> ## Documentation Index
> Fetch the complete documentation index at: https://metacognition-fdc534de-master.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API overview

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

<Info>
  In Python, prefer the [SDK](/sdk/installation). It handles token exchange and refresh for you. Use this page for curl, other languages, or raw HTTP debugging.
</Info>

## Quick reference

| Topic             | Where                                                             |
| ----------------- | ----------------------------------------------------------------- |
| Live host         | `https://api.getmetacognition.com`                                |
| Auth header       | `Authorization: Bearer <access_token>`                            |
| Get tokens        | [`POST /auth/token-exchange`](/api-reference/auth/token-exchange) |
| Trace failures    | `X-Correlation-ID` + JSON `request_id`                            |
| Limits & metering | [Usage, quotas, and billing](/concepts/usage-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:

```http theme={null}
Authorization: Bearer <access_token>
```

Create `<access_token>` by posting your API key to [`POST /auth/token-exchange`](/api-reference/auth/token-exchange). Then send it like any other short-lived bearer token.

## Content type

Always:

```http theme={null}
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.

```http theme={null}
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:

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

## Rate limits

<Info>
  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](/concepts/usage-billing) explains how this appears in responses and dashboards.
</Info>

## 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

<CardGroup cols={2}>
  <Card title="Auth" icon="key" href="/api-reference/auth/signup">
    /signup · /auth/token-exchange · /auth/refresh
  </Card>

  <Card title="Account" icon="user" href="/api-reference/account/me">
    /me · /me/api-keys
  </Card>

  <Card title="Memory" icon="brain" href="/api-reference/memory/ingest-memory">
    /ingestion/memory · /recall
  </Card>

  <Card title="Usage" icon="receipt" href="/api-reference/usage/today">
    /usage/today · /usage/summary
  </Card>
</CardGroup>