Aller au contenu
Vérifié

Vue d'ensemble

Un seul endpoint, une seule enveloppe de réponse et les 337 méthodes qu'une clé API peut atteindre.

Chaque écran du tableau de bord Xuda, chaque programme Studio et chaque intégration tierce appelle la même surface HTTP : CPI, abréviation du répartiteur de méthodes de la plateforme. Il n'y a qu'une forme d'endpoint, /cpi/<method>, et une seule enveloppe de réponse. L'apprendre une fois couvre les 337 méthodes qu'une clé API de compte peut atteindre aujourd'hui.

L'endpoint

POST https://xuda.ai/cpi/<method>GET  https://xuda.ai/cpi/<method>

<method> est un nom de méthode tel que get_account_projects ou dbs_read, jamais un chemin de ressource contenant un identifiant. Chaque entrée, identifiant compris, est un paramètre : avec POST, c'est un champ d'un corps JSON ; avec GET, c'est un paramètre de chaîne de requête (voir Appeler une méthode pour les règles corps ou requête et des exemples complets en cURL, JavaScript et Python).

Ce site de documentation

La documentation est servie sur xuda.ai/docs, donc le bac à sable de ce site appelle /cpi/<method> sur la même origine. Votre propre code, où qu'il s'exécute, appelle directement https://xuda.ai/cpi/<method>.

L'enveloppe

Chaque méthode, en cas de succès comme d'échec, répond avec la même forme :

json
{ "code": 1, "data": { "...": "..." } }
  • code > 0 signifie succès. Le nombre lui-même n'a pas d'autre sens que d'être positif, lisez data.
  • code < 0 signifie erreur. data est généralement une chaîne de message ; un échec de validation ajoute aussi un champ message qui en est dérivé. Voir Erreurs pour les codes sur lesquels brancher votre logique et ceux qu'il suffit de journaliser et d'afficher.
  • Une méthode qui renvoie un fichier ou un type de contenu personnalisé (un export CSV, une image) saute l'enveloppe JSON et définit ses propres en-têtes et son propre corps. C'est l'exception, pas la règle.
  • Une réponse réussie porte un en-tête xu-region qui indique la région Xuda ayant traité l'appel. Une réponse d'erreur ne le porte pas.

L'habilitation et le mur privé

Chaque méthode porte une clearance : public, user, user_access, developer ou admin. C'est qui peut l'atteindre via une session de tableau de bord connectée : une méthode public n'exige rien, les autres exigent une session à ce niveau ou au-dessus.

Une clé API est un mur à part, pas une autre habilitation. Une méthode porte aussi un indicateur private. private: true est absolu : aucune clé API ne peut l'appeler, pas même une clé à accès complet, quelle que soit son habilitation. Environ un quart du catalogue est public en ce sens : 337 méthodes réparties sur 24 microservices, de Voice et Domains jusqu'à Drive et l'API de création de Studio. Le reste, y compris chaque méthode de api_module lui-même (les méthodes qui créent et gèrent les clés API), reste réservé aux sessions. Authentification détaille l'accès complet ou personnalisé d'une clé, et chaque guide de module ci-dessous se termine par le tableau en direct de ce que son microservice expose.

Trouver une méthode

La référence API interactive liste les 337 méthodes avec leurs champs, et vous permet d'en exécuter une sur votre propre compte directement depuis le navigateur.