> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thrindex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Thrindex REST API. Base URL, authentication, endpoints, and request/response conventions.

## Base URL

```
https://api.thrindex.com
```

All endpoints are versioned under `/v1`. JSON request and response bodies. Unknown fields in request bodies are rejected with `400 validation_error`.

***

## Authentication

Every request requires a Bearer token:

```
Authorization: Bearer th_live_<64 hex characters>
```

API keys are created in the [dashboard](https://app.thrindex.com). See [Authentication & Security](/concepts/authentication) for details on scopes, rotation, and best practices.

***

## Endpoints

| Method   | Path                                                    | Scope           | Description                             |
| -------- | ------------------------------------------------------- | --------------- | --------------------------------------- |
| `POST`   | [`/v1/memories`](/api-reference/memories/create)        | `memory:write`  | Store a memory for async processing     |
| `POST`   | [`/v1/memories/search`](/api-reference/memories/search) | `memory:read`   | Search memories by semantic similarity  |
| `GET`    | [`/v1/memories`](/api-reference/memories/list)          | `memory:read`   | List memories with cursor pagination    |
| `GET`    | [`/v1/memories/{id}`](/api-reference/memories/get)      | `memory:read`   | Fetch a single memory including content |
| `DELETE` | [`/v1/memories/{id}`](/api-reference/memories/delete)   | `memory:delete` | Delete a memory (soft or hard)          |

### Health check

```
GET /healthz
```

No authentication required. Returns `200 {"status":"ok"}` when the API is healthy. Use for uptime monitoring and load balancer health checks.

***

## Request conventions

* All request bodies must be `application/json`.
* The `org_id` is never accepted in a request body — it is derived from your API key.
* Unknown fields in request bodies are rejected with `400 validation_error`.
* Maximum request body size: `content` field up to 8192 bytes plus 16 KB overhead for JSON structure and metadata. Search request bodies are limited to 8 KB.

***

## Response conventions

All successful responses are `application/json`.

| Endpoint                   | Success status   |
| -------------------------- | ---------------- |
| `POST /v1/memories`        | `202 Accepted`   |
| `POST /v1/memories/search` | `200 OK`         |
| `GET /v1/memories`         | `200 OK`         |
| `GET /v1/memories/{id}`    | `200 OK`         |
| `DELETE /v1/memories/{id}` | `204 No Content` |

All timestamps are ISO 8601 strings in UTC (e.g. `"2026-05-24T17:00:00.000Z"`).

***

## Error format

All errors follow a consistent envelope:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "agent_id is required",
    "request_id": "req_01j..."
  }
}
```

The `request_id` is unique per request. Include it when contacting support.

See [Errors](/api-reference/errors) for the complete list of codes and HTTP statuses.

***

## Rate limits

Rate limits are enforced per API key. When exceeded, the API returns `429 Too Many Requests` with a `Retry-After: 1` header.

Both the Python and TypeScript SDKs respect `Retry-After` automatically and retry without extra configuration. If you are using the REST API directly, implement exponential backoff and respect the `Retry-After` header.

Response headers on every authenticated request:

* `X-RateLimit-Limit` — your key's configured requests-per-second limit
* `X-RateLimit-Remaining` — remaining requests in the current window