Formcrest
Log inGet started

API versioning

The rules we follow so an integration you build today keeps working — including the form action URLs embedded in your sites.

The /v1 prefix is permanent

Every endpoint lives under a version prefix — /v1/submit/…, /v1/api/… — and /v1 never goes away while it has users. This matters most for the submit endpoint: the action URL pasted into your HTML forms keeps working without edits.

What can change inside /v1

Additive, backwards-compatible changes ship without a version bump. Expect us to:

  • add new endpoints;
  • add new optional request fields and parameters;
  • add new fields to JSON responses;
  • add new values to the error-code catalog.

Write clients accordingly: ignore response fields you don't recognize, and treat unknown error codes as generic failures of their HTTP status class.

What never changes inside /v1

  • Existing fields are not removed or renamed, and their types don't change.
  • Existing endpoints are not removed, and their semantics don't change.
  • Existing error codes keep their meaning and status — they are part of the contract (see Error codes).
  • Authentication schemes (session cookies, fc_live_ Bearer keys) are not dropped.

Breaking changes ship as /v2

If we ever need a breaking change, it ships under a new prefix, and /v1 keeps working for at least 12 months after /v2 is generally available. Deprecations are announced by email to affected account owners and documented here well before any cutoff.

API keys and rate limits

Management-API keys are not tied to an API version — the same fc_live_ key works across versions. Rate limits (currently 120 requests/minute per key) may be tuned over time; we treat raising limits as non-breaking and will announce any reduction in advance.

Next steps