# SDKs Vibedasher fournit des SDKs officiels, entièrement typés, pour **TypeScript** et **Python**, générés à partir de la spécification OpenAPI de l'API afin de rester en phase avec la plateforme. C'est ainsi que votre propre code atteint la plateforme maintenue : exécuter du SQL contre vos jeux de données, déclencher des actualisations, gérer les connexions et les droits d'accès, câbler un tableau de bord à des données en direct, ou automatiser depuis un script tout ce que font les [outils MCP](/fr/guides/build-with-your-agent.md) depuis un agent. | Langage | Paquet | Documenté ici | | ---------- | ------------------------------------------------------------------------ | ------------- | | TypeScript | [`@vibedasher/client`](https://www.npmjs.com/package/@vibedasher/client) | 4.1.5 | | Python | [`vibedasher`](https://pypi.org/project/vibedasher/) | 4.3.19 | Les deux SDKs s'authentifient avec une **clé API** dans l'en-tête `X-Api-Key`. Générez-en une dans l'application sous **Paramètres → Clés API** sur [cloud.vibedasher.com](https://cloud.vibedasher.com) — voir [Authentification](/fr/api/authentication.md). (Les SDKs sont le chemin *code* ; si votre agent pilote Vibedasher via MCP, il se connecte avec `vibedasher login` à la place et n'a besoin d'aucune clé — voir [Construire avec votre agent](/fr/guides/build-with-your-agent.md).) Aucun des deux clients n'a besoin qu'on lui dise dans quelle région vit votre compte. Sans URL de base et sans `region`, tous deux résolvent vers `https://api.vibedasher.com/api`, qui route chaque requête d'après l'identifiant qu'elle porte — voir [Un seul hôte, routé par votre identifiant](/fr/api/authentication.md#one-host-routed-by-your-credential). Passer `region` reste pris en charge et épingle le client au nom d'hôte propre à cette région, `https://api.{region}.vibedasher.com/api` ; un `baseUrl` / `base_url` explicite l'emporte sur les deux. (`region` est devenu optionnel dans `@vibedasher/client` 4.1.5 et `vibedasher` 4.3.19.) Vous cherchez un endpoint spécifique ? Parcourez la **[Référence API](/fr/reference/vibedasher-sdk-api.md)** complète — chaque opération groupée par ressource, avec des exemples de requêtes curl / Python / TypeScript générés à partir des mêmes signatures que les SDKs. ## La forme de chaque appel[​](#la-forme-de-chaque-appel "Lien direct vers La forme de chaque appel") Les deux SDKs exposent le même **client fluent groupé par ressource**. Construisez-le une fois, puis appelez des méthodes groupées par ressource. Les signatures sont **plates** : d'abord les paramètres de chemin (dans l'ordre du chemin), puis le corps de la requête, puis un objet d'options final optionnel portant les paramètres de requête. Il n'y a pas d'objets d'enveloppe `path` / `query` / `body`. Les ressources sont les mêmes 23 dans les deux langages, en camelCase en TypeScript et en snake\_case en Python : `accounts`, `aiProviders`, `apiKeys`, `chats`, `connections`, `dashboardSubscriptions`, `datasets`, `dbt`, `embedTokens`, `folders`, `groups`, `images`, `questions`, `refreshes`, `skills`, `sql`, `subscriptions`, `tasks`, `templates`, `tools`, `upload`, `users`, `viz`. Une réponse non-2xx **lève une exception** — `VibedasherApiError` dans les deux langages. Les méthodes ne se résolvent jamais en une union d'erreur, vous n'avez donc pas à vérifier un résultat avant de l'utiliser. ## TypeScript[​](#typescript "Lien direct vers TypeScript") ``` npm install @vibedasher/client ``` ``` import { Vibedasher, VibedasherApiError } from '@vibedasher/client'; const client = new Vibedasher({ apiKey: process.env.VIBEDASHER_API_KEY!, }); // List datasets — query params go in the trailing options object const page = await client.datasets.list({ limit: 50 }); // Create — the body is positional const created = await client.datasets.create({ name: 'Sales', type: 'csv' }); // Fetch one by id — path params are positional const one = await client.datasets.get(created.dataset.id); // Update — path param, then body const updated = await client.datasets.update(one.dataset.id, { name: 'Sales 2026' }); ``` Chaque méthode est typée de bout en bout : les types d'arguments et le type de réponse résolu proviennent de la spécification, et les interfaces par ressource (`DatasetsResource`, `DatasetsListOptions`, …) et les types de modèle (`DatasetResponse`, `DatasetUpdate`, …) sont exportés depuis la racine du paquet si vous voulez annoter une variable. ### Exécuter du SQL[​](#exécuter-du-sql "Lien direct vers Exécuter du SQL") `client.query` est la méthode écrite à la main que la surface générée n'a pas : un appel en entrée, des résultats colonnaires typés en sortie. ``` const result = await client.query({ sql: 'SELECT country, SUM(revenue) AS revenue FROM sales GROUP BY 1', }); console.log(result.columns, result.rows); ``` `datasetIds` est optionnel — omettez-le et le serveur résout l'ensemble de jeux de données à partir des alias que votre SQL référence, en appliquant exactement la même autorisation. ### Importer un CSV[​](#importer-un-csv "Lien direct vers Importer un CSV") ``` const uploaded = await client.datasets.upload({ name: 'Sales', content: 'country,revenue\nFR,10\nDE,12\n', }); console.log(uploaded.cleanSQLName); // the alias to use in client.query SQL ``` ### Échappatoire[​](#échappatoire "Lien direct vers Échappatoire") Le client `fetch` sous-jacent est disponible sur l'instance en tant que `client.http` si vous avez besoin d'intercepteurs, d'un `fetch` personnalisé, ou de surcharges par appel. Il n'y a pas de singleton au niveau du module à configurer : chaque instance `Vibedasher` possède son propre client, donc deux clients dans un même processus n'écrasent jamais mutuellement leur URL de base ou leur clé. ## Python[​](#python "Lien direct vers Python") ``` pip install vibedasher ``` ``` from vibedasher import Vibedasher, VibedasherApiError from vibedasher.models import DatasetCreate, DatasetUpdate client = Vibedasher(api_key="") # List datasets — query params are keyword-only page = client.datasets.list(limit=50) # Create — the body is the first positional argument created = client.datasets.create(DatasetCreate(name="Sales", type_="csv")) # Fetch one by id — path params are positional one = client.datasets.get(created.dataset.id) # Update — path param, then body updated = client.datasets.update(one.dataset.id, DatasetUpdate(name="Sales 2026")) ``` Les modèles de requête et de réponse vivent dans `vibedasher.models`. Les attributs de ressource sont en snake\_case (`client.datasets`, `client.api_keys`, `client.ai_providers`, `client.embed_tokens`, `client.viz`, …), et les méthodes aussi. ### Exécuter du SQL[​](#exécuter-du-sql-1 "Lien direct vers Exécuter du SQL") ``` result = client.query(sql="SELECT country, SUM(revenue) AS revenue FROM sales GROUP BY 1") print(result.columns, result.rows) ``` ### Importer un CSV[​](#importer-un-csv-1 "Lien direct vers Importer un CSV") ``` uploaded = client.datasets.upload(name="Sales", content="country,revenue\nFR,10\nDE,12\n") print(uploaded["cleanSQLName"]) # the alias to use in client.query SQL ``` ### Échappatoire[​](#échappatoire-1 "Lien direct vers Échappatoire") Les modules d'opération plats sous `vibedasher.api.` sont encore fournis pour tout ce que la façade ne couvre pas. Construisez un client brut avec `create_client` et appelez `.sync()`, `.sync_detailed()`, `.asyncio()`, ou `.asyncio_detailed()` : ``` from vibedasher import create_client from vibedasher.api.datasets import read_datasets raw = create_client(api_key="") datasets = read_datasets.sync(client=raw) ``` ## Gestion des erreurs[​](#gestion-des-erreurs "Lien direct vers Gestion des erreurs") Les deux SDKs lèvent une exception sur une réponse non-2xx, si bien que le chemin heureux se lit directement et les erreurs sont attrapées là où vous voulez les gérer. **TypeScript :** ``` import { Vibedasher, VibedasherApiError } from '@vibedasher/client'; try { const page = await client.datasets.list({ limit: 50 }); console.log(page.datasets); } catch (err) { if (err instanceof VibedasherApiError) { console.error(`Request failed (${err.status})`, err.detail, err.requestId); } else { throw err; } } ``` **Python :** ``` from vibedasher import VibedasherApiError try: page = client.datasets.list(limit=50) except VibedasherApiError as err: print(f"Request failed ({err.status_code})", err.detail, err.request_id) ``` Codes de statut courants : **401/403** (clé API manquante ou invalide, ou une clé utilisée sur une route réservée à la session), **404** (introuvable, ou une viz non publiée), **422** (erreur de validation de requête). La page de référence de chaque endpoint liste les réponses exactes qu'il peut renvoyer. ## Pagination[​](#pagination "Lien direct vers Pagination") Les endpoints de liste renvoient une page de résultats plus un curseur `nextKey`. Vous avez rarement besoin de piloter ce curseur vous-même : chaque ressource listable porte `iterAll()` (TypeScript) / `iter_all()` (Python), qui parcourt les pages et produit les lignes. **TypeScript :** ``` for await (const ds of client.datasets.iterAll()) { handle(ds); } ``` **Python :** ``` for ds in client.datasets.iter_all(): handle(ds) ``` Les deux exposent aussi la forme au niveau page (`iterPages()` / `iter_pages()`) quand vous voulez l'enveloppe plutôt que les lignes. Piloter le curseur à la main fonctionne toujours — repassez `nextKey` en tant que `exclusiveStartKey` (`exclusive_start_key` en Python) et arrêtez-vous quand il revient à `null`/`None` — mais les itérateurs détectent aussi un curseur qui cesse d'avancer et lèvent une exception plutôt que de boucler indéfiniment. Le nom sur le fil — celui qu'affichent l'onglet cURL et le tableau des paramètres de chaque page de référence — est toujours `exclusiveStartKey` ; le SDK TypeScript garde cette graphie camelCase comme clé d'option, et le SDK Python expose le même paramètre sous le mot-clé `exclusive_start_key`. C'est un seul curseur, orthographié selon le langage — jamais les deux dans une même requête. ## Mise en garde sur le typage des réponses[​](#mise-en-garde-sur-le-typage-des-réponses "Lien direct vers Mise en garde sur le typage des réponses") Certaines routes de l'API renvoient actuellement des réponses faiblement typées (`object` / `Any`) parce qu'elles déclarent une forme de réponse générique côté backend. Les corps de requête, les paramètres de requête/chemin, et un ensemble croissant de réponses sont entièrement typés. Les types de réponse sont durcis module par module — mettez à jour le SDK pour bénéficier des améliorations. remarque Les SDKs sont générés, jamais édités à la main. Si vous repérez une lacune, c'est presque toujours en amont dans la spécification OpenAPI de l'API — contactez-nous via la [page de contact](https://vibedasher.com/contact).