API overview

The Cortex API is an HTTP API for building applications and automation on Cortex. It follows the same rules on every endpoint — base URL, authentication, identifiers, errors, pagination, and timestamps. Read this page once and the rest of the reference is predictable.

Base URL and versioning

Every developer-facing endpoint lives under a single base URL with the version prefix /v1.

https://api.cortex.cognit-dx.com/v1/

The version prefix is mandatory. There is no unversioned route — every call you make must include /v1. When breaking changes ship, they ship under a new version (/v2) and existing clients continue to receive the contract they were built against.

A handful of operational endpoints (such as /health) sit outside the versioned surface. These are not part of the public contract and may change without notice.

Authentication

Every request must include a bearer token in the Authorization header.

curl https://api.cortex.cognit-dx.com/v1/threads \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Treat the token as an opaque string. Do not parse it, do not decode it, do not rely on its internal structure. The token format is an implementation detail and may change without breaking the contract.

Two distinct error statuses are used for auth:

Tokens must never be placed in URL query strings or path segments — they will appear in server logs and browser history. Header only.

Identifiers

Every resource has an id field that uniquely identifies it within the platform. IDs are version-4 UUIDs serialized as lowercase hyphenated strings.

"id": "9f7c9d3a-2b1e-4c5f-bd91-7e2c4a8d6f10"

IDs are stable for the lifetime of a resource and are never reused. A deleted resource's ID will never refer to another resource later. IDs are opaque — do not infer creation order or resource type from them.

When a request requires a resource ID in the URL, use the full UUID string exactly as it was returned by the API.

GET /v1/threads/9f7c9d3a-2b1e-4c5f-bd91-7e2c4a8d6f10

Timestamps

Every timestamp is an ISO 8601 string with millisecond precision in UTC, indicated by the trailing Z.

"created_at": "2026-05-17T14:32:11.123Z"

Timestamps are returned in standard fields with consistent names across every resource:

Clients should always parse timestamps as UTC. Local-time display is a client concern.

Pagination

List endpoints use opaque cursor pagination. Cursors are stable under concurrent writes — items will not appear twice or be skipped if the underlying collection changes while you page through it.

Two query parameters control paging:

Every list response has the same envelope:

{
  "data": [
    { "id": "9f7c9d3a-...", ... },
    { "id": "a1b2c3d4-...", ... }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImExYjJjM2Q0LSJ9"
}

Endpoints under /v1/admin/* additionally carry a total integer in the envelope so operator UIs can render absolute counts; everything else returns the three fields above.

First page:

curl "https://api.cortex.cognit-dx.com/v1/threads?limit=20" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Next page — pass the next_cursor from the previous response as cursor:

curl "https://api.cortex.cognit-dx.com/v1/threads?limit=20&cursor=eyJpZCI6ImExYjJjM2Q0LSJ9" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

When has_more is false, you have reached the end of the collection. next_cursor is also null on the final page.

Treat the cursor as an opaque string — do not parse or construct it yourself. Its internal shape may change without breaking the contract.

Errors

Every failed request returns the same flat envelope — a human-readable error message, a stable machine-readable code, and the request_id for support correlation.

{
  "error": "Email is already in use by another user in this organization.",
  "code": "duplicate_email",
  "request_id": "req_9f7c9d3a-2b1e-4c5f-bd91-7e2c4a8d6f10"
}

Branch on the HTTP status code for broad categories (4xx is a client problem; 5xx is ours), and on code when you need to react to a specific failure. See the Errors reference for the full status code table, the error code catalog, and per-code semantics.

Request IDs

Every response — successful or not — carries a unique request identifier in the X-Request-Id header.

X-Request-Id: req_9f7c9d3a-2b1e-4c5f-bd91-7e2c4a8d6f10

Error responses also include the same value in the request_id field of the response body. When something goes wrong, capture the request ID and include it in any support request. It lets us correlate your request with our server-side logs in a single lookup.

Organization scoping

Cortex is multi-organization. Every resource (thread, document, run, agent, workflow, project) belongs to exactly one organization. The organization is determined automatically from your authentication token; you never need to specify it in a URL or request body.

This has two consequences:

• Resources you create are automatically tagged with your organization.
• List, read, update, and delete operations only see and act on resources that belong to your organization. A resource in another organization returns 404 — its existence is not revealed.

Cross-organization administration (creating organizations, managing users across organizations, configuring platform-wide AI providers and plans) is a separate surface used by Cortex operators. It is not part of the developer API and is not documented here.