API Reference

Simple Agent REST API

Crie agents, envie mensagens e gerencie conversas programaticamente. Auth via API key no header Authorization: Bearer API_KEY

Base URL: https://simple-agent.meContent-Type: application/jsonRate limit: 100 req/min

POST/api/v1/chat

Envia uma mensagem para um agent e recebe a resposta (streaming ou síncrono).

Parâmetros

tokenstring — embed token do agent (obrigatório)

messagestring — mensagem do usuário (obrigatório)

conversationIdstring? — UUID da conversa existente (opcional, cria nova se omitido)

streamboolean? — true para streaming SSE (padrão: false)

Resposta (200)

{
  "reply": "Olá! Como posso ajudar?",
  "conversationId": "uuid",
  "citations": [
    {
      "index": 1,
      "source_uri": "https://docs.exemplo.com/intro",
      "content_snippet": "...",
      "page": null
    }
  ],
  "fcs": 0.92,
  "label": "high"
}

Exemplo curl

curl -X POST https://simple-agent.me/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "message": "Como funciona o produto?",
    "stream": false
  }'

POST/api/v1/agents

Cria um novo agent. Requer API key de workspace (header Authorization).

Parâmetros

namestring — nome do agent (obrigatório)

urlstring? — URL para crawl inicial (opcional)

systemPromptstring? — prompt de sistema customizado

tonePreset"formal" | "balanced" | "casual" (padrão: "balanced")

Resposta (200)

{
  "agentId": "uuid",
  "embedToken": "token_para_embed",
  "name": "Meu Agent",
  "trainingStatus": "partial"
}

Exemplo curl

curl -X POST https://simple-agent.me/api/v1/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{
    "name": "Suporte SaaS",
    "url": "https://docs.meusite.com"
  }'

GET/api/v1/agents

Lista todos os agents do workspace. Paginado (limit/offset).

Resposta (200)

{
  "agents": [
    {
      "id": "uuid",
      "name": "Suporte SaaS",
      "trainingStatus": "complete",
      "embedToken": "...",
      "createdAt": "2026-05-13T00:00:00Z"
    }
  ],
  "total": 3
}

Exemplo curl

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

GET/api/v1/conversations

Lista conversas de um agent. Filtre por agentId e dateRange.

Parâmetros

agentIdstring — UUID do agent (query param obrigatório)

limitnumber? — máx por página (padrão: 50)

offsetnumber? — paginação

Resposta (200)

{
  "conversations": [
    {
      "id": "uuid",
      "createdAt": "2026-05-13T00:00:00Z",
      "messageCount": 5,
      "lastUserMessage": "Como integrar com meu CRM?"
    }
  ],
  "total": 42
}

Exemplo curl

curl "https://simple-agent.me/api/v1/conversations?agentId=UUID" \
  -H "Authorization: Bearer API_KEY"

POST/api/v1/sources

Adiciona uma nova fonte (URL ou texto) a um agent existente.

Parâmetros

agentIdstring — UUID do agent (obrigatório)

type"url" | "text" | "pdf"

urlstring? — URL a rastrear (se type=url)

contentstring? — texto direto (se type=text)

namestring? — nome descritivo da fonte

Resposta (200)

{
  "sourceId": "uuid",
  "status": "processing",
  "estimatedChunks": 12
}

Exemplo curl

curl -X POST https://simple-agent.me/api/v1/sources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{
    "agentId": "UUID",
    "type": "url",
    "url": "https://docs.meusite.com/novo"
  }'

POST/api/v1/webhooks

Registra um webhook outbound para eventos do agent.

Parâmetros

agentIdstring — UUID do agent (obrigatório)

urlstring — URL HTTPS para receber eventos (obrigatório)

eventsstring[] — ex: ["conversation.created", "message.received", "lead.captured"]

secretstring? — segredo HMAC para validar assinatura (recomendado)

Resposta (200)

{
  "webhookId": "uuid",
  "status": "active",
  "events": ["conversation.created", "message.received"]
}

Exemplo curl

curl -X POST https://simple-agent.me/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{
    "agentId": "UUID",
    "url": "https://meusite.com/webhook/simple-agent",
    "events": ["conversation.created", "lead.captured"],
    "secret": "meu-segredo-hmac"
  }'

Eventos de Webhook

Cada evento é enviado via HTTP POST para sua URL com header X-SimpleAgent-Signature: sha256=HMAC_HEX

conversation.created

{ "conversationId": "uuid", "agentId": "uuid", "createdAt": "..." }

message.received

{ "conversationId": "uuid", "message": "...", "reply": "...", "fcs": 0.92 }

lead.captured

{ "conversationId": "uuid", "fields": { "email": "...", "name": "..." } }