Authentication - Memories.ai API

Get a key

Create and manage keys in the Developer Console — 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.