--- title: "Référence de l’API REST" description: "Points de terminaison REST de Datarelix : connexions, découverte du schéma, exécutions, artefacts, conversations, tableaux de bord, facturation. Chemins et méthodes vérifiés." canonical: https://docs.datarelix.ai/fr/api/rest/ --- # 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. ```bash 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](https://datarelix.ai/fr/contact/) 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](/fr/api/auth/). ## 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](/fr/guides/billing/). ## 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](/fr/guides/billing/) ; les codes d'erreur qu'elles renvoient sont dans [Codes d'erreur](/fr/api/errors/). `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](/fr/api/auth/). ## 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. ```bash 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](/fr/api/errors/). ## 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](/fr/api/errors/). 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.