API Overview

The SquadOS API is a REST API that exposes your agents, conversations, and knowledge bases to any external system — n8n, Make, Zapier, a CRM, your own backend, anything that speaks HTTP. With it you can send messages to an agent, read conversation history, query agents and bases, and run semantic search (RAG) directly against a base.

This section is the complete reference: every endpoint ships a ready-to-run curl, the required headers, and request/response examples — no need to execute anything to understand how a call works.

Base URL

All requests share a single host, with the /v1 version prefix:

https://api.squados.io/v1

Paths in this documentation are relative to that base. For example, POST /chat/{agentId} means POST https://api.squados.io/v1/chat/{agentId}.

Authentication

The API uses a Bearer token in the Authorization header. The token is generated per organization, in the admin panel, and is prefixed with pk_:

Authorization: Bearer pk_your_key_here

See Authentication to generate, use, and manage tokens.

Request format

Protocol: HTTPS only.
Body: JSON. On requests with a body (POST, PATCH), always send the Content-Type: application/json header.
Responses: JSON, with Content-Type: application/json.
Dates: ISO 8601 strings in UTC (e.g. 2026-06-08T15:51:00Z).
IDs: UUID v4.

A minimal call — send a message and wait for the reply:

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

Available resources

Resource	What it does
Chat	Send messages to an agent (synchronous or asynchronous via webhook)
Conversations	List, fetch, update conversations and read messages
Agents	List and fetch the organization’s agents
Knowledge Bases	Manage a base’s items and run semantic search (RAG)
Tags	Manage the tag catalog and apply/remove tags on external contacts

Supporting the reference:

Webhooks — the payload you receive on asynchronous responses.
Errors — error response format and code table.

Supported attachment formats

Several endpoints accept attachments (the attachments field). Accepted formats:

Images: JPEG, PNG, WebP, GIF.
Documents: PDF, TXT, MD, CSV, DOC, DOCX, XLS, XLSX.

Attachments can be sent by public URL or as base64.