Référence de l’API REST

Chaque action de l’interface Datarelix correspond à un point de terminaison REST, et les mêmes points de terminaison sont accessibles par programmation. URL de base : https://app.datarelix.ai. La plupart des routes sont sous /api/v1 ; les routes de connexion sont à la racine (/auth/...). Une référence interactive (Swagger / ReDoc) et le schéma OpenAPI sont servis par l’application elle-même.

Authentification

Deux identifiants sont acceptés, et l’un ou l’autre suffit :

Un cookie de session navigateur — posé lorsque vous vous connectez. C’est ce qu’utilise l’application elle-même ; aucune clé n’intervient.
Un en-tête X-API-Key — pour les appels de serveur à serveur.

curl -H "X-API-Key: $DATARELIX_API_KEY" \
  https://app.datarelix.ai/api/v1/connections

Les clés d’API sont délivrées sur demande, et non en libre-service — il n’y a pas d’écran de génération de clé dans l’application. Contactez-nous si vous en avez besoin. Le détail complet, y compris ce qui se passe lorsque les deux identifiants sont présents, est dans Authentification.

Exécution

POST   /api/v1/run                  # run a question, returns the finished RunResult
POST   /api/v1/run/stream           # same, as an SSE stream of progress + artifacts
GET    /api/v1/runs                 # ?connection_id= &status= &limit= (max 100) &offset=
GET    /api/v1/runs/{run_id}

Notez que le chemin est run (singulier) pour l’exécution et runs (pluriel) pour l’historique. Il n’existe aucun point de terminaison pour annuler une exécution — une exécution s’annule en fermant le flux SSE. (Le seul point de terminaison d’annulation de l’API concerne les tâches de découverte du schéma en arrière-plan, ci-dessous.)

Corps de requête pour les deux routes d’exécution :

Champ	Type	Notes
`question`	string	Obligatoire, 1–2 000 caractères.
`connection_id`	string	Obligatoire.
`conversation_id`	string	Facultatif — poursuit une conversation existante au lieu d’en démarrer une.
`chart_requested`	boolean	Facultatif, `false` par défaut. À définir lorsque l’utilisateur a demandé un graphique.
`selected_tables_override`	string[]	Facultatif — restreint le périmètre de tables de cette exécution.
`selected_columns_override`	object	Facultatif — nom de table → noms de colonnes, pour cette exécution uniquement.

Artefacts

GET    /api/v1/artifacts/{artifact_id}
GET    /api/v1/artifacts/{artifact_id}/download
GET    /api/v1/artifacts/{artifact_id}/render          # ?format=png|svg — server-side chart render
GET    /api/v1/runs/{run_id}/artifacts/{artifact_id}/csv      # ?rerun=true to bypass the cache
POST   /api/v1/runs/{run_id}/artifacts/{artifact_id}/refresh

L’export CSV et l’actualisation s’adressent via leur exécution — l’identifiant d’exécution fait partie du chemin, et c’est sur lui que la propriété est vérifiée.

Connexions

GET    /api/v1/connections                        # ?tag=
POST   /api/v1/connections
GET    /api/v1/connections/{id}
PATCH  /api/v1/connections/{id}
DELETE /api/v1/connections/{id}
POST   /api/v1/connections/{id}/test
POST   /api/v1/connections/{id}/duplicate
POST   /api/v1/connections/{id}/paused            # body: { "paused": true | false }
PUT    /api/v1/connections/{id}/tags
GET    /api/v1/connections/dialects               # supported engines + auth modes + availability
GET    /api/v1/connections/auth-modes             # ?dialect=postgres (required)

GET /api/v1/connections/dialects est la liste faisant autorité des moteurs et des modes d’authentification que chacun prend en charge — lisez-la plutôt que de coder une liste en dur.

POST /api/v1/connections/{id}/paused est le moyen de libérer un emplacement de connexion sans rien supprimer ; voir Facturation et formules.

Schéma

GET    /api/v1/connections/{id}/schemas           # schemas / datasets / databases in scope
GET    /api/v1/schema/{connection_id}/tables
GET    /api/v1/schema/{connection_id}/tables/{table_name}
GET    /api/v1/connections/{id}/metadata/status   # is the analyzed metadata stale?
PUT    /api/v1/connections/{id}/metadata          # curated table/column descriptions, keys
PUT    /api/v1/connections/{id}/schema-overrides  # key/relationship overrides used when planning
PUT    /api/v1/connections/{id}/schema-selection  # persisted table + column selection
PUT    /api/v1/connections/{id}/selected-tables

La liste des tables se trouve sous /api/v1/schema/{connection_id}/..., et non sous la connexion. Il n’existe pas de point de terminaison /connections/{id}/schema.

Découverte du schéma

POST   /api/v1/connections/{id}/introspect              # structure only, no AI
POST   /api/v1/connections/{id}/discover                # AI schema analysis, blocking
POST   /api/v1/connections/{id}/discover/stream         # AI schema analysis, SSE
POST   /api/v1/connections/{id}/discover/cross-schema   # relationships only, reuses metadata
POST   /api/v1/connections/{id}/discover/jobs           # start (or re-attach to) a background job
GET    /api/v1/connections/{id}/discover/jobs/active
GET    /api/v1/connections/{id}/discover/jobs/{job_id}
GET    /api/v1/connections/{id}/discover/jobs/{job_id}/stream
POST   /api/v1/connections/{id}/discover/jobs/{job_id}/cancel   # 202, best-effort

Les tâches en arrière-plan sont la voie qu’emprunte l’application : une tâche survit à un changement de page, et le flux peut être rattaché. Démarrer une nouvelle analyse IA du schéma en consomme une sur votre quota mensuel ; reprendre ou relancer une tâche qui réutilise une découverte existante, non.

Conversations

GET    /api/v1/conversations                       # ?connection_id= &limit= (max 100) &offset=
GET    /api/v1/conversations/{id}
GET    /api/v1/conversations/{id}/runs
DELETE /api/v1/conversations/{id}
DELETE /api/v1/conversations/{id}/runs/from/{from_turn_index}

La dernière est l’opération de troncature — un DELETE adressé à un index de tour, qui supprime ce tour et tout ce qui suit. C’est ce que fait, en coulisses, « modifier un message précédent et redemander ».

Modèles de requête

GET    /api/v1/connections/{id}/templates
POST   /api/v1/connections/{id}/templates
PUT    /api/v1/templates/{template_id}
DELETE /api/v1/templates/{template_id}

Tableaux de bord

GET    /api/v1/dashboards
POST   /api/v1/dashboards
GET    /api/v1/dashboards/{id}
PUT    /api/v1/dashboards/{id}
DELETE /api/v1/dashboards/{id}
POST   /api/v1/dashboards/{id}/refresh
POST   /api/v1/dashboards/{id}/items
PUT    /api/v1/dashboards/{id}/items/reorder
PUT    /api/v1/dashboards/{id}/items/{item_id}
DELETE /api/v1/dashboards/{id}/items/{item_id}
POST   /api/v1/dashboards/{id}/items/{item_id}/refresh

La mise à jour d’un tableau de bord se fait avec PUT, pas PATCH. Le réordonnancement passe par PUT .../items/reorder — une route imbriquée sous items, pas un reorder de premier niveau.

Style des graphiques

GET    /api/v1/conversations/{id}/style
POST   /api/v1/conversations/{id}/style              # apply a style patch directly, no AI
GET    /api/v1/conversations/{id}/charts/restyle     # ?run_id= &artifact_id=
GET    /api/v1/style/presets

Facturation et espace de travail

GET    /api/v1/billing/summary        # plan, status, usage this month, seats
POST   /api/v1/billing/checkout       # returns a Stripe Checkout URL
POST   /api/v1/billing/portal         # returns a Stripe customer portal URL
GET    /api/v1/workspace              # your workspace: roster for owners, summary for members
POST   /api/v1/workspace/invites
DELETE /api/v1/workspace/invites/{invite_id}
POST   /api/v1/workspace/invites/accept
DELETE /api/v1/workspace/members/{member_user_id}

Les routes d’espace de travail ne font quelque chose que sur une formule Team. Le comportement des formules est décrit dans Facturation et formules ; les codes d’erreur qu’elles renvoient sont dans Codes d’erreur.

POST /api/v1/billing/webhook existe également — c’est le rappel de Stripe, authentifié par signature, et vous ne pouvez pas l’appeler.

Compte

GET    /auth/me
GET    /auth/me/onboarding-status
GET    /auth/providers            # which sign-in methods are enabled
POST   /auth/email/register
POST   /auth/email/login
POST   /auth/email/forgot-password
POST   /auth/email/reset-password
POST   /auth/email/verify
POST   /auth/refresh
POST   /auth/logout

Ces routes sont à la racine, pas sous /api/v1. Voir Authentification.

Diffusion d’une exécution

POST /api/v1/run/stream renvoie des événements envoyés par le serveur (SSE). Chaque événement porte un nom et une charge utile JSON.

curl -N -X POST https://app.datarelix.ai/api/v1/run/stream \
  -H "X-API-Key: $DATARELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_abc",
    "question": "Top 10 customers by revenue last quarter",
    "chart_requested": true
  }'

Les événements que vous verrez :

Événement	Charge utile
`status`	`{ phase: "building_context" \| "planning" \| "executing" }`
`step_start`	`{ index, op, ref }`
`step_complete`	`{ index, status, elapsed_ms }`
`error`	`{ type, message, recoverable }`
`complete`	Le résultat complet de l’exécution

La connexion est maintenue ouverte par des commentaires périodiques de maintien en vie (heartbeat) : ne prenez donc pas un flux silencieux pour un flux mort. Pour poursuivre une conversation, passez conversation_id dans le corps de la requête.

Les échecs sont décrits par les codes d’erreur.

Idempotence

La création d’une exécution n’est pas idempotente — chaque appel crée une nouvelle exécution. Pour rejouer une question, renvoyez la même charge utile ; pour la rejouer sur place dans une conversation, tronquez d’abord à partir de l’index de tour (DELETE /api/v1/conversations/{id}/runs/from/{from_turn_index}), puis reposez la question.

Limites de débit et quotas

Deux mécanismes distincts vous freinent, et ils renvoient des corps différents :

Limite de débit — une limite fixe de requêtes par minute, actuellement 20 requêtes par minute, comptée par clé d’API (ou par utilisateur connecté lorsque vous passez par une session). La dépasser renvoie un 429 avec un détail sous forme de chaîne simple et les en-têtes Retry-After, X-RateLimit-Limit et X-RateLimit-Remaining.
Quotas de formule — questions mensuelles, analyses IA du schéma mensuelles, limites de connexions. Ceux-là renvoient un corps structuré avec un code sur lequel brancher votre logique. Voir Codes d’erreur.

Branchez votre logique sur le code du corps de réponse, jamais sur le statut seul — le 429 est partagé par le limiteur de débit et le système de quotas.