Resumen de la API
REST sobre HTTPS, JSON de entrada y salida, una única URL base: https://api.oryksa.com/v1
OpenAPI y Postman
La API completa está descrita en un archivo OpenAPI 3.1. Impórtalo en Postman, Insomnia o cualquier generador de código, o usa la colección Postman lista (pon tu clave en la variable apiKey).
OpenAPI 3.1 (JSON) Colección Postman actualizado 2026-09-28
Endpoints
| Método | Endpoint | Descripción |
|---|---|---|
| GET | /v1/account | Plan, consumo y resumen del agente |
| PATCH | /v1/agent | Perfil del negocio del empleado de IA |
| PATCH | /v1/agent/appearance | Nombre, foto, saludo, sugerencias |
| GET | /v1/knowledge | Lo que sabe el agente |
| PUT | /v1/knowledge/pages | Reemplazar el contenido del sitio |
| POST | /v1/knowledge/crawl | Leer un sitio publicado |
| POST | /v1/knowledge/faq | Añadir o actualizar FAQs |
| POST | /v1/chat | Mensaje del cliente, respuesta de la IA |
| GET | /v1/conversations | Conversaciones de la API |
| GET | /v1/conversations/{id} | Mensajes de una conversación |
| POST | /v1/sessions | Token temporal para un usuario de la app |
| GET/POST | /v1/client/* | Chat dentro de la app con el token de sesión |
| GET | /v1/widget | Código del chat para sitios |
| PUT | /v1/widget/domains | Limitar el chat a tus dominios |
| GET/POST | /v1/webhooks | Listar o crear webhooks |
| DELETE | /v1/webhooks/{id} | Eliminar un webhook |
| POST | /v1/webhooks/{id}/test | Enviar un evento de prueba |
Errores
Los errores traen siempre un code legible por máquinas y un message legible por personas:
{
"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 un campo o no es válido. |
| 401 | unauthorized | Clave de API ausente, incorrecta o revocada. |
| 402 | plan_required | El canal no está incluido en el plan (mira upgrade_url). |
| 402 | interaction_limit_reached | Las interacciones del plan de este periodo se han agotado. |
| 403 | account_inactive | La cuenta dueña de la clave no está activa. |
| 404 | not_found | El recurso no existe. |
| 409 | agent_not_configured | Configura primero el agente con PATCH /v1/agent. |
| 422 | crawl_failed | No se pudo leer el sitio (por ejemplo, solo se dibuja en el navegador). |
| 429 | rate_limited | Demasiadas peticiones. Espera retry_after segundos. |
| 503 | agent_unavailable | El dueño apagó la IA para este canal. |
Límites de peticiones
Por clave de API: 120 peticiones por minuto. Chat: 30 mensajes por minuto por cuenta. Envío de páginas: 20 por hora. Lectura de un sitio publicado: 10 por hora. Por encima del límite la API responde 429 rate_limited.
Planes e interacciones
La API es un canal como el chat del sitio: necesita un plan con canales web (el bono de desarrollador de las cuentas conectadas por MCP también lo incluye). Cada respuesta de la IA cuenta como una interacción del plan, con los mismos límites que WhatsApp. Los endpoints de conocimiento, agente y conversaciones no gastan interacciones.