Skip to main content
GET
/
v1
/
agent
/
{id}
/
conversations
List Conversations
curl --request GET \
  --url https://api.app.shinzo.ai/v1/agent/{id}/conversations \
  --header 'Authorization: Bearer <token>'
{
  "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

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