Documentação

API Reference

Documentação da API REST da Elohia — autenticação JWT, endpoints de agentes, tarefas e exemplos de uso.

Atualizado em 21 de abril de 202610 min de leitura

Autenticação

A API usa JWT Bearer Token. O token e emitido no login (POST /v1/auth/login) ou no signup (POST /v1/auth/signup) e já traz o tenant assinado no claim tslug. Inclua o token em todas as requisições autenticadas:

Authorization: Bearer <accessToken>

// Exemplo com curl
curl -X GET https://api.elohia.com.br/v1/agents \
  -H "Authorization: Bearer <seu-jwt>" \
  -H "Content-Type: application/json"

Nunca coloque o accessToken em código commitado ou em URLs públicas. Use variáveis de ambiente. O token expira em 24h — use /v1/auth/refresh para renovar.

Base URL

https://api.elohia.com.br/v1

// O alias /api/* também esta disponível para compatibilidade
// com o SPA e com integrações antigas.

Endpoints de Agentes

Metodo	Endpoint	Descrição
GET	/agents	Listar todos os agentes do tenant
POST	/agents	Criar novo agente
GET	/agents/:id	Obter agente por ID
PUT	/agents/:id	Atualizar agente
DELETE	/agents/:id	Excluir agente
POST	/agents/:id/run	Executar tarefa no agente
GET	/agents/:id/tasks	Listar tarefas do agente
GET	/agents/:id/metrics	Métricas do agente

Criar agente (POST /agents)

// Request body
{
  "name": "Agente de Suporte",
  "description": "Responde dúvidas internas sobre RH e beneficios",
  "model": "claude-3-5-sonnet-20241022",
  "config": {
    "maxIterations": 10,
    "timeoutSeconds": 120,
    "allowedSkills": ["search", "summarize", "send-email"]
  }
}

// Response (201 Created)
{
  "id": "agt_01jf8x2k3m...",
  "tenantId": "ten_01je...",
  "name": "Agente de Suporte",
  "status": "idle",
  "createdAt": "2026-03-29T14:00:00Z"
}

Executar tarefa (POST /agents/:id/run)

// Request body
{
  "input": "Quantos funcionários temos no departamento de vendas?",
  "context": {
    "userId": "usr_123",
    "source": "slack"
  }
}

// Response (streaming com SSE ou JSON sincronizado)
{
  "taskId": "tsk_01jf...",
  "status": "running",
  "streamUrl": "/v1/tasks/tsk_01jf.../stream"
}

Endpoints de Tarefas

Metodo	Endpoint	Descrição
GET	/tasks	Listar todas as tarefas do tenant
GET	/tasks/:id	Obter tarefa por ID
GET	/tasks/:id/stream	Stream SSE da execução em tempo real
DELETE	/tasks/:id	Cancelar tarefa em execução

Limites de uso (Rate Limiting)

Os limites variam por plano e são acordados no onboarding. Em caso de rate limit, a API retorna HTTP 429 com header Retry-After indicando quantos segundos aguardar. Cada tenant tem limites isolados — o uso de outro tenant não afeta o seu.

Codigos de Erro

Código HTTP	Código interno	Descrição
400	INVALID_INPUT	Dados de entrada invalidos ou ausentes
401	UNAUTHORIZED	Token ausente ou invalido
403	FORBIDDEN	Sem permissao para este recurso
404	NOT_FOUND	Recurso não encontrado
429	RATE_LIMITED	Limite de requisições excedido
500	INTERNAL_ERROR	Erro interno — suporte notificado automaticamente