Skip to main content

Conversations API

Read and manage conversations between your characters and players. Each unique player_id + character_id pair creates a persistent conversation with full memory.

Base path: /api/agents/{agent_id}/players

agent_id = character_id

The agent_id in the URL path is the same id returned by the Characters API.

Get Conversation Stats​

GET /api/agents/{agent_id}/players/stats

Returns aggregate statistics for all conversations with a character.

Response​

{
  "totalConversations": 156,
  "totalMessages": 4230,
  "firstActivity": "2026-01-15T10:30:00",
  "lastActivity": "2026-03-01T14:22:00"
}
FieldTypeDescription
totalConversationsintegerTotal number of player conversations
totalMessagesintegerTotal messages across all conversations
firstActivitystring | nullISO 8601 timestamp of earliest conversation
lastActivitystring | nullISO 8601 timestamp of most recent activity

Example​

curl https://api.estuary-ai.com/api/agents/550e8400-e29b-41d4-a716-446655440000/players/stats \
  -H "X-API-Key: est_your_api_key"

List Conversations​

GET /api/agents/{agent_id}/players

Returns a paginated list of player conversations for a character.

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Results per page (1-100)
offsetinteger0Number of results to skip
sort_bystring"last_activity"Sort field: "last_activity", "created_at", "message_count", "player_id"
sort_orderstring"desc""asc" or "desc"
player_searchstring—Filter by player_id (partial match)
min_messagesinteger—Only include conversations with at least this many messages

Response​

{
  "conversations": [
    {
      "id": "conv_abc123",
      "characterId": "550e8400-e29b-41d4-a716-446655440000",
      "playerId": "player_xyz",
      "messageCount": 42,
      "createdAt": "2026-01-20T09:00:00",
      "lastActivity": "2026-03-01T14:22:00"
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0,
  "sortBy": "last_activity",
  "sortOrder": "desc"
}

Example​

curl "https://api.estuary-ai.com/api/agents/550e8400-e29b-41d4-a716-446655440000/players?limit=10&sort_by=message_count&sort_order=desc" \
  -H "X-API-Key: est_your_api_key"
const agentId = "550e8400-e29b-41d4-a716-446655440000";
const res = await fetch(
  `https://api.estuary-ai.com/api/agents/${agentId}/players?limit=10&min_messages=5`,
  { headers: { "X-API-Key": "est_your_api_key" } }
);
const data = await res.json();
console.log(`${data.total} conversations found`);

Get a Conversation​

GET /api/agents/{agent_id}/players/{player_id}

Returns details for a specific player's conversation.

Example​

curl https://api.estuary-ai.com/api/agents/550e8400-e29b-41d4-a716-446655440000/players/player_xyz \
  -H "X-API-Key: est_your_api_key"

Get Messages​

GET /api/agents/{agent_id}/players/{player_id}/messages

Returns messages for a player conversation, ordered chronologically (newest page first, messages within each page in chronological order).

Query Parameters​

ParameterTypeDefaultDescription
limitinteger100Messages per page
pageinteger1Page number (1-indexed)

Response​

{
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Hey, remember what we talked about last time?",
      "timestamp": "2026-03-01T14:20:00"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Of course! You were telling me about your hiking trip to Rocky Mountain National Park.",
      "timestamp": "2026-03-01T14:20:05"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 42,
    "hasMore": false
  }
}

Example​

curl "https://api.estuary-ai.com/api/agents/550e8400-e29b-41d4-a716-446655440000/players/player_xyz/messages?limit=50&page=1" \
  -H "X-API-Key: est_your_api_key"

Delete a Conversation​

DELETE /api/agents/{agent_id}/players/{player_id}

Permanently deletes a conversation, all its messages, and all associated memories for this player-character pair.

Response​

{
  "message": "Player conversation deleted"
}

Example​

curl -X DELETE https://api.estuary-ai.com/api/agents/550e8400-e29b-41d4-a716-446655440000/players/player_xyz \
  -H "X-API-Key: est_your_api_key"
Last updated