Documentation de l’API REST

Authentification

Créez une clé API dans Paramètres (jusqu’à 3 clés actives). La clé en clair n’est affichée qu’une seule fois — conservez-la en sécurité. Envoyez-la à chaque requête comme jeton Bearer :

Authorization: Bearer vot_api_xxxxxxxxxxxxxxxx

Les requêtes sans clé valide et active reçoivent 401 Unauthorized. Si le forfait du compte est inactif, les endpoints retournent 403 Forbidden. Les clés peuvent être renouvelée (invalide instantanément l’ancien secret) ou supprimées à tout moment depuis les paramètres.

Conventions

Toutes les requêtes et réponses utilisent application/json.
Les réponses réussies encapsulent la charge utile dans un data champ.
Les erreurs utilisent l’enveloppe { "error": "<code>", "message": "<text>" }.
Les horodatages sont au format ISO‑8601 (UTC).

Endpoints

Méthode	Chemin	Description
`GET`	`/surveys`	Listez vos enquêtes.
`POST`	`/surveys`	Créer une enquête.
`GET`	`/surveys/{id}`	Obtenez une enquête avec ses questions.
`PATCH`	`/surveys/{id}`	Modifiez le titre, la description, le statut, les questions ou les paramètres.
`DELETE`	`/surveys/{id}`	Supprimez une enquête et toutes ses données.
`GET`	`/surveys/{id}/responses`	Lister les réponses (`?limit=`, `?offset=`).
`GET`	`/surveys/{id}/analysis`	Obtenir l’analyse IA mise en cache.
`POST`	`/surveys/{id}/analysis`	Générer une analyse IA globale de l’enquête (nécessite ≥3 réponses).

Exemples

Lister les enquêtes

curl -H "Authorization: Bearer $VOTIRA_API_KEY" \
  https://votira.co/api/v1/surveys

Créer une enquête

curl -X POST https://votira.co/api/v1/surveys \
  -H "Authorization: Bearer $VOTIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Pricing validation","description":"Quick check","questions":[]}'

Récupérer les réponses (paginées)

curl -H "Authorization: Bearer $VOTIRA_API_KEY" \
  "https://votira.co/api/v1/surveys/srv_123/responses?limit=50&offset=0"

Limites de taux

Les requêtes sont limitées par client. Les points de terminaison de lecture autorisent jusqu’à 600 requêtes/heure ; les écritures et l’analyse IA sont plus strictement limitées (la génération IA est plafonnée à 30/heure). Dépasser une limite renvoie 429 avec le rate_limited code d’erreur — attendez et réessayez.

Codes de statut

200 / 201 — succès.
400 — corps de requête ou paramètres invalides.
401 — clé API manquante ou invalide.
403 — forfait du compte inactif.
404 — ressource non trouvée.
422 — pas assez de données (par exemple moins de 3 réponses pour l’analyse).
429 — limite de taux dépassée.
502 — fournisseur IA temporairement indisponible.