Conversations

All endpoints below require the Authorization: Bearer pk_... header on every request. When sending a JSON body, also include Content-Type: application/json.

Base URL: https://api.squados.io/v1

See Authentication to learn how to obtain your API key, and Errors for the error code reference.

---

GET /conversations

Lists a user’s conversations, with support for filters and pagination.

At least one of user_id or external_user_id is required. If neither is provided, the API returns 400.

Query parameters

Name	Type	Description
user_id	uuid	Internal user ID in SquadOS.
external_user_id	string	User ID in your system (useful for integrating with external databases).
agent_id	uuid	Filters conversations for a specific agent.
limit	int	Number of records per page. Default: 50. Maximum: 100.
offset	int	Number of records to skip. Default: 0.

curl -X GET "https://api.squados.io/v1/conversations?external_user_id=usr_abc123&agent_id=AGENT_ID&limit=20&offset=0" \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{
  "conversations": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "Billing question",
      "external_user_id": "usr_abc123",
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-01T10:35:00Z",
      "channel_source": "widget"
    },
    {
      "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "Technical support",
      "external_user_id": "usr_abc123",
      "created_at": "2026-05-28T14:20:00Z",
      "updated_at": "2026-05-28T14:55:00Z",
      "channel_source": "widget"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Relevant errors: 400 if both user_id and external_user_id are omitted.

---

GET /conversations/{conversationId}

Returns the full details of a conversation.

Path parameters

Name	Type	Description
conversationId	uuid	Conversation ID.

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

Response — 200 OK

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

Relevant errors: 404 if the conversation does not exist or does not belong to your organization.

---

PATCH /conversations/{conversationId}

Updates conversation settings: enables/disables AI, changes the title, or sets the user name for personalization.

Path parameters

Name	Type	Description
conversationId	uuid	Conversation ID.

Request body

Field	Type	Required	Description
ai_enabled	boolean	No	If false, the conversation stops generating automatic AI responses.
title	string	No	New conversation title.
user_name	string	No	User’s name for response personalization.

Example — set user name:

{
  "user_name": "John Smith"
}

Example — disable AI for human takeover:

{
  "ai_enabled": false
}

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

Note

When ai_enabled is set to false, the conversation keeps receiving user messages, but the agent does not generate automatic responses. This is useful for handing off to a human agent: you disable the AI, a team member takes over via the Hub, and you can re-enable the AI at any time by sending ai_enabled: true.

Response — 200 OK

{
  "success": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ai_enabled": false,
  "user_name": "John Smith"
}

Relevant errors: 404 if the conversation does not exist or does not belong to your organization.

---

GET /conversations/{conversationId}/messages

Returns the message history of a conversation in chronological order.

Path parameters

Name	Type	Description
conversationId	uuid	Conversation ID.

Query parameters

Name	Type	Description
limit	int	Number of messages per page. Default: 50. Maximum: 100.
offset	int	Number of messages to skip. Default: 0.

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

Response — 200 OK

{
  "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": "Hi, John! Billing runs on the 1st of every month...",
      "created_at": "2026-06-01T10:00:14Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

Relevant errors: 404 if the conversation does not exist or does not belong to your organization.

---

Tip

All endpoints that support limit and offset follow the same pagination pattern. To page through a large set, increment offset by limit until you receive an empty list or until offset >= total. Example: limit=50&offset=0 → limit=50&offset=50 → limit=50&offset=100, and so on.