API
Access your forms and submissions from your code.
From the Starter plan, the REST API gives you access to your forms and their submissions.
Create an API key
A key belongs to a project.
- Open the project, API keys section.
- Create a key and choose its permissions:
forms:read,forms:write: read forms, change their status.submissions:read,submissions:write: read submissions, change their status.
- Copy the key (
cfk_…). It is shown only once.
A key only gives access to the forms of its project. You can revoke it at any time.
Call the API
curl https://api.canardform.com/api/v1/forms \
-H "Authorization: Bearer cfk_your_key"
OpenAPI specification
The full API contract (routes, parameters, responses, error codes) is published as OpenAPI 3.1:
https://api.canardform.com/api/v1/openapi.yaml
Import it into Postman, Insomnia or Bruno to try the calls, or into a generator to get a typed client in your language.
To try the API with nothing to install, open the interactive explorer: https://api.canardform.com/api/v1/docs. Paste your key under “Authentication”, then send calls from the page. Calls are real: preferably use a dedicated test key with read-only scopes. The key is never stored.
Rate limits
- 120 calls per minute per API key, and 300 per minute per IP address (all keys combined).
- Every response tells you where you stand:
X-RateLimit-Limit(calls allowed per minute) andX-RateLimit-Remaining(calls left this minute). - Beyond that, the API answers
429with therate_limitedcode and aRetry-Afterheader giving the number of seconds to wait.
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."}
Wait for the time given by Retry-After before retrying. To follow new answers, prefer webhooks over repeated calls.
Error codes
Every error returns {"error": "<code>", "message": "…"}, with per-field details in errors on validation.
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_api_key |
Missing, unknown or revoked key |
| 403 | plan_upgrade_required |
The API needs the Starter or Pro plan |
| 403 | insufficient_scope |
The key lacks the required scope |
| 404 | not_found |
Resource not found, or outside the key's project |
| 422 | validation_failed |
Invalid data (details in errors) |
| 429 | rate_limited |
Rate limit reached (see Retry-After) |
SDK
To show a form on a website, use the JavaScript SDK instead (see the developer guide). It doesn't need a key.