Naar de inhoud springen
Geverifieerd

Overzicht

Eén endpoint, één responsenvelop en de 337 methoden die een API-sleutel kan bereiken.

Elk scherm in het Xuda-dashboard, elk Studio-programma en elke integratie van derden roept hetzelfde HTTP-oppervlak aan: CPI, kort voor de methodedispatcher van het platform. Er is één vorm van endpoint, /cpi/<method>, en één responsenvelop. Als je die één keer kent, heb je alle 337 methoden die een API-sleutel van een account nu kan bereiken.

Het endpoint

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

<method> is een methodenaam zoals get_account_projects of dbs_read, nooit een resourcepad met een id erin. Elke invoer, ook een id, is een parameter: bij POST is het een veld in een JSON-body, bij GET een queryparameter (zie Een methode aanroepen voor de regels over body versus query en uitgewerkte voorbeelden in cURL, JavaScript en Python).

Deze documentatiesite

De documentatie wordt geserveerd op xuda.ai/docs, dus de sandbox op deze site roept /cpi/<method> aan op dezelfde origin. Je eigen code, waar die ook draait, roept https://xuda.ai/cpi/<method> direct aan.

De envelop

Elke methode, bij succes of falen, antwoordt in dezelfde vorm:

json
{ "code": 1, "data": { "...": "..." } }
  • code > 0 is succes. Het getal zelf heeft verder geen betekenis dan positief te zijn, lees data.
  • code < 0 is een fout. data is meestal een berichtstring. Een validatiefout voegt ook een veld message toe dat ervan is afgeleid. Zie Fouten voor de codes waarop je kunt vertakken en de codes die je gewoon moet loggen en tonen.
  • Een methode die een bestand of een eigen contenttype teruggeeft (een CSV-export, een afbeelding) slaat de JSON-envelop over en zet in plaats daarvan eigen headers en een eigen body. Dat is de uitzondering, niet de regel.
  • Een succesvol antwoord heeft een header xu-region met de Xuda-regio die de aanroep heeft afgehandeld. Een foutantwoord heeft die niet.

Clearance en de privémuur

Elke methode heeft een clearance: public, user, user_access, developer of admin. Dat bepaalt wie hem kan bereiken via een ingelogde dashboardsessie: een public-methode vraagt niets, de rest vraagt een sessie op dat niveau of hoger.

Een API-sleutel is een aparte muur, geen ander clearance-niveau. Een methode heeft ook een vlag private. private: true is absoluut: geen enkele API-sleutel kan hem aanroepen, ook niet een met volledige toegang, ongeacht de clearance. Ongeveer een kwart van de catalogus is in die zin openbaar: 337 methoden in 24 microservices, van Voice en Domains tot Drive en de Studio-authoring-API. De rest, inclusief elke methode op api_module zelf (de methoden die API-sleutels aanmaken en beheren), blijft alleen voor sessies. Authenticatie legt volledige versus aangepaste sleuteltoegang uit, en elke modulegids hieronder eindigt met de live tabel van wat zijn microservice beschikbaar stelt.

Een methode vinden

De interactieve API-referentie toont alle 337 methoden met hun velden en laat je er direct in de browser een uitvoeren op je eigen account.