Documentação AI API

API estilo Assistants: crie assistentes no painel ou via API, envie mensagens WhatsApp com Bearer token e receba a resposta da IA com contexto por par de números. Base local: http://localhost:3020/zeus

Autenticação

Todas as rotas (exceto /api/health e docs) exigem:

Header

Authorization: Bearer <token>

Token de demonstração: demo_token_ai_api_mvp_2026 — assistentes seed: asst_demo_whatsapp_atendente, asst_beatriz_qualificacao (Beatriz — qualificação AutoEnvia)

POST /api/chat

Endpoint principal para o bridge WhatsApp.

Campo	Obrigatório	Descrição
`assistant_id`	sim	ID do assistente
`wa_from`	sim	Remetente (só dígitos)
`wa_to`	sim	Destinatário / número do bot
`message`	sim	Texto recebido no WhatsApp
`overrides`	não	model, temperature, instructions, max_tokens, top_p (só neste request)

cURL

curl -X POST "http://localhost:3020/zeus/api/chat" \
  -H "Authorization: Bearer demo_token_ai_api_mvp_2026" \
  -H "Content-Type: application/json" \
  -d "{
            \"assistant_id\": \"asst_demo_whatsapp_atendente\",
    \"wa_from\": \"5511999999999\",
    \"wa_to\": \"5511888888888\",
    \"message\": \"Oi, qual o horário de atendimento?\"
  }"

cURL — Beatriz (qualificação)

curl -X POST "http://localhost:3020/zeus/api/chat" \
  -H "Authorization: Bearer demo_token_ai_api_mvp_2026" \
  -H "Content-Type: application/json" \
  -d "{
    \"assistant_id\": \"asst_beatriz_qualificacao\",
    \"wa_from\": \"5511999999999\",
    \"wa_to\": \"5511888888888\",
    \"message\": \"Oi, quanto custa a AutoEnvia?\"
  }"

Resposta 200

{
  "success": true,
  "reply": "Nosso horário é...",
  "context_id": "ctx_…",
  "request_id": "uuid",
  "duration_ms": 1200,
  "meta": {
    "model": "llama3.2",
    "temperature": 0.3,
    "history_messages": 2,
    "usage": {}
  }
}

O contexto é isolado por assistant_id + wa_from + wa_to. O mesmo número com outro assistente não compartilha histórico.

Assistentes

Método	Rota	Ação
GET	`/api/assistants`	Listar
POST	`/api/assistants`	Criar
GET	`/api/assistants/:id`	Detalhe
PATCH	`/api/assistants/:id`	Atualizar
DELETE	`/api/assistants/:id`	Soft-delete (is_active=0)

POST body

{
  "name": "Atendente vendas",
  "instructions": "Você é um vendedor educado...",
  "model": "llama3.2",
  "temperature": 0.3,
  "top_p": 1,
  "max_tokens": 512,
  "max_history_messages": 20
}

Threads (contexto)

Método	Rota	Ação
GET	`/api/threads/:context_id`	Ver mensagens
POST	`/api/threads/:context_id/reset`	Limpar mensagens
DELETE	`/api/threads/:context_id`	Apagar thread

Erros

HTTP	Caso
400	Validação (message, WA, overrides)
401	Bearer ausente/inválido
403	IP bloqueado; token inactive/blocked
404	Assistente/thread não encontrado
429	Rate limit
503 / 504	LLM down / timeout

Corpo típico: { "success": false, "error": "...", "request_id": "..." }

Demo e health

GET /api/health → { success, status, llm: "ok"|"down" }
Painel: /admin — Demonstração simula WhatsApp sem token
Requisito: Ollama em http://127.0.0.1:11434 com o modelo configurado