Conversations

The Conversations endpoints let you locate an organization’s threads, inspect their data, change conversation state, and page through message history.

Every call requires Authorization: Bearer pk_.... Requests with JSON also require Content-Type: application/json. The base is https://api.squados.io/v1; see Authentication and Errors for shared contracts.

List conversations

GET /conversations

Provide at least one identity filter: user_id or external_user_id. The API restricts results to the token’s organization and orders conversations by updated_at, newest first.

Query	Type	Required	Description
user_id	string (UUID)	Conditional	Internal SquadOS profile ID. Primarily used by private Hub conversations.
external_user_id	string	Conditional	Contact identifier from the integrated system.
agent_id	string (UUID)	No	Keeps only conversations assigned to this agent. Agentless conversations have agent_id: null.
limit	integer	No	Page size. Default: 50; maximum: 100. Values above 100 are reduced to 100.
offset	integer	No	Number of records skipped before the page. Default: 0.

If both user_id and external_user_id are provided, both filters must match the conversation. agent_id is also combined with the identity filters.

curl "https://api.squados.io/v1/conversations?external_user_id=crm-customer-123&limit=20&offset=0" \
  -H "Authorization: Bearer pk_your_key_here"

Response 200

{
  "conversations": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "Billing question",
      "external_user_id": "crm-customer-123",
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-01T10:35:00Z",
      "channel_source": "api"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

total is the total number of conversations matching the filters, not just the current page size. A valid search with no results returns 200, conversations: [], and total: 0. Without either user_id or external_user_id, the API returns 400 invalid_request.

Get a conversation

GET /conversations/{conversationId}

Returns conversation details and its message count. The UUID must identify a conversation in the token’s organization.

curl "https://api.squados.io/v1/conversations/CONVERSATION_ID" \
  -H "Authorization: Bearer pk_your_key_here"

Response 200

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "agent_name": "Customer Support",
  "title": "Billing question",
  "status": "active",
  "channel_source": "api",
  "ai_enabled": true,
  "user_name": "Maria Silva",
  "external_user_id": "crm-customer-123",
  "credits_used": 12.5,
  "message_count": 8,
  "created_at": "2026-06-01T10:00:00Z",
  "updated_at": "2026-06-01T10:35:00Z"
}

A conversation from a human-handled inbox can return agent_id: null and agent_name: null. A malformed UUID returns 400 invalid_request; a missing conversation or one from another organization returns 404 not_found.

Update a conversation

PATCH /conversations/{conversationId}

PATCH accepts state changes, AI control, and identification fields. You can send one or more fields in the same body.

Field	Type	Description
status	active | completed	completed completes the conversation; active reopens a completed conversation.
ai_enabled	boolean	Enables or disables automatic responses. When false, messages can still be stored, but the agent does not reply automatically.
title	string	Replaces the conversation title.
user_name	string	Replaces the name on the conversation and on the linked external contact, when present.

State and AI control

• {"ai_enabled": false} disables AI without completing the conversation.
• {"status": "completed"} completes the conversation and leaves ai_enabled: false.
• {"status": "active"} reopens the conversation. The resulting ai_enabled value depends on the conversation’s stored resolution mode.
• {"status": "active", "ai_enabled": false} reopens and keeps human handling.
• {"status": "active", "ai_enabled": true} reopens and requests AI handling. The operation can fail when no agent is available to take over.
• If status: "completed" is sent with ai_enabled, completion takes precedence and the response still contains ai_enabled: false.

Caution

ai_enabled and status represent different concepts. Disabling AI does not complete the conversation; completing it changes the service lifecycle and starts background completion processing.

curl -X PATCH "https://api.squados.io/v1/conversations/CONVERSATION_ID" \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"status":"active","ai_enabled":false}'

Response 200

{
  "success": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "active",
  "ai_enabled": false
}

The response includes success and conversation_id, plus the state fields that were processed. Unrelated fields are omitted. For example, a title-only PATCH returns only success and conversation_id; a PATCH with user_name also returns user_name.

Malformed JSON, an invalid UUID, or a status other than active/completed returns 400 invalid_request. A missing conversation or one from another organization returns 404 not_found. A failure while completing, reopening, or changing AI returns 500 internal_error.

Read message history

GET /conversations/{conversationId}/messages

Returns messages in chronological order, oldest first.

Query	Type	Description
limit	integer	Page size. Default: 50. The current handler does not enforce a maximum.
offset	integer	Number of messages skipped. Default: 0.

Note

Although Swagger still states a maximum of 100 messages, the current endpoint does not cap limit. Use moderate page sizes such as 50 or 100 for predictable responses.

curl "https://api.squados.io/v1/conversations/CONVERSATION_ID/messages?limit=50&offset=0" \
  -H "Authorization: Bearer pk_your_key_here"

Response 200

{
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "messages": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "role": "user",
      "content": "Hi, how does monthly billing work?",
      "created_at": "2026-06-01T10:00:10Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
      "role": "assistant",
      "content": "Billing runs at the beginning of each cycle.",
      "created_at": "2026-06-01T10:00:14Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

This endpoint returns only id, role, content, and created_at for each message. Attachments, execution steps, model, and metadata are not part of this response.

Pagination

For GET /conversations, increase offset by limit until offset >= total. Message history does not return total; stop when messages is empty or contains fewer items than the requested limit.