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.
- Ouvrez le projet, section Clés API.
- 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.
- 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) etX-RateLimit-Remaining(appels restants dans la minute). - Au-delà, l'API répond
429avec le coderate_limitedet l'en-têteRetry-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é.