REST API

Everything the portal and MCP tools do goes through the REST API. Use it for scripts, integrations, and anything a client cannot do over MCP.

#Base URL and schema

https://api.animawake.com

The full, generated reference is public:

• Swagger UI: api.animawake.com/api/docs/
• OpenAPI schema: api.animawake.com/api/schema/

This page covers the conventions the schema does not explain.

#Authentication

Send a key as a bearer token:

curl https://api.animawake.com/api/startup/ \
  -H "Authorization: Bearer ent_your_key_here"

Only the Authorization: Bearer header is accepted. Headers such as X-API-Key are ignored, and keys in query strings are never accepted.

#Key types

See Access tokens and keys for how to create, rotate, and revoke keys.

#Portal sessions

The portal authenticates with a session cookie. If you call the API from a browser session, send X-Animawake-Preflight: 1 on writes; it is required for requests with form, multipart, plain-text, or empty bodies. Three session endpoints also require an X-Animawake-Client header with any non-empty value: VRM upload (POST /api/vrm-library/), VRM delete (DELETE /api/vrm-library/<id>/), and voice profile upload (POST /api/families/<workspace>/<entity>/voice-profile/).

#URL shapes

• Entity endpoints: /api/<resource>/, with an ent_ key. Examples: /api/moments/, /api/insights/, /api/decisions/, /api/sessions/, /api/memory/search/.
• Workspace endpoints: /api/families/<workspace-slug>/.... Examples: /api/families/<workspace>/entities/, /api/families/<workspace>/entities/<entity>/api-keys/.
• Entity endpoints addressed through a workspace: /api/families/<workspace-slug>/<entity-slug>/..., for example set-engine/ and continuity/export/.

In paths and in the API, a workspace is called a family.

#Examples

Load startup context:

curl https://api.animawake.com/api/startup/ \
  -H "Authorization: Bearer ent_your_key_here"

Record a moment:

curl -X POST https://api.animawake.com/api/moments/ \
  -H "Authorization: Bearer ent_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"event": "Shipped the importer", "tags": ["MILESTONE"], "date": "2026-09-27"}'

Search memory:

curl -X POST https://api.animawake.com/api/memory/search/ \
  -H "Authorization: Bearer ent_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "importer launch", "limit": 5}'

limit is 1 to 100 (default 10). threshold is 0 to 3 (default 1.5); lower values return only closer matches.

#Pagination

List endpoints are paginated by page number, 50 items per page:

curl "https://api.animawake.com/api/moments/?page=2" -H "Authorization: Bearer ent_your_key_here"

{
  "count": 134,
  "next": "https://api.animawake.com/api/moments/?page=3",
  "previous": "https://api.animawake.com/api/moments/?page=1",
  "results": [ ... ]
}

Follow next until it is null. Some endpoints return their own shape instead, such as {"tokens": [...]}; the schema shows each response.

#Errors

Errors use standard HTTP status codes and a JSON body with an error key:

{ "error": "Entity name does not match. Retirement cancelled." }

Validation errors put field messages under error:

{ "error": { "name": ["This field is required."] } }

A few endpoints return field messages at the top level, as {"query": ["This field is required."]}, or add extra keys next to error. Check error first, then fall back to the whole body.

#Rate limits

Limits apply per endpoint group, counted per entity, per user, or per IP address. A limited request returns 429:

{ "error": "Request was throttled. Expected available in 42 seconds." }

Resonance checks (/api/memory/check-resonance/) and reading traces have no rate limit. The MCP server has separate limits; see Connection troubleshooting.

#Useful endpoints

The MCP tools reference is also a guide to the entity endpoints: each tool is a thin wrapper around one or two of them.