Skip to main content
Les SDK officiels encapsulent l’API REST de Bookivox : authentification, transport HTTP, retries, timeouts, typage et gestion d’erreurs. Vous n’écrivez plus que la logique métier.

Installer les SDK

Prérequis, environnements Python et Node.js, création de la clé API, premier appel de vérification et dépannage.

Python

pip install bookivox : client typé et CLI inclus.

TypeScript

npm install @bookivox/sdk : zéro dépendance, fetch natif.

CLI

Pilotez vos agents depuis un terminal ou un job CI.
Le code source des deux SDK et de la CLI est public et auditable : github.com/limitless-influence-ai/bookivox-sdk. Les versions y sont étiquetées (v0.1.1) en même temps que leur publication sur les registres.

​
Ce que couvrent les SDK

Les SDK exposent un sous-ensemble stable et documenté de l’API, pas les 250+ routes internes. La surface publique est définie côté serveur par un marqueur (x-sdk-method) : une route qui n’est pas marquée n’existe pas dans le SDK.
La surface SDK est volontairement plus petite que l’API complète. Si une opération vous manque, elle peut être ajoutée côté serveur : le SDK est régénéré automatiquement à partir du schéma OpenAPI.

​
Authentification

Les SDK utilisent votre clé API dans l’en-tête X-API-Key. Créez-la dans Clés API ; elle n’est affichée qu’une seule fois.
Une clé API donne accès aux ressources de son organisation. Ne la commitez jamais : utilisez une variable d’environnement (BOOKIVOX_API_KEY) ou un gestionnaire de secrets.

​
Comportements communs

  • Retries : les requêtes idempotentes (GET, PUT, DELETE) sont rejouées sur 429 et 5xx, avec back-off exponentiel et jitter. Un POST n’est jamais rejoué automatiquement (risque de doublon ou de double facturation).
  • Timeouts : 30 s par défaut, configurable.
  • Erreurs typées : 401 → authentification, 403 → permission, 404 → introuvable, 422 → validation, 429 → limite de débit (avec retry_after), 5xx → serveur.
  • Origine fixe : toutes les requêtes ciblent https://api.bookivox.com, en TLS ; l’URL n’est pas configurable.
  • Aucun secret dans les logs : les clés sont masquées dans les sorties de la CLI et les exceptions.

​
Cycle de vie et versions

Les SDK sont générés depuis le schéma OpenAPI de l’API. Le contrat public est versionné : une opération publiée n’est retirée qu’avec un changement majeur documenté.
Les fichiers générés (models.py, _generated.py, types.ts, generated.ts) ne doivent jamais être édités à la main. Ils sont régénérés par sdk/generate_sdk.sh depuis le schéma OpenAPI.
Last modified on October 29, 2026