Conversations API

Conversations are served by two routers:

• User conversations (agents router): mounted under /api/v1/agents, scoped to the caller's own conversations, and covering listing, renaming, deleting conversations, and deleting a single message.
• Platform conversations (conversations router): mounted under /api/v1/conversations, aimed at the team/admin view, and covering paginated team-wide search, detail retrieval, single and batch deletion, and conversation statistics.

Both require conversation:read for reads and conversation:delete for writes.

Endpoint Overview

User Conversation Endpoints

Every user endpoint is scoped to Conversation.user: accessing someone else's conversation is treated as not found (404, code 6210). Parameters, responses, and errors per endpoint are documented in Agent Conversations in the Agent API.

Platform Conversation Endpoints

The platform router serves the team/admin view and backs the admin panel's conversation-management page.

Paginated Listing

GET /api/v1/conversations

Results are ordered by updated_at descending as a PageData[ConversationListOut]. Besides the conversation fields, each item carries the admin-view user_id/user_name plus the denormalized agent_name/agent_icon.

Get Conversation Detail

GET /api/v1/conversations/{conversation_id}

Returns a ConversationWithMessages: the conversation fields plus messages (visible messages, each with version_count) and the extra user_id/user_name. Unlike the user endpoint, this route lets an admin with dashboard access read another user's conversation within their teams.

Delete Conversation

DELETE /api/v1/conversations/{conversation_id}

curl -X DELETE "https://your-domain.com/api/v1/conversations/conv-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Batch Delete Conversations

DELETE /api/v1/conversations?ids=conv-123&ids=conv-456

ids is a required repeated query parameter (list[UUID]), not a JSON body. The batch does not roll back per-item: it deletes whatever exists, and only returns 404 (6210) when none of the targets exist. Deletion is permanent, so filter by time, team, user, and agent first to confirm the scope.

Scope

Visibility is the intersection of "accessible agents" and "dashboard access":

For non-superusers, passing team_id first verifies team membership; when the caller has no accessible agents the listing returns an empty result (no error).

Conversation Statistics

Both statistics routes are built on "accessible agents" and then narrowed by own_only and dashboard access:

• Without team_id, the scope covers every agent in the teams the caller belongs to (all agents for a superuser).
• With team_id, the scope is limited to that team's agents and team membership is verified.
• Callers with dashboard access (superuser, or the owner/admin of the named team) see all conversations in scope; members and viewers see only their own.
• own_only=true restricts any caller to their own conversations.

Get Conversation Stats

GET /api/v1/conversations/stats

{
  "code": 0,
  "data": {
    "total_conversations": 1284,
    "total_messages": 18237,
    "conversations_by_agent": [
      {
        "agent_id": "1c2f1a2e-0f4e-4a8f-9d4a-2b0d7b3dcb6d",
        "agent_name": "Support Assistant",
        "agent_icon": "life-buoy",
        "count": 742
      }
    ]
  },
  "msg": "success"
}

conversations_by_agent lists at most the 10 agents with the most conversations, ordered descending. If an agent record can no longer be resolved, agent_name falls back to the localized "unknown" label and agent_icon is null.

Get Conversation Trends

GET /api/v1/conversations/stats/trends?period=30d

{
  "code": 0,
  "data": {
    "period": "7d",
    "data": [
      {
        "date": "09/20",
        "conversations": 34,
        "messages": 512,
        "tokens": 187340,
        "users": {}
      }
    ]
  },
  "msg": "success"
}

Message Versions

Messages can have multiple versions, and responses include version_number, is_active, parent message/branch relationships, and version_count. Editing or regenerating creates a branch; switching versions only changes the active version and deactivates the versions after the selected one (they were based on the previous branch). See message versions in the Agent Chat API.

Error Codes

Related Documentation

• Agent Chat API — Send messages, streaming responses, and durable runs
• Agent API — Agent management, agent conversation endpoints, and agent statistics
• SSE Streaming Events — Run events and reconnection