REST API overview

Base URL, JWT auth, correlation IDs, errors, limits, and retries.

In Python, prefer the SDK. It handles token exchange and refresh for you. Use this page for curl, other languages, or raw HTTP debugging.

Quick reference

Topic	Where
Live host	https://api.getmetacognition.com
Auth header	Authorization: Bearer <access_token>
Get tokens	POST /auth/token-exchange
Trace failures	X-Correlation-ID + JSON request_id
Limits & metering	Usage, quotas, and billing

The API is small, and auth works the same way across it: /me, /ingestion/memory, /recall, and /usage/*.

Base URL

https://api.getmetacognition.com

Auth

Every product endpoint expects:

Authorization: Bearer <access_token>

Create <access_token> by posting your API key to POST /auth/token-exchange. Then send it like any other short-lived bearer token.

Content type

Always:

Content-Type: application/json

Correlation IDs

Each request can include an X-Correlation-ID UUID. If you do not send one, the server creates one. The SDK always sends one so your logs and ours match. Include this value in support threads.

X-Correlation-ID: 4f1d8e3c-2a9b-4c0d-9e6f-1a2b3c4d5e6f

HTTP errors

Standard HTTP status codes:

Status	Meaning
200	OK
201	Created (signup, key creation)
202	Accepted (async ingestion)
204	No content (key revoke)
400	Bad payload
401	Auth failure
403	Forbidden
404	Not found
422	Validation error (FastAPI request format)
429	Daily quota exceeded
5xx	Tex platform fault. Retry with backoff, then escalate with the correlation ID.

Error body:

{
  "error": "HTTP 401",
  "message": "Invalid token",
  "details": null,
  "timestamp": "2026-05-08T10:00:00Z",
  "request_id": "..."
}

Rate limits

Limits are per organization. The free tier allows 1,000,000 tokens_in and 5,000,000 tokens_out each UTC day. Both reset at 00:00 UTC. Usage, quotas, and billing explains how this appears in responses and dashboards.

Retries

Retry twice with exponential backoff on 408, 500, 502, 503, 504, and hard network failures. Respect Retry-After when the API sends it.

Do not retry 400, 401, 403, 404, 422, or quota 429. A replay will usually fail the same way.

Endpoints

Auth

/signup · /auth/token-exchange · /auth/refresh

Account

/me · /me/api-keys

Memory

/ingestion/memory · /recall

Usage

/usage/today · /usage/summary