Authentication & Headers

This page covers the base URL, API Key authentication, request trace IDs, and the headers the contract declares but the API does not implement yet.

1. Base URL and request format

Item	Value
Base URL	`https://api.sequenxai.com/v1`
Live endpoints	`POST /v1/forecast`, `POST /v1/clean`
Request body	A UTF-8 JSON object; unparseable bodies return 400 `MALFORMED_JSON`, non-objects return 422 `VALIDATION_ERROR`
Response body	JSON; every error uses the `{"error": {...}}` envelope, see Error Codes

The OpenAPI paths /anomaly-detection, /batch/forecast, /batch/jobs/{job_id} and the https://api.sequenxai.com/cn/v1 prefix are not open yet; the three operations are labelled "Not yet available" (x-availability: planned) in the OpenAPI reference and return 404.

2. API Keys

Every request carries a tenant key:

authorization-header

Authorization: Bearer sqx_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys are created on the API Keys page of the SequenxAI Platform at platform.sequenxai.com; the full plaintext is shown once, at creation. The service stores only a digest, so a key cannot be recovered: delete a lost key on the API Keys page and create a new one. Deletion takes effect immediately and cannot be undone: requests with that key then get a 401, and the key no longer appears in the list (the usage page still attributes its past usage by name).

Situation	HTTP	`error.code`
No `Authorization`, not `Bearer <key>`, unknown, deleted or revoked key	401	`INVALID_API_KEY` (with `WWW-Authenticate: Bearer`)
A `sqx_test_*` test key	401	`INVALID_API_KEY`: the live API accepts `sqx_live_*` only
The key lacks the `forecast:write` scope	403	`INSUFFICIENT_SCOPE`: keys created on the platform carry it by default
The key's account or workspace is suspended by SequenxAI (beta)	403	`ACCOUNT_SUSPENDED`: the key stays valid and works again once restored; contact support
The key's workspace is in its deletion cool-off (beta)	403	`ORG_PENDING_DELETION`: keys work again once the deletion is cancelled on the platform

3. Request IDs

The service generates a req_… ID for every request, failed ones included. It appears in:

the X-Request-Id response header;
request_id in a success body, or error.request_id in an error body.

Quote this ID when you contact support.

You can also send your own trace ID in the X-Request-Id request header. It must match ^[A-Za-z0-9_-]{8,64}$; when it does, it is echoed in the X-Client-Request-Id response header and stored with the usage record. Values that do not match are ignored silently and not echoed. Your ID only correlates logs: it never replaces the server ID and is never used as an idempotency key.

4. Request headers

Header	Status	Notes
`Authorization`	Required	`Bearer sqx_live_…`
`Content-Type`	Recommended	`application/json`
`X-Request-Id`	Optional	Your trace ID, rules above
`Idempotency-Key`	Optional	`/v1/forecast` only: 1–255 printable ASCII characters, scoped to the API Key, kept 24 hours; rules below. The old `X-Idempotency-Key` is a deprecated alias accepted for one more release
`X-SequenX-Region`	Not read	Contract-reserved region hint; does not affect routing today

5. Response headers

Header	When	Notes
`X-Request-Id`	Always	The server-generated `req_…`
`X-Client-Request-Id`	You sent a valid `X-Request-Id`	Echo of your trace ID
`Retry-After`	429; 503 `MODEL_BUSY`; 503 `SERVICE_UNAVAILABLE` when the service is paused or cleaning is at capacity	Seconds to wait
`X-RateLimit-Limit` / `-Remaining` / `-Reset` / `-Limit-Type` / `-Policy`	Every response once the key is authenticated	Normally the per-minute request limit of the key's account (shared by all its keys); on a 429, the bucket that was exhausted. See Metering, Quotas & Rate Limits
`X-Idempotent-Replayed`	Idempotent replay	Always `true`: this response is the stored result of the first request with the same idempotency key
`Deprecation`	You sent only `X-Idempotency-Key`	Always `@1791417600` (RFC 9745: deprecated since 2026-10-08T00:00:00Z): switch to `Idempotency-Key`
`WWW-Authenticate`	401	Always `Bearer`

IMPORTANT

Retrying safely with an idempotency key

Generate one unique Idempotency-Key per logical request (an order number or a UUID, for example) and send the same key with the exact same body on every retry. Keys are scoped to the API Key and kept for 24 hours:

The first request's final outcome (a success, or a deterministic 4xx such as a validation error) is stored. A retry with the same key and body returns that result as-is, with the original request_id and the response header X-Idempotent-Replayed: true; nothing runs or is billed again. Bodies are compared as JSON, so key order and whitespace do not matter.
The same key with a different body returns 422 IDEMPOTENCY_KEY_REUSED. A duplicate that arrives while the first request is still running returns 409 IDEMPOTENCY_IN_PROGRESS; retry a little later to receive the stored result.
X-Idempotency-Key still works for one more release as a deprecated alias: sent alone, it is used as the key and the response carries Deprecation: @1791417600. Sending both headers with different values returns 400 VALIDATION_ERROR.
A replay is not billed, but it still counts against the per-minute request limit.
Upstream 5xx, timeouts, service unavailability, and 401, 403 and 429 are not stored, so a retry with the same key runs again. Neither are 422s that depend on platform configuration rather than the body itself: a model that is not available (MODEL_NOT_AVAILABLE), POINTS_EXCEEDED, HORIZON_EXCEEDS_MODEL, SERIES_TOO_LONG and QUANTILE_UNSUPPORTED.
Without the header nothing changes: every retry is a new request, and a retry after a client timeout or dropped connection may bill twice.

Give /v1/forecast a generous client timeout (for example 180 seconds) and tag each attempt with your own X-Request-Id.