Visão Geral da API

A API do SquadOS é uma API REST que expõe seus agentes, conversas e bases de conhecimento para qualquer sistema externo — n8n, Make, Zapier, CRM, backend próprio, qualquer coisa que faça HTTP. Com ela você pode enviar mensagens a um agente, ler o histórico de conversas, consultar agentes e bases, e fazer busca semântica (RAG) diretamente numa base.

Esta seção é a referência completa: cada endpoint traz o curl pronto, os headers obrigatórios e exemplos de request e response — sem precisar executar nada para entender como a chamada funciona.

Base URL

Todas as requisições partem de um único host, com o prefixo de versão /v1:

https://api.squados.io/v1

Os caminhos nesta documentação são relativos a essa base. Por exemplo, POST /chat/{agentId} significa POST https://api.squados.io/v1/chat/{agentId}.

Autenticação

A API usa Bearer token no header Authorization. O token é gerado por organização, no painel admin, e tem o prefixo pk_:

Authorization: Bearer pk_sua_chave_aqui

Veja Autenticação para gerar, usar e gerenciar tokens.

Formato das requisições

Protocolo: HTTPS apenas.
Corpo: JSON. Em requisições com corpo (POST, PATCH), envie sempre o header Content-Type: application/json.
Respostas: JSON, com Content-Type: application/json.
Datas: strings ISO 8601 em UTC (ex.: 2026-06-08T15:51:00Z).
IDs: UUID v4.

Uma chamada mínima — enviar uma mensagem e aguardar a resposta:

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual é o horário de funcionamento?",
    "sync": true
  }'

Recursos disponíveis

Recurso	O que faz
Chat	Enviar mensagens a um agente (síncrono ou assíncrono via webhook)
Conversas	Listar, consultar, atualizar conversas e ler mensagens
Agentes	Listar e consultar agentes da organização
Bases de Conhecimento	Gerenciar itens de uma base e fazer busca semântica (RAG)
Tags	Gerenciar o catálogo de tags e aplicar/remover tags em contatos externos

Complementam a referência:

Webhooks — o payload que você recebe nas respostas assíncronas.
Erros — formato das respostas de erro e tabela de códigos.

Formatos de anexo suportados

Vários endpoints aceitam anexos (campo attachments). Formatos aceitos:

Imagens: JPEG, PNG, WebP, GIF.
Documentos: PDF, TXT, MD, CSV, DOC, DOCX, XLS, XLSX.

Anexos podem ser enviados por URL pública ou em base64.