Documentation

Authentication

The Ask Xverum API uses API keys for authentication. Each request must carry your key in the x-api-key HTTP header.

How it works

POST /v1/search HTTP/1.1
Host: search-api.xverum.com
x-api-key: XVERUM-API-KEY
Content-Type: application/json

Every authenticated request is validated against the Xverum user-management service, which confirms the API key resolves to an active account. If it does not, the request is rejected before any search work is done. See the errors below. Validation results are cached briefly to avoid a round-trip on every request.

The key is a long-lived credential — there is no token-exchange step and no expiry on the key itself. Rotate it through user-management.

Getting a key

Your API keys are available to view and manage directly in your Xverum dashboard — no need to contact support.

Treat the key like a password:

Never commit it to source control.
Never embed it in browser-side code — keys belong on a server you control.
Rotate keys periodically and on any suspected leak.

One key, one account

Multiple API keys for the same Xverum account share one credit balance. Each key has its own rate-limit bucket (60 requests/minute by default — see Rate limits). The keys exist for rotation and for labelling distinct integrations.

Error format

Every API error returns a structured envelope with a stable, machine-readable code:

{
  "error": {
    "code": "out_of_credits",
    "message": "Out of credits. Top up to continue.",
    "request_id": "9f1c2a7e6b3d4f08",
    "upgrade_url": "https://myaccount.xverum.com/plans"
  }
}

`code` — a value from a documented closed enum. Branch on this, never on message.
`message` — human-readable, may be reworded at any time. Do not parse it.
`request_id` — the same id returned in the X-Request-Id response header; quote it in support tickets.
`upgrade_url` — present only on the 402 out_of_credits error; a URL to top up credits. Optional — absent on every other error.

Treat unknown error.code values as forward-compatible: map any code you don't recognise to your generic failure handling keyed off the HTTP status.

Errors

Status	`error.code`	Meaning	What to do
`401`	`invalid_api_key`	Missing or invalid API key.	Check the `x-api-key` header is present and spelled exactly.
`402`	`out_of_credits`	Credit balance is zero or negative.	Top up the account before retrying.
`403`	`account_not_authorized`	Account is not authorized.	Contact Xverum support.
`429`	`rate_limited`	Rate limit exceeded.	Wait for `Retry-After` seconds and retry. See Rate limits.

See each endpoint reference for the full per-endpoint error list (Search, Profiles).