Recursos · Chat API

Documentação da Chat API

Referência de nível empresarial para /chat/completions, incluindo esquema de requisição, eventos em streaming, comportamento em tempo de execução e semântica de erros.

Voltar à documentação Ir para Endpoints

Endpoints

GET /api/v1/chat/health

POST /api/v1/chat/completions

Cabeçalhos obrigatórios

Authorization: Bearer [token] ou autenticação por chave de APIContent-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: obrigatório somente quando scope for workspace

Corpo da requisição

json

{
  "message": "Summarize the last meeting in bullet points",
  "session_id": "sess_123",
  "stream": true,
  "attachments": [],
  "metadata": {
    "locale": "en",
    "channel": "web"
  }
}

Corpo da resposta

json

{
  "success": true,
  "session_id": "sess_123",
  "content": "• Discussed roadmap\n• Confirmed release scope\n• Assigned owners",
  "provider": "pulse",
  "usage": {
    "input_tokens": 324,
    "output_tokens": 118
  },
  "metadata": {
    "latency_ms": 612
  }
}

Eventos em streaming

response.started — execução do chat iniciada
response.delta — tokens de texto incrementais
response.tool_call — evento de invocação de ferramenta (se houver)
response.usage — atualização de uso/tokens
response.completed — resposta final montada

Comportamentos em tempo de execução

Controle de backpressure rejeita sobrecarga retornando 503.
Bloqueio distribuído evita processamento duplicado em andamento.
Cache de deduplicação atende requisições repetidas não por streaming.
Persistência de sessão armazena as trocas entre usuário e assistente.
Validação protege o corpo da requisição, anexos e contexto de acesso.

Modelos de erro

400

Corpo da requisição inválido ou campos obrigatórios ausentes.

401

Autenticação ausente ou inválida.

403

Restrição de escopo ou permissão.

409

Conflito de bloqueio: requisição já em processamento.

422

Falha de validação em cabeçalhos/corpo/contexto.

429

Limite de requisições excedido.

503

Sobrecarga do sistema ou indisponibilidade de serviços a montante.

Exemplos

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Write a short product update",
    "session_id":"sess_123",
    "stream":false
  }'