Authentication

Every request to a data endpoint (/api/v1/..., /api/v2/...) must carry an API key in the x-api-key header. The header is the only accepted mechanism: keys in a query parameter or an Authorization: Bearer header are not read and the request is rejected with 401.

System endpoints (/health, /about, /services, /sources) are public and need no key.

API keys

Keys look like sugra_ab1_ followed by a 24-character random suffix. Treat the whole string as the secret.

Manage keys in the dashboard at app.sugra.ai (Developer, Keys):

Create up to 5 keys per account. Each key gets its own usage counter and its own daily quota, all inherited from your account plan.

Rotate a key at any time. Rotation issues a new random suffix and invalidates the old key immediately.

Delete keys you no longer use. At least one key must remain; to replace your last key, rotate it instead of deleting.

There is no key expiry. A key stays valid until you rotate or delete it, or the account plan changes it.

Error responses

Status	Meaning	What to do
401	Missing or invalid `x-api-key`	Send a current key from the dashboard
403	Not used for key errors on data endpoints	See note below
429	Daily request quota exhausted	Wait for the UTC midnight reset or upgrade the plan

401 Unauthorized

Both a missing key and an unrecognized key return 401. The response body is an HTML help page (Content-Type: text/html) that points humans at the onboarding flow, so branch on the status code, not the body:

HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=utf-8

<!DOCTYPE html>
...
<h1>401 - Unauthorized</h1>
<p>A valid <code>X-API-Key</code> header is required to access this endpoint.</p>

A syntactically valid but revoked or rotated-away key gets the same 401. There is no separate status for "expired": if the key is rejected, it is always 401.

403 Forbidden

Data endpoints do not use 403 for authentication. A 403 from sugra.ai means the path itself is restricted (internal, non-public surfaces), not that your key is wrong. Client retry logic should treat 401 as "fix the key" and 403 as "this route is not for API keys".

429 Too Many Requests

Each key has a daily request quota set by the plan (see Rate limits and errors). The counter resets at UTC midnight. Over quota, requests return 429 with a JSON body and a Retry-After header giving the whole seconds until the reset:

HTTP/1.1 429 Too Many Requests
Retry-After: 19722
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-07-18T23:59:59Z

{"detail": "Daily limit of 50 requests reached. Current plan: free"}

Rate limit headers

Every authenticated response includes the current quota state:

HTTP/1.1 200 OK
x-ratelimit-limit: 1000000
x-ratelimit-remaining: 999968
x-ratelimit-reset: 2026-07-18T23:59:59Z

X-RateLimit-Limit - the key's daily quota

X-RateLimit-Remaining - requests left today

X-RateLimit-Reset - the UTC timestamp when the counter resets

Header names are case-insensitive; HTTP/1.1 responses emit them lowercase.

Key security

Call the API from your server or agent backend only. Never embed a key in browser JavaScript, mobile app binaries, or public repositories: anything shipped to a client is public.

Load the key from an environment variable or secret store, not from source code.

If a key leaks, rotate it in the dashboard immediately. The old value stops working at once and your integrations only need the new suffix.

Use separate keys per application or environment (each of the 5 has its own usage counter), so one leak is contained by one rotation.

API keys#

Error responses#

401 Unauthorized#

403 Forbidden#

429 Too Many Requests#

Rate limit headers#