API Overview

The SquadOS REST API connects agents, conversations, knowledge bases, tags, and contact lists to any system that can make HTTP requests. The current reference covers 26 operations across six resource families.

Use this page to understand the shared contract. Each resource page documents its parameters, pagination, request bodies, and responses.

Base URL and version

Every operation in this reference uses HTTPS and the /v1 version prefix:

https://api.squados.io/v1

Paths on the following pages are relative to this base. For example, GET /agents means GET https://api.squados.io/v1/agents.

Authentication and scope

Send an active organization token as a Bearer token on every operation:

Authorization: Bearer pk_your_key_here

The token identifies the organization. Handlers apply this scope when reading or changing resources, so an ID from another organization does not grant access to that resource. See Authentication to create, copy, rotate, and delete tokens.

Common format

• Send request bodies as JSON objects and use Content-Type: application/json.
• The API responds with JSON. REST handler errors use { "error": "message", "code": "machine_code" }.
• Dates are ISO 8601 strings, and resource identifiers use UUID format.
• Query parameters control pagination and filters on endpoints that provide them; check the resource page before assuming default values.

A minimal call to list the agents visible to the token:

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

To send a message and receive the reply in the same request:

curl -X POST https://api.squados.io/v1/chat/API_INBOX_ID \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "sync": true
  }'

The final /chat/{id} segment accepts the API inbox ID. The agent ID remains accepted for compatibility with older integrations when the agent has an active API inbox. In both cases, the target must belong to the token’s organization and must be an inbox for the API channel.

Available resources

Family	Documented operations
Chat	Send messages, attachments, and correlation data; receive a direct reply or webhook callback
Conversations	List, fetch, and update conversations; read messages
Agents	List and fetch the organization’s agents
Knowledge Bases	List bases, manage items, and run semantic search
Tags	Manage the catalog and apply or remove contact tags
Contact Lists	List lists and members, add contacts, and unsubscribe them

Also see:

• Response webhooks for the callback from an asynchronous Chat message.
• Event webhooks to subscribe to organization events; this flow is separate from the Chat callback.
• Errors for HTTP statuses, codes, and safe handling.

Direct or asynchronous response

In Chat, sync: true waits for execution and returns the reply in the same request. For asynchronous processing, send webhook_url and do not set sync: true: the API returns 202 with the conversation ID and delivers the result to the webhook later.

Do not assume a fixed 10-second timeout for a direct response. Duration varies with the agent’s model, tools, and attachments; configure your HTTP client’s timeout for your workflow.

Caution

The public Swagger still describes the Chat path parameter only as agentId and mentions a 10-second synchronous timeout. Both details are stale relative to the runtime; use the textual contract above until the specification is reconciled.

Chat attachments

Only the Chat endpoint accepts the attachments field. Each item requires:

{
  "name": "contract.pdf",
  "url": "https://example.com/contract.pdf",
  "type": "file",
  "mimeType": "application/pdf"
}

• name: file name.
• url: a publicly reachable HTTP(S) URL or a data URL containing base64 data; a raw base64 sequence without the data URL prefix is not a complete value.
• type: image, audio, or file.
• mimeType: the content’s MIME type; optional in the contract, but supply it to avoid incorrect inference.

Images can be sent to a vision-capable model, audio is transcribed, and files are read according to their type and the model’s capabilities. TXT, MD, CSV, JSON, PDF, DOC/DOCX, and XLS/XLSX have explicit handling in the current pipeline. Local, private, reserved, or non-HTTP(S) URLs are blocked.

Processing also honors the agent’s attachment configuration. If a modality is disabled or the model lacks the required capability, the result may contain a rejection or an indication that the content was not processed.

Interactive Swagger

The public Swagger lets you authorize a token and run examples in the browser. Treat it as a secondary explorer: for integration instructions and runtime caveats, use this text documentation first.