REST API Overview

The Estuary REST API lets you manage characters, read conversation history, and query the memory system programmatically. All endpoints return JSON.

Base URL

https://api.estuary-ai.com

Authentication

Authenticate every request with an X-API-Key header:

curl https://api.estuary-ai.com/api/v1/characters \
  -H "X-API-Key: est_your_api_key"

Generate API keys from the Estuary Dashboard under Settings > API Keys. See Authentication for details.

Keys carry scopes that decide which resources they can reach, for example memories:read or characters:write. A key that lacks the scope a route needs gets a 403 with "error": "insufficient_scope". See API key scopes.

Player Scoping

The Characters and Character Generation APIs accept an optional X-Player-Id header. When present, operations are scoped to characters owned by that player. See Characters API -- Authentication & Player Scoping for the full rules.

Permanent Shares

The Shares API lets you mint permanent or expiring shareable links for a character. Permanent shares are designed for physical carriers (NFC tags, QR codes, print) and never expire. Once a recipient calls POST /api/v1/share/{id}/open, they receive a short-lived session token (sst_...) that the SDK uses in place of an API key.

Endpoints

Method	Path	Description
POST	/api/v1/characters	Create a character
GET	/api/v1/characters	List characters
GET	/api/v1/characters/{id}	Get a character
PUT	/api/v1/characters/{id}	Update a character
DELETE	/api/v1/characters/{id}	Delete a character
POST	/api/v1/characters/batch	Create up to 100 characters with knowledge documents fetched by URL
GET	/api/v1/characters/batch/{id}	Poll a batch
GET	/api/v1/characters/batch	List batches
POST	/api/v1/characters/batch/{id}/retry	Retry failed items and documents
POST	/api/v1/characters/batch/{id}/cancel	Cancel queued work in a batch
POST	/api/v1/characters/{id}/documents	Add a knowledge document by URL
GET	/api/v1/characters/{id}/documents	List a character's documents
DELETE	/api/v1/characters/{id}/documents/{documentId}	Remove a document
GET	/api/v1/characters/documents/{documentId}	Poll a knowledge document
GET	/api/v1/characters/documents/{documentId}/view-url	Get a short-lived download link for a document
PUT	/api/v1/characters/{id}/avatar	Upload a character avatar image
PUT	/api/v1/characters/{id}/model-file	Upload a character 3D model file
POST	/api/v1/characters/from-image	Generate a character from an image
POST	/api/v1/characters/{id}/model	Trigger 3D model generation
GET	/api/v1/characters/{id}/model	Poll 3D model generation status
POST	/api/v1/share	Create a share (expiring or permanent)
POST	/api/v1/share/{id}/open	Open a permanent share (unauthenticated)
GET	/api/v1/share/character/{character_id}	List shares for a character
DELETE	/api/v1/share/{id}	Revoke a share
DELETE	/api/v1/share/by-api-key/{api_key_id}	Bulk revoke shares by API key
GET	/api/v1/characters/{id}/players/stats	Conversation stats
GET	/api/v1/characters/{id}/players	List conversations
GET	/api/v1/characters/{id}/players/{player_id}	Get a conversation
GET	/api/v1/characters/{id}/players/{player_id}/messages	Get messages
DELETE	/api/v1/characters/{id}/players/{player_id}	Delete a conversation
GET	/api/v1/characters/{id}/players/{player_id}/memories	List memories
POST	/api/v1/characters/{id}/players/{player_id}/memories	Create a memory
PATCH	/api/v1/characters/{id}/players/{player_id}/memories/{memory_id}	Update a memory
DELETE	/api/v1/characters/{id}/players/{player_id}/memories/{memory_id}	Delete a memory
GET	/api/v1/characters/{id}/players/{player_id}/memories/timeline	Memory timeline
GET	/api/v1/characters/{id}/players/{player_id}/memories/stats	Memory stats
GET	/api/v1/characters/{id}/players/{player_id}/memories/core-facts	Core facts
GET	/api/v1/characters/{id}/players/{player_id}/memories/graph	Knowledge graph
POST	/api/v1/characters/{id}/players/{player_id}/memories/search	Search memories
DELETE	/api/v1/characters/{id}/players/{player_id}/memories	Delete all memories

:::info {id} is the character ID Every path above uses the character's id, the value returned by the Characters API. Older routes spelled the same value agent_id. :::

Migrating from the older routes

Estuary also serves a set of unversioned routes (/api/agents/..., /api/generate/..., /api/encounters). They still work and are not going away without a long notice period, but every one of them now has a canonical /api/v1 replacement. Responses from them carry Deprecation, Link and Sunset headers.

See the Legacy migration guide for the full mapping and the wire differences, which are mostly camelCase query parameters and a few changed status codes.

Pagination

List endpoints support limit and offset query parameters:

curl "https://api.estuary-ai.com/api/v1/characters?limit=10&offset=20" \
  -H "X-API-Key: est_your_api_key"

Paginated responses include total, limit, and offset fields.

Errors

Error responses use standard HTTP status codes with a JSON body:

{
  "detail": "Character not found"
}

Status	Meaning
400	Bad request -- invalid parameters
401	Unauthorized -- missing or invalid API key
403	Forbidden -- not a member of the organization named in X-Org-Id, a player-scoped request on a developer-owned character, or a credential (such as a share session token) that cannot perform this operation
404	Not found -- resource doesn't exist or isn't owned by this account
409	Conflict -- the resource is busy or already in the requested state, for example a batch that is still running
413	Payload too large
422	Validation error -- detail lists the offending fields
429	Rate limit or quota exceeded -- honor the Retry-After header
500	Server error
503	Feature temporarily unavailable