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.

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/generate/image-to-character	Generate a character from an image
POST	/api/generate/{agent_id}/generate-model	Trigger 3D model generation
GET	/api/generate/{agent_id}/model-status	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/agents/{agent_id}/players/stats	Conversation stats
GET	/api/agents/{agent_id}/players	List conversations
GET	/api/agents/{agent_id}/players/{player_id}	Get a conversation
GET	/api/agents/{agent_id}/players/{player_id}/messages	Get messages
DELETE	/api/agents/{agent_id}/players/{player_id}	Delete a conversation
GET	/api/agents/{agent_id}/players/{player_id}/memories	List memories
POST	/api/v1/agents/{agent_id}/players/{player_id}/memories	Create a memory
PATCH	/api/v1/agents/{agent_id}/players/{player_id}/memories/{memory_id}	Update a memory
DELETE	/api/v1/agents/{agent_id}/players/{player_id}/memories/{memory_id}	Delete a memory
GET	/api/agents/{agent_id}/players/{player_id}/memories/timeline	Memory timeline
GET	/api/agents/{agent_id}/players/{player_id}/memories/stats	Memory stats
GET	/api/agents/{agent_id}/players/{player_id}/memories/core-facts	Core facts
GET	/api/agents/{agent_id}/players/{player_id}/memories/graph	Knowledge graph
POST	/api/agents/{agent_id}/players/{player_id}/memories/search	Search memories
DELETE	/api/agents/{agent_id}/players/{player_id}/memories	Delete all memories

:::info agent_id = character_id The Conversations and Memories APIs use agent_id in the URL path. This is the same ID returned as id by the Characters API. :::

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
404	Not found -- resource doesn't exist or isn't owned by this account
500	Server error