Présentation de l'API
REST sur HTTPS, JSON en entrée et sortie, une URL de base : https://api.oryksa.com/v1
OpenAPI et Postman
L'ensemble de l'API est décrit dans un fichier OpenAPI 3.1. Importez-le dans Postman, Insomnia ou tout générateur de code, ou utilisez la collection Postman prête à l'emploi (définissez la variable apiKey sur votre clé).
OpenAPI 3.1 (JSON) Collection Postman mis à jour le 28/09/2026
Points de terminaison
| Méthode | Point de terminaison | Description |
|---|---|---|
| GET | /v1/account | Résumé du plan, de l'utilisation et des agents |
| PATCH | /v1/agent | Profil professionnel de l'employé IA |
| PATCH | /v1/agent/appearance | Nom, photo, message d'accueil, suggestions |
| GET | /v1/knowledge | Connaissances de l'agent |
| PUT | /v1/knowledge/pages | Remplacer le contenu du site |
| POST | /v1/knowledge/crawl | Lire un site en direct |
| POST | /v1/knowledge/faq | Ajouter ou mettre à jour des FAQ |
| POST | /v1/chat | Message client entrant, réponse IA sortante |
| GET | /v1/conversations | Conversations API |
| GET | /v1/conversations/{id} | Messages d'une conversation |
| POST | /v1/sessions | Jeton temporaire pour un utilisateur d'application |
| GET/POST | /v1/client/* | Chat intégré avec le jeton de session |
| GET | /v1/widget | Extrait de chat pour site web |
| PUT | /v1/widget/domains | Restreindre le chat à vos domaines |
| GET/POST | /v1/webhooks | Lister ou créer des webhooks |
| SUPPRIMER | /v1/webhooks/{id} | Supprimer un webhook |
| POST | /v1/webhooks/{id}/test | Envoyer un événement de test |
Erreurs
Les erreurs sont toujours accompagnées d'une valeur lisible par machine code et d'une valeur lisible par humain message:
{
"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 | Code | Signification |
|---|---|---|
| 400 | invalid_request | Un champ est manquant ou invalide. |
| 401 | unauthorized | Clé API manquante, incorrecte ou révoquée. |
| 402 | plan_required | Le canal n'est pas inclus dans l'offre (voir upgrade_url). |
| 402 | interaction_limit_reached | Les interactions du forfait pour cette période sont épuisées. |
| 403 | account_inactive | Le compte propriétaire de la clé n'est pas actif. |
| 404 | not_found | La ressource n'existe pas. |
| 409 | agent_not_configured | Configurez d'abord l'agent avec PATCH /v1/agent. |
| 422 | crawl_failed | Le site n'a pas pu être lu (par exemple il ne s'affiche que dans le navigateur). |
| 429 | rate_limited | Trop de requêtes. Veuillez attendre retry_after secondes. |
| 503 | agent_unavailable | Le propriétaire a désactivé l'IA pour ce canal. |
Limites de débit
Par clé API : 120 requêtes par minute. Chat : 30 messages par minute et par compte. Lecture de pages : 20 par heure. Lecture d’un site en direct : 10 par heure. Au-delà de la limite, l’API répond 429 rate_limited.
Offres et interactions
L’API est un canal comme le chat du site web : elle nécessite une offre incluant les canaux web (le bonus développeur des comptes connectés via le MCP l’inclut également). Chaque réponse de l’IA compte pour une interaction de l’offre, avec les mêmes limites que WhatsApp. Les endpoints knowledge, agent et conversations n’utilisent pas d’interactions.