Getting Started

Authentication

HyperSearchX uses API keys for authentication. All requests (except /health) require a valid API key in the Authorization header.

API key format

API keys are prefixed with hsx_ followed by 64 lowercase hexadecimal characters, giving 256 bits of entropy:

text

hsx_4626d3fc3fd6693aaaf2d8f5fd084a71320f48e0e94904ff9dc9a1064b4bb998

Using your API key

Pass the key as a Bearer token in the Authorization header on every request:

bash

curl -X POST https://api.hypersearchx.zuhabul.com/v1/search \
  -H "Authorization: Bearer hsx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async programming", "tier": "summary"}'

Security: Never expose your API key in client-side code, public repositories, or logs. Always load it from environment variables.

Getting an API key

Sign up at app.hypersearchx.zuhabul.com
Navigate to API Keys in the sidebar
Click Create Key
Copy the key immediately — it is shown only once

One-time display: The full key is shown only at creation time. After you navigate away, only the last 8 characters are shown. Store the key in a password manager or secrets vault before closing the dialog.

Key management

List your keys

bash

curl https://api.hypersearchx.zuhabul.com/v1/keys \
  -H "Authorization: Bearer hsx_your_key"

response.json

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "Production",
      "prefix": "hsx_4626...bb98",
      "created_at": "2025-01-15T10:22:00Z",
      "last_used_at": "2025-06-20T14:30:00Z",
      "scopes": ["search", "research", "scrape"]
    }
  ]
}

Create a key

bash

curl -X POST https://api.hypersearchx.zuhabul.com/v1/keys \
  -H "Authorization: Bearer hsx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline", "scopes": ["search"]}'

Revoke a key

bash

curl -X DELETE https://api.hypersearchx.zuhabul.com/v1/keys/key_abc123 \
  -H "Authorization: Bearer hsx_your_key"

Error responses

Status	Code	Cause
`401`	`missing_auth`	No Authorization header
`401`	`invalid_auth`	Malformed Bearer token
`401`	`invalid_key`	Key not found or revoked
`403`	`insufficient_scope`	Key lacks required scope
`429`	`rate_limited`	Quota or per-minute limit exceeded

401-response.json

{
  "error": {
    "code": "invalid_key",
    "message": "API key not found or has been revoked.",
    "request_id": "req_01j8xk3..."
  }
}

Environment variable setup

.env

# Add to your .env or secrets manager
HSX_API_KEY=hsx_4626d3fc3fd6693aaaf2d8f5fd084a71...

client.ts

const HSX_API_KEY = process.env.HSX_API_KEY;
if (!HSX_API_KEY) throw new Error("HSX_API_KEY is not set");

const headers = {
  "Authorization": `Bearer ${HSX_API_KEY}`,
  "Content-Type": "application/json",
};

client.py

import os

HSX_API_KEY = os.environ["HSX_API_KEY"]  # raises KeyError if missing
HEADERS = {
    "Authorization": f"Bearer {HSX_API_KEY}",
    "Content-Type": "application/json",
}

Key rotation

Rotate keys regularly and immediately if compromised. The recommended workflow:

Create a new key in the dashboard
Deploy the new key to your environment
Verify requests are working with the new key
Revoke the old key

Next steps

Quick Start →

Make your first API call

Rate Limits →

Understand quotas and headers

Search API →

Full search reference

Error Reference →

All error codes explained