API conventions

Base URL, content types, timestamps, money, IDs, pagination, and versioning shared by every CognitiveX endpoint.

These rules hold across the whole API. Read them once and you can predict the shape of any endpoint you haven't seen yet. For credentials, see Authentication.

Base URL

All product endpoints live under a single host with the /api prefix:

https://api.cognitivx.io/api

So recall is POST https://api.cognitivx.io/api/recall, remember is POST https://api.cognitivx.io/api/remember, and so on. There is no separate sandbox host: use a free-tier account and disposable keys for testing.

Content types

Send and receive JSON.

Header	Value
`Content-Type`	`application/json` (on any request with a body)
`Accept`	`application/json` (optional; JSON is the only response format)

Authenticate with either header on every call:

Authorization: Bearer icog_xxx

X-API-Key: icog_xxx

Both are equivalent on /api routes. A key passed as a bearer token works because any Authorization: Bearer value beginning with icog_ is treated as an API key.

Every response carries an X-Request-ID header (a hex UUID). Include it when you report a problem so it can be traced in the logs.

Timestamps

All timestamps are ISO 8601 strings in UTC, for example 2026-06-16T08:30:00Z. This applies to every time field returned by the API, including created_at, occurred_at, and last_used_at. The API does not return Unix epoch numbers.

Money and credits

The user-facing billing unit is the credit, an integer. Balances are returned as credits, with a USD equivalent alongside for display only.

{
  "balance_credits": 4200,
  "balance_usd": 4.2,
  "low_balance": false,
  "depleted": false
}

Credits are the unit you meter and budget against. The USD figure is a convenience for showing users a dollar value; do not treat it as the source of truth for billing logic. See Billing and usage.

There is no amount_cents field in this API. If you are porting code that expects integer minor units, map it to balance_credits (credits) and read balance_usd only for presentation.

IDs

Resource IDs (users, sessions, messages, memories, organizations) are UUIDs, serialized as strings:

{ "memory_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" }

There are no typed ID prefixes (no mem_, key_, or usr_ style prefixes). The only prefix convention in the system is on API keys, which always start with icog_. When a key is created, the response also returns a short key_prefix (the first eight characters, e.g. icog_abc) so you can identify a key later without storing the secret.

Lists and pagination

Most list endpoints page with limit and offset.

Param	Type	Default	Notes
`limit`	int	varies	Page size. Capped per endpoint (commonly 50, 100, 200, or 500).
`offset`	int	`0`	Number of records to skip. Must be `>= 0`.
`q`	string	none	Free-text search filter, where supported.

To page through a list, increase offset by limit until you receive fewer items than you asked for.

List responses are not wrapped in a uniform envelope. They return the items under a named key plus a count. The key is usually the resource plural (or items). For example, recall returns:

{
  "memories": [
    {
      "id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "text": "User prefers TypeScript examples.",
      "memory_type": "semantic",
      "age_days": 12,
      "created_at": "2026-06-04T10:22:11Z",
      "occurred_at": null,
      "similarity": 0.83
    }
  ],
  "count": 1
}

A small number of administrative and audit endpoints page with page (1-indexed) and page_size instead of limit/offset. Each endpoint's reference entry states which it uses. There is no global next_cursor field.

Idempotency

CognitiveX does not support an Idempotency-Key request header. Retrying a write is not automatically deduplicated at the HTTP layer, so a retried POST /api/remember can store a second memory.

If a write times out or fails ambiguously, prefer to recall and confirm the state before retrying, rather than assuming the first call did nothing.

Versioning

The API is unversioned. There is no /v1 path segment and no Accept-Version or X-API-Version header. Endpoints live directly under /api (for example /api/recall), and the OpenAPI document reports a single API version of 1.0.0.

Changes are additive where possible: new fields may appear on responses, so parse defensively and ignore fields you do not recognize. Breaking changes are announced before they ship.

Internal phase or release numbers you may see in marketing or changelogs are not API versions. Pin your integration to endpoint paths and field names, not to those numbers.

Errors

Errors are returned as JSON with the standard detail field and the matching HTTP status code:

{ "detail": "Invalid API key" }

For validation failures (HTTP 422), detail is an array describing each problem:

{
  "detail": [
    { "loc": ["body", "query"], "msg": "field required", "type": "value_error.missing" }
  ]
}

Some gated and quota errors return a structured object in detail instead of a string. The common status codes:

Status	Meaning
`200`	Success with a body.
`201`	Resource created.
`204`	Success with no body (most deletes).
`400`	The request was understood but rejected (invalid input).
`401`	Missing or invalid credentials.
`403`	Authenticated but not allowed (for example, email not verified, or tier too low).
`404`	Resource does not exist or is not yours.
`409`	Conflict (for example, a duplicate signup).
`422`	Request body or params failed validation.
`429`	Rate limit or usage quota exceeded. See Rate limits.
`500`	Unexpected server error. The body includes `path` for tracing.
`503`	A dependency is not ready. Retry shortly.

On an unexpected 500, the body also includes the request path:

{ "detail": "Internal server error", "path": "/api/recall" }

Pair that with the X-Request-ID header when you ask for help.

What's next

Authentication — keys, bearer tokens, and sessions.
Rate limits — quotas and the 429 you will actually hit.
API reference — every endpoint with its parameters and responses.

On this page