Référence API

L'API publique NexBasira est REST + JSON, versionnée sous /api/v1/public/*. Chaque endpoint est authentifié via votre paire d'identifiants cvp_pub:cvp_sec, restreint par scope, et paginé par curseur là où il renvoie une liste.

URL de base

https://app.nexbasira.com/api/v1/public

Pour les installations auto-hébergées, remplacez l'hôte par le vôtre. Le chemin est identique.

Sections

Authentification — paire d'identifiants, schéma de signature, catalogue de scopes
Pagination + idempotence — pagination par curseur + en-tête Idempotency-Key
Erreurs + limites de débit — forme de l'enveloppe d'erreur, en-têtes X-RateLimit-*
Sessions — créer, lister, récupérer, terminer, inviter
Preuves — lister, récupérer, URL de téléchargement signée
Tableaux blancs — lister par session
Endpoints de webhook — enregistrer / faire tourner le secret / test-fire
Branding — lecture seule sur l'API publique ; les mutations passent par la SPA
Organisation — métadonnées d'organisation en lecture seule

Schéma OpenAPI

Une spécification OpenAPI 3.1 filtrée (uniquement les opérations taguées public-api) est servie à l'adresse https://app.nexbasira.com/api/public-schema/. Utilisez-la directement avec des générateurs de code :

# Node typed types
npx openapi-typescript https://app.nexbasira.com/api/public-schema/ -o src/nb-types.ts

# Python typed models
datamodel-codegen \
  --url https://app.nexbasira.com/api/public-schema/ \
  --input-file-type openapi \
  --output-model-type pydantic_v2.BaseModel \
  --output cvp_models.py

Nos SDK (@nexbasira/node + nexbasira pour Python) sont construits par-dessus ces types générés et y ajoutent une ergonomie écrite à la main — erreurs typées, pagination par itérateur asynchrone, helpers de vérification de webhook.

Stabilité de l'API

L'API publique suit un versionnement sémantique par espace de noms d'URL. Les changements cassants sont livrés sous un nouveau préfixe (/api/v2/public/*) avec au moins 12 mois de chevauchement avant le retrait de la version précédente. Les changements additifs (nouveaux champs optionnels, nouveaux endpoints, nouveaux types d'événements) sont livrés sur place ; les SDK traitent les champs inconnus comme compatibles en avant.