Aller au contenu
Aide

Toutes les pages de l’aide

API

Accéder à vos formulaires et à vos réponses depuis votre code.

À partir de l'offre Starter, l'API REST donne accès à vos formulaires et à leurs réponses.

Créer une clé API

Une clé est rattachée à un projet.

  1. Ouvrez le projet, section Clés API.
  2. Créez une clé et choisissez ses droits :
    • forms:read, forms:write : lire les formulaires, modifier leur état.
    • submissions:read, submissions:write : lire les réponses, modifier leur état.
  3. Copiez la clé (cfk_…). Elle n'est affichée qu'une seule fois.

Une clé donne accès uniquement aux formulaires de son projet. Vous pouvez la révoquer à tout moment.

Appeler l'API

curl https://api.canardform.com/api/v1/forms \
  -H "Authorization: Bearer cfk_votre_cle"

Spécification OpenAPI

Le contrat complet de l'API (routes, paramètres, réponses, codes d'erreur) est publié au format OpenAPI 3.1 :

https://api.canardform.com/api/v1/openapi.yaml

Importez-le dans Postman, Insomnia ou Bruno pour tester les appels, ou dans un générateur pour obtenir un client typé dans votre langage.

Pour essayer l'API sans rien installer, ouvrez l'explorateur interactif : https://api.canardform.com/api/v1/docs. Collez votre clé dans « Authentication », puis envoyez les appels depuis la page. Les appels sont réels : utilisez de préférence une clé dédiée aux essais, avec les seuls droits de lecture. La clé n'est jamais enregistrée.

Limites d'appels

  • 120 appels par minute et par clé API, et 300 par minute et par adresse IP (toutes clés confondues).
  • Chaque réponse indique où vous en êtes : X-RateLimit-Limit (appels permis par minute) et X-RateLimit-Remaining (appels restants dans la minute).
  • Au-delà, l'API répond 429 avec le code rate_limited et l'en-tête Retry-After, qui donne le nombre de secondes à attendre.
HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{"error": "rate_limited", "message": "Too many requests."}

Attendez la durée indiquée par Retry-After avant de réessayer. Pour suivre les nouvelles réponses, préférez les webhooks à des appels répétés.

Codes d'erreur

Chaque erreur renvoie {"error": "<code>", "message": "…"}, avec le détail par champ dans errors en cas de validation.

Statut Code Signification
401 invalid_api_key Clé absente, inconnue ou révoquée
403 plan_upgrade_required L'API demande l'offre Starter ou Pro
403 insufficient_scope La clé n'a pas le droit nécessaire
404 not_found Ressource introuvable, ou hors du projet de la clé
422 validation_failed Données invalides (détail dans errors)
429 rate_limited Limite d'appels atteinte (voir Retry-After)

SDK

Pour afficher un formulaire sur un site, utilisez plutôt le SDK JavaScript (voir le guide développeur). Il ne nécessite pas de clé.