Visão geral da API

REST sobre HTTPS, JSON na entrada e na saída, uma única URL base: https://api.oryksa.com/v1

Teste a API no navegador: Console da API.

OpenAPI e Postman

A API completa está descrita em um arquivo OpenAPI 3.1. Importe no Postman, no Insomnia ou em qualquer gerador de código, ou use a coleção Postman pronta (coloque sua chave na variável apiKey).

OpenAPI 3.1 (JSON) Coleção Postman atualizado 2026-09-28

Endpoints

Método	Endpoint	Descrição
GET	`/v1/account`	Plano, consumo e resumo do agente
PATCH	`/v1/agent`	Perfil do negócio do colaborador de IA
PATCH	`/v1/agent/appearance`	Nome, foto, saudação, sugestões
GET	`/v1/knowledge`	O que o agente sabe
PUT	`/v1/knowledge/pages`	Substituir o conteúdo do site
POST	`/v1/knowledge/crawl`	Ler um site publicado
POST	`/v1/knowledge/faq`	Adicionar ou atualizar FAQs
POST	`/v1/chat`	Mensagem do cliente, resposta da IA
GET	`/v1/conversations`	Conversas da API
GET	`/v1/conversations/{id}`	Mensagens de uma conversa
POST	`/v1/sessions`	Token temporário para um usuário do app
GET/POST	`/v1/client/*`	Chat dentro do app com o token de sessão
GET	`/v1/widget`	Código do chat para sites
PUT	`/v1/widget/domains`	Limitar o chat aos seus domínios
GET/POST	`/v1/webhooks`	Listar ou criar webhooks
DELETE	`/v1/webhooks/{id}`	Excluir um webhook
POST	`/v1/webhooks/{id}/test`	Enviar um evento de teste

Erros

Os erros sempre trazem um code legível por máquinas e uma message legível por pessoas:

{
  "error": {
    "code": "interaction_limit_reached",
    "message": "The plan's interaction limit for this period is used up.",
    "upgrade_url": "https://app.oryksa.com/billing"
  }
}

HTTP	Código	Significado
400	`invalid_request`	Falta um campo ou é inválido.
401	`unauthorized`	Chave de API ausente, errada ou revogada.
402	`plan_required`	O canal não está incluído no plano (veja upgrade_url).
402	`interaction_limit_reached`	As interações do plano deste período acabaram.
403	`account_inactive`	A conta dona da chave não está ativa.
404	`not_found`	O recurso não existe.
409	`agent_not_configured`	Configure primeiro o agente com PATCH /v1/agent.
422	`crawl_failed`	Não foi possível ler o site (por exemplo, só é exibido no navegador).
429	`rate_limited`	Pedidos demais. Aguarde retry_after segundos.
503	`agent_unavailable`	O dono desligou a IA para este canal.

Limites de requisições

Por chave de API: 120 requisições por minuto. Chat: 30 mensagens por minuto por conta. Envio de páginas: 20 por hora. Leitura de um site publicado: 10 por hora. Acima do limite a API responde 429 rate_limited.

Planos e interações

A API é um canal como o chat do site: precisa de um plano com canais web (o bônus de developer das contas conectadas pelo MCP também inclui). Cada resposta da IA conta como uma interação do plano, com os mesmos limites do WhatsApp. Os endpoints de conhecimento, agente e conversas não consomem interações.