> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API key, host, and request conventions for the Video Datalake.

## Get a key

Create and manage keys in the **[Developer Console](https://console.memories.ai/)** — it is also where you top up your balance, watch usage, and configure webhooks. Keys look like `sk-mai-…`; treat one as a password.

## API key & host

Every request carries your Memories.ai key in the `Authorization` header:

```
Authorization: sk-mai-<your key>
```

* Missing / invalid key → `401`. A scoped key used outside its scope → `403`.
* Store the key in an environment variable (e.g. `MEMORIES_API_KEY`); never hard-code it.

All Datalake endpoints live under one base path:

```
https://api.memories.ai/datalake/v1
```

## Request conventions

| Header            | Description                                                                                                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-Request-ID`    | Optional, `[A-Za-z0-9_.-]{1,128}`. Auto-generated (`req_` prefix) if omitted. Provide it when reporting an issue.                                                                                      |
| `Idempotency-Key` | Idempotency key for writes (≤128 chars). Same key + same request → replays the first response; same key + different request → `409`. **`POST /videos` uses the `idempotency_key` body field instead.** |

Responses always echo `X-Request-ID`, carry `X-RateLimit-Limit / -Remaining / -Reset`, and send `Retry-After` on `429` / `503` / `409 (video_not_ready)` / `500`.

## IDs & state

* **Prefixes**: `col_` / `vid_` / `op_` / `per_` / `fce_` / `ent_` / `evt_` / `spk_` / `req_` (prefix + 26-char lowercase base32).
* **Video / Person state**: `processing → ready | failed`.
* **Moment ref**: `{video_id}@{start}-{end}` in seconds (omit `@` for the whole video).

## Pagination

| Cursor                   | Where                      | How                                                                                                                                                                                    |
| ------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` / `next_cursor` | List endpoints             | Pass `next_cursor` as `cursor=`; `null` means the end.                                                                                                                                 |
| `since`                  | Derived-content increments | `?since=` (empty) for the first page, then the previous `next_cursor`; `live: true` means indexing is still running. Bound to the (video, endpoint) pair — don't mix across endpoints. |

## SDKs

The Datalake is **REST-first** — every example is copy-paste `curl` and Python `requests`. Official SDKs are on the way.