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.

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
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
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
GET	/api/agents/{agent_id}/players/{player_id}/memories/search	Search memories
DELETE	/api/agents/{agent_id}/players/{player_id}/memories	Delete memories

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