API REST e Tokens

A API REST do SquadOS permite integrar seus agentes, bases de conhecimento e conversas com qualquer sistema externo. Tudo o que o painel admin faz pode ser feito por requisição HTTP autenticada.

O que a API oferece

A API está na versão v1 e cobre quatro recursos:

• Chat — POST /api/v1/chat/{agentId}: envia uma mensagem para um agente e recebe a resposta (com streaming opcional).
• Agents — lista (GET /api/v1/agents) e busca por id (GET /api/v1/agents/{id}) os agentes da organização.
• Conversations — lista, busca, atualiza conversas e lê mensagens (GET, PATCH e GET .../messages).
• Bases (bases de conhecimento) — CRUD completo de bases e seus items, além de POST /api/v1/bases/{id}/query para fazer busca semântica direto.

Lista resumida dos endpoints disponíveis:

• POST /api/v1/chat/{agentId}
• GET /api/v1/agents e GET /api/v1/agents/{id}
• GET /api/v1/conversations, GET /api/v1/conversations/{id}, PATCH /api/v1/conversations/{id}, GET /api/v1/conversations/{id}/messages
• GET /api/v1/bases, GET /api/v1/bases/{id}
• GET /api/v1/bases/{id}/items, POST /api/v1/bases/{id}/items
• GET /api/v1/bases/{id}/items/{itemId}, PATCH /api/v1/bases/{id}/items/{itemId}, DELETE /api/v1/bases/{id}/items/{itemId}
• POST /api/v1/bases/{id}/query

Como gerar um token

Tokens são por organização e dão acesso aos recursos dela.

1. Abra Configurações → aba API.
2. Clique em Gerar Token API.
3. No modal Gerar Token API, informe um Nome do Token descritivo (ex.: Integração site institucional).
4. Clique em Gerar Token.

O token completo aparece em um segundo modal (Token Gerado) com um alerta amarelo: “Este token será exibido apenas uma vez”. Copie e guarde em local seguro (gerenciador de segredos, vault, env var) usando o botão de cópia ao lado do campo. Depois disso o painel mostra apenas o prefixo (primeiros 8 caracteres seguidos de ...) para você identificar o token.

Tokens têm o formato pk_<hex>. Só admins (ou owners) podem gerar.

Gerenciar tokens existentes

Na mesma aba, a tabela Tokens API lista cada token com:

• Nome;
• Prefixo (ex.: pk_99fa646d...);
• Status (badge verde Ativo ou vermelho Revogado);
• Criado em (data);
• Último uso (data/hora, ou - se nunca foi usado);
• Chamadas (contador total);
• Ações (revogar com ícone de chave; excluir com ícone de lixeira).

Revogar desativa o token mas mantém o registro na tabela e o histórico de chamadas. Excluir remove o registro inteiro. Tokens revogados não podem ser reativados — gere um novo.

Header de autenticação

Todas as chamadas precisam do header:

Authorization: Bearer pk_<seu_token>

Tokens inválidos ou expirados retornam 401 Unauthorized.

Exemplo com curl

# Listar agentes da organização
curl https://<projeto>.supabase.co/functions/v1/api/v1/agents \
  -H "Authorization: Bearer pk_seu_token_aqui"

# Mandar mensagem para um agente
curl https://<projeto>.supabase.co/functions/v1/api/v1/chat/<agent_id> \
  -H "Authorization: Bearer pk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"message": "Olá, agente!"}'

# Buscar semanticamente em uma base
curl https://<projeto>.supabase.co/functions/v1/api/v1/bases/<base_id>/query \
  -H "Authorization: Bearer pk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"query": "termo de busca", "limit": 5}'

Documentação OpenAPI

Logo abaixo da tabela de tokens, a seção Documentação da API tem um botão OpenAPI Spec que abre a especificação em formato JSON (em nova aba). Você pode usar essa spec em ferramentas como Postman, Insomnia ou para gerar clientes automaticamente.

Boas práticas

• Gere um token por integração (um para o site, outro para o app interno, etc.) para conseguir revogar individualmente sem afetar os outros.
• Use nomes descritivos no token — o painel não mostra mais nada além do nome e prefixo.
• Nunca cole o token em código cliente (navegador, app mobile). A API REST é para chamadas server-to-server.
• Revogue tokens de imediato se suspeitar de vazamento; o impacto fica limitado à organização do token.
• Monitore a coluna Chamadas na tabela para identificar integrações mortas que podem ser revogadas.