API REST

Tout ce que fait la console passe par la même API que celle qui vous est ouverte. Il n’y a pas d’API privilégiée réservée à l’interface.

Un contrat, et sa règle d’or

L’API vit sous /api/v1. Le contrat est décrit en OpenAPI et il est stable : les évolutions sont additives.

Une fonction désactivée répond 501 feature_disabled, jamais 404. Ce n’est pas un détail de mise en œuvre, c’est ce qui rend une intégration durable :

votre code d’intégration distingue « pas disponible sur cette installation » de « vous vous êtes trompé d’URL » ;
il ne casse pas le jour où la fonction est activée.

Le corps d’une réponse 501 nomme la fonction désactivée et indique de ne pas réessayer.

S’authentifier

Deux en-têtes, sur chaque requête :

Authorization: Bearer <jeton>
X-Tenant: <votre-locataire>

C’est X-Tenant qui choisit le domaine d’authentification, pas l’URL. Le jeton vient de l’émetteur OpenID Connect de votre installation :

curl -s -X POST "https://identity.example.com/realms/$TENANT/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d "client_id=$APP_ID" -d "client_secret=$APP_SECRET"

Pour un script ou une intégration, utilisez les identifiants d’une application, pas les vôtres (voir rôles et permissions).

Le type de média, à la lettre

Chaque ressource a le sien : application/vnd.graal.systems.v1.<type>+json, où <type> est le nom exact de la ressource dans le contrat.

project · job · run · identity · assignment · library · blobmetadata · instance-type

Modifier : JSON Patch, jamais de remplacement complet

Les modifications se font en JSON Patch (RFC 6902), avec le type de média application/json-patch+json;charset=UTF-8 :

curl -s -X PATCH "$GRAAL_API/jobs/$JOB" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT" \
  -H 'Content-Type: application/json-patch+json;charset=UTF-8' \
  -d '[{"op":"replace","path":"/schedule","value":"0 6 * * *"}]'

Un PUT complet écraserait les champs qu’un autre a changés entre votre lecture et votre écriture. C’est pourquoi il n’y en a pas.

Pagination

Les listes sont paginées par page et size, et la réponse porte le total :

curl -s "$GRAAL_API/projects?page=0&size=50" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT"

Les logs font exception : ils sont paginés par curseur, parce qu’on les suit pendant qu’ils s’écrivent. La réponse porte un en-tête X-Cursor à renvoyer à l’appel suivant pour obtenir la suite — et seulement la suite.

La forme d’une erreur

{ "code": "JOB_NOT_FOUND", "message": "…", "errors": [] }

code est stable et se teste ; message est pour l’humain et peut changer. errors porte le détail champ par champ d’une erreur de validation.

Quelques codes qu’on rencontre tôt :

Code	Ce qu’il veut dire
`feature_disabled` (501)	Fonction désactivée sur cette installation. Ne pas réessayer
`TENANT_CONFIGURATION_ERROR`	Le locataire n’a pas la configuration nécessaire (souvent : l’adresse interne du stockage)
`MISSING_OWNER`	La ressource créée a besoin d’un propriétaire explicite
`JOB_NOT_FOUND`	L’identifiant n’existe pas dans ce locataire

Les grandes familles de ressources

Identité — locataires, utilisateurs, groupes, rôles, affectations, fournisseurs d’identité, applications (jetons), audit.
Workloads — projets, jobs, runs, logs, workflows, secrets, librairies, runtimes, types d’instance, quotas, graphes de l’éditeur.
Données — buckets, catalogue (couches, bases, tables, champs), entrepôts.
ML — expériences, modèles.
Exploitation — usage et coûts, notifications, tickets, recherche.

La façade MLflow

Une façade compatible avec le client MLflow pour le suivi d’expériences est servie sous /mlflow, sur le même hôte que la console et l’API. Elle implémente le sous-ensemble de l’API REST 2.0 de MLflow consacré au suivi d’expériences et au registre : voir la page machine learning.

Jetons d’API et jetons d’agent

Un jeton porte les droits d’un compte de service, soumis au même contrôle d’accès par projet qu’un utilisateur, et se révoque de la même façon. C’est le support technique du serveur MCP : chaque agent agit sous un compte de service aux droits limités.

Le contrat OpenAPI

Le contrat complet est un fichier OpenAPI : c’est de lui que se génèrent les clients, celui de la console compris. Dans la console, le menu « Copier en tant que… » rend l’appel équivalent en curl ou en appel d’outil MCP.