Visão Geral da API

A API REST do SquadOS conecta agentes, conversas, bases de conhecimento, tags e listas de contatos a qualquer sistema capaz de fazer requisições HTTP. A referência atual cobre 26 operações distribuídas em seis famílias de recursos.

Use esta página para entender o contrato comum. As páginas de cada recurso detalham parâmetros, paginação, corpos e respostas.

Base URL e versão

Todas as operações desta referência usam HTTPS e o prefixo de versão /v1:

https://api.squados.io/v1

Os caminhos das páginas seguintes são relativos a essa base. Por exemplo, GET /agents corresponde a GET https://api.squados.io/v1/agents.

Autenticação e escopo

Envie um token ativo da organização como Bearer token em todas as operações:

Authorization: Bearer pk_sua_chave_aqui

O token identifica a organização. Os handlers aplicam esse escopo ao consultar ou alterar recursos, portanto um ID de outra organização não concede acesso ao recurso. Veja Autenticação para criar, copiar, rotacionar e excluir tokens.

Formato comum

• Envie corpos como objetos JSON e use Content-Type: application/json.
• A API responde em JSON. Erros dos handlers REST usam { "error": "mensagem", "code": "codigo" }.
• Datas são strings ISO 8601 e identificadores de recursos usam formato UUID.
• Parâmetros de consulta controlam paginação e filtros nos endpoints que os oferecem; consulte a página do recurso antes de assumir valores padrão.

Uma chamada mínima para listar os agentes visíveis ao token:

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

Para enviar uma mensagem e receber a resposta no mesmo request:

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

O segmento final de /chat/{id} aceita o ID da caixa de entrada API. O ID do agente continua aceito como compatibilidade para integrações antigas, desde que exista uma caixa API ativa vinculada a ele. Em ambos os casos, o alvo deve pertencer à organização do token e ser uma caixa do canal API.

Recursos disponíveis

Família	Operações documentadas
Chat	Enviar mensagens, anexos e dados de correlação; receber resposta direta ou por webhook
Conversas	Listar, consultar e atualizar conversas; ler mensagens
Agentes	Listar e consultar agentes da organização
Bases de Conhecimento	Listar bases, gerenciar itens e executar busca semântica
Tags	Gerenciar o catálogo e aplicar ou remover tags de contatos
Listas de Contatos	Listar listas e membros, adicionar contatos e descadastrá-los

Também consulte:

• Webhooks de resposta para o callback de uma mensagem assíncrona do Chat.
• Webhooks de eventos para assinar eventos da organização; esse fluxo é separado do callback de Chat.
• Erros para status HTTP, códigos e tratamento seguro.

Resposta direta ou assíncrona

No Chat, sync: true aguarda a execução e devolve a resposta no próprio request. Para processamento assíncrono, envie webhook_url e não defina sync: true: a API responde 202 com o ID da conversa e entrega o resultado depois ao webhook.

Não presuma um timeout fixo de 10 segundos para a resposta direta. O tempo varia conforme o modelo, as ferramentas e os anexos usados pelo agente; configure o timeout do seu cliente HTTP de acordo com a sua jornada.

Cuidado

O Swagger público ainda descreve o parâmetro de Chat apenas como agentId e menciona um timeout síncrono de 10 segundos. Esses dois pontos estão desatualizados em relação ao runtime; use o contrato textual acima até a especificação ser reconciliada.

Anexos do Chat

Somente o endpoint de Chat recebe o campo attachments. Cada item exige:

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

• name: nome do arquivo.
• url: URL HTTP(S) publicamente acessível ou data URL com conteúdo em base64; uma sequência base64 sem o prefixo de data URL não é um valor completo.
• type: image, audio ou file.
• mimeType: MIME type do conteúdo; é opcional no contrato, mas deve ser informado para evitar inferência incorreta.

Imagens podem seguir para um modelo com visão, áudios são transcritos e arquivos são lidos conforme o tipo e a capacidade do modelo. TXT, MD, CSV, JSON, PDF, DOC/DOCX e XLS/XLSX têm tratamento explícito no pipeline atual. URLs locais, privadas, reservadas ou com protocolo diferente de HTTP(S) são bloqueadas.

O processamento também respeita a configuração de anexos do agente. Se uma modalidade estiver desativada ou o modelo não tiver a capacidade necessária, o resultado pode conter uma rejeição ou uma indicação de que o conteúdo não foi processado.

Swagger interativo

O Swagger público permite autorizar um token e executar exemplos no navegador. Ele é um explorador secundário: para instruções de integração e ressalvas do runtime, use primeiro esta documentação textual.