List Conversations

List conversations for an agent, grouped by counterparty with message counts and recent messages.

GET /v1/agent/{id}/conversations

List Conversations

cURL

curl --request GET \
  --url https://api.app.shinzo.ai/v1/agent/{id}/conversations \
  --header 'Authorization: Bearer <token>'

200

{
  "conversations": [
    {}
  ],
  "conversations[].counterparty": {},
  "conversations[].total_messages": 123,
  "conversations[].unread_count": 123,
  "conversations[].last_message_at": "<string>",
  "conversations[].messages": [
    {}
  ],
  "pagination": {}
}

Authentication

Requires JWT token or Platform API key via Authorization: Bearer <token> header.

id · string · required

Agent UUID

limit · number

Number of conversations to return (default: 10, max: 50)

messages_per_conversation · number

Number of recent messages per conversation (default: 20, max: 50)

before · string

Cursor: ISO timestamp to load older conversations

Example Request

curl "https://api.app.shinzo.ai/v1/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/conversations?limit=5&messages_per_conversation=10" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "conversations": [
    {
      "counterparty": {
        "uuid": "user-uuid-123",
        "type": "user",
        "name": "John Doe"
      },
      "total_messages": 48,
      "unread_count": 3,
      "last_message_at": "2026-02-24T14:30:00Z",
      "messages": [
        {
          "uuid": "msg-001",
          "content": "Can you help me with this?",
          "sender_type": "user",
          "sender_uuid": "user-uuid-123",
          "recipient_type": "agent",
          "recipient_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "status": "read",
          "created_at": "2026-02-24T14:30:00Z"
        }
      ]
    },
    {
      "counterparty": {
        "uuid": "agent-uuid-456",
        "type": "agent",
        "name": "Assistant Agent"
      },
      "total_messages": 15,
      "unread_count": 0,
      "last_message_at": "2026-02-24T12:00:00Z",
      "messages": []
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "2026-02-24T12:00:00Z"
  }
}

Response Fields

conversations · array · required

Array of conversation objects grouped by counterparty

conversations[].counterparty · object · required

The other party in the conversation (user or agent)

conversations[].total_messages · number · required

Total number of messages exchanged with this counterparty

conversations[].unread_count · number · required

Number of unread messages from this counterparty

conversations[].last_message_at · string · required

ISO 8601 timestamp of the most recent message

conversations[].messages · array · required

Array of recent messages (limited by messages_per_conversation)

pagination · object · required

Pagination metadata for loading more conversations

This endpoint groups messages by counterparty to provide a conversation-style view. For raw message listing, use List Messages instead.

Status Codes

Code	Description
200	Conversations retrieved successfully
401	Unauthorized - invalid or missing authentication
404	Agent not found