Skip to content
Help

All help pages

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.

  1. Open the project, API keys section.
  2. 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.
  3. 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) and X-RateLimit-Remaining (calls left this minute).
  • Beyond that, the API answers 429 with the rate_limited code and a Retry-After header 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.