API Reference

Documentação completa da API REST Simple Agent — autenticação, endpoints, webhooks e rate limits.

A API REST Simple Agent permite que você gerencie agents, fontes e conversas programaticamente.

Base URL: https://simple-agent.me/api/v1

Autenticação

Todas as requisições usam Bearer token no header Authorization:

curl https://simple-agent.me/api/v1/agents \
  -H "Authorization: Bearer af_live_xxxxxxxxxxxxxxxxxxxx"

Crie sua API key em Configurações → API → Gerar chave.

Escopos disponíveis:

agents:read — listar e ler agents
agents:write — criar e editar agents
sources:write — adicionar e remover fontes
conversations:read — ler histórico de conversas
webhooks:write — gerenciar webhooks

Agents

Listar agents

GET /v1/agents

Response:

{
  "data": [
    {
      "id": "ag_01HXxxxxxx",
      "name": "Suporte Principal",
      "status": "active",
      "sources_count": 12,
      "messages_this_month": 1847,
      "created_at": "2026-05-01T10:00:00Z"
    }
  ],
  "total": 1,
  "has_more": false
}

Criar agent

POST /v1/agents
Content-Type: application/json

{
  "name": "Suporte Vendas",
  "welcome_message": "Olá! Como posso ajudar com sua compra?",
  "tone": "balanced",
  "fallback_message": "Deixa eu conectar você com nosso time."
}

Sources

Adicionar fonte URL

POST /v1/agents/{agent_id}/sources
Content-Type: application/json

{
  "type": "url",
  "url": "https://seusite.com/faq",
  "crawl_depth": 2,
  "refresh_every_days": 7
}

Response:

{
  "id": "src_01HXxxxxxx",
  "status": "processing",
  "estimated_chunks": 340,
  "webhook_on_complete": null
}

Upload PDF

POST /v1/agents/{agent_id}/sources
Content-Type: multipart/form-data

file=@manual.pdf
type=pdf

Status de fonte

GET /v1/agents/{agent_id}/sources/{source_id}

{
  "id": "src_01HXxxxxxx",
  "status": "ready",
  "chunks_count": 342,
  "last_crawled_at": "2026-05-10T14:22:00Z"
}

Conversas

Listar conversas

GET /v1/agents/{agent_id}/conversations?limit=20&cursor=xxx

Buscar conversa

GET /v1/agents/{agent_id}/conversations/{conversation_id}

Response:

{
  "id": "conv_01HXxxxxxx",
  "messages": [
    {
      "role": "user",
      "content": "Qual o prazo de entrega?",
      "created_at": "2026-05-10T15:00:00Z"
    },
    {
      "role": "assistant",
      "content": "O prazo de entrega é de 3–5 dias úteis para todo o Brasil...",
      "citations": [
        {
          "source_id": "src_01HXxxxxxx",
          "chunk_offset": 847,
          "text": "...prazo de entrega é de 3–5 dias úteis...",
          "url": "https://seusite.com/faq#entrega",
          "confidence": 0.94
        }
      ],
      "fcs_score": 0.94,
      "latency_ms": 823
    }
  ]
}

Webhooks

Configure webhooks para receber eventos em tempo real.

Criar webhook

POST /v1/webhooks
Content-Type: application/json

{
  "url": "https://seusite.com/webhooks/simple-agent",
  "events": ["conversation.created", "source.ready", "source.failed"],
  "secret": "seu-segredo-hmac"
}

Verificar assinatura

Cada requisição inclui o header X-Simple Agent-Signature:

X-Simple Agent-Signature: t=1715000000,v1=abc123def456...

Verifique com HMAC SHA-256:

import crypto from "crypto";

function verifySignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const [, timestamp] = signature.split(",t=").at(0)?.split("t=") ?? [];
  const [, v1] = signature.split(",v1=");

  const signed = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(v1, "hex"),
    Buffer.from(expected, "hex")
  );
}

Rate limits

Plano	Requests/min	Burst
Free	10	20
Starter	60	100
Growth	300	500
Agency	1.000	2.000
Scale	5.000	10.000

Headers de rate limit retornados em toda resposta:

X-RateLimit-Limit: limite do plano
X-RateLimit-Remaining: requisições restantes neste minuto
X-RateLimit-Reset: timestamp Unix do reset

Erros

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 30 seconds.",
    "retry_after": 30
  }
}

Código HTTP	Significado
400	Parâmetro inválido
401	API key inválida ou expirada
403	Sem permissão (escopo)
404	Recurso não encontrado
429	Rate limit excedido
500	Erro interno