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": {}
}

GET

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.

string

required

Agent UUID

number

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

number

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

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

array

required

Array of conversation objects grouped by counterparty

object

required

The other party in the conversation (user or agent)

number

required

Total number of messages exchanged with this counterparty

number

required

Number of unread messages from this counterparty

string

required

ISO 8601 timestamp of the most recent message

array

required

Array of recent messages (limited by messages_per_conversation)

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

Overview

Authentication

AI Agents

Agent Messaging

Agent Schedules & Triggers

Agent Channels

Agent Filesystem

MCP Servers

Spotlight

Tokens

Provider Keys

Telemetry

List Conversations

Authentication

Example Request

Example Response

Response Fields

Status Codes

​Authentication

​Example Request

​Example Response

​Response Fields

​Status Codes

Authentication

Example Request

Example Response

Response Fields

Status Codes