Visão geral da API

REST sobre HTTPS, JSON à entrada e à saída, um único URL base: https://api.oryksa.com/v1

Experimenta a API no browser: Consola da API.

OpenAPI e Postman

A API completa está descrita num ficheiro OpenAPI 3.1. Importa-o no Postman, no Insomnia ou em qualquer gerador de código, ou usa a coleção Postman pronta (põe a tua 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 utilizador da app
GET/POST	`/v1/client/*`	Chat dentro da app com o token de sessão
GET	`/v1/widget`	Código do chat para sites
PUT	`/v1/widget/domains`	Limitar o chat aos teus domínios
GET/POST	`/v1/webhooks`	Listar ou criar webhooks
DELETE	`/v1/webhooks/{id}`	Apagar um webhook
POST	`/v1/webhooks/{id}/test`	Enviar um evento de teste

Erros

Os erros trazem sempre 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 em falta, errada ou revogada.
402	`plan_required`	O canal não está incluído no plano (vê 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`	Configura primeiro o agente com PATCH /v1/agent.
422	`crawl_failed`	Não foi possível ler o site (por exemplo, só é desenhado no browser).
429	`rate_limited`	Demasiados pedidos. Espera retry_after segundos.
503	`agent_unavailable`	O dono desligou a IA para este canal.

Limites de pedidos

Por chave de API: 120 pedidos 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 ligadas pelo MCP também o 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 gastam interações.