← Developers

Changelog

Notable changes to the Formfy Public API. Newest first. The canonical spec lives at /api/v1/openapi.yaml — diff that file across deploys to see the source-of-truth changes.

Versioning & deprecation policy

  • Major version (v1, v2, …) pinned in the URL path. We only bump it for breaking changes.
  • Additive changes (new endpoints, new optional fields, new webhook events) ship continuously without a version bump and are always backwards-compatible.
  • Breaking changes within an active major version are avoided. If unavoidable (e.g. compliance), we ship them behind a new endpoint + give at least 12 months of notice + email every active API-key owner.
  • Deprecation is announced here AND surfaced via the Deprecation + Sunset response headers (RFC 8594 / draft-ietf-httpapi-deprecation-header).
  • Removal happens at the Sunset date, never earlier. No silent removals, no “migration to v1.x.y in 30 days” surprises.

2026-05-20

  • addedPublic developer surface launched: /developers (overview), /developers/docs (interactive Scalar reference), /developers/quickstart (5-min walkthrough).
  • addedMonthly per-user API quota with X-RateLimit-Monthly-{Limit,Remaining,Reset} headers on every authenticated response. Default 10,000/mo paid · 1,000/mo trial. Returns 429 quota_exceeded when exhausted.
  • changedAPI key creation is now plan-gated: fk_live_* requires a paid plan; free-trial accounts can mint fk_test_* keys for evaluation.
  • addedPublic /status page surfaces /api/v1/health (database, webhook_queue, api) with timestamps.

2026-05-03

1.0.0 — Phase 7 (SmartWaiver parity)

  • addedWebhook management endpoints: POST/GET /webhooks, GET/PATCH/DELETE /webhooks/{id}, POST /webhooks/{id}/rotate-secret.
  • addedwebhooks: section in the OpenAPI spec documenting form.created, form.sent, form.viewed, form.signed, form.expired payloads.
  • addedGET /forms/{id}/signers — list every recipient with their per-recipient delivery + view + sign timestamps.
  • addedForms list filters: ?status=, ?created_after=, ?created_before=, ?cursor= for pagination.
  • addedX-Formfy-Prefill-Unmatched response header on POST /forms — lists prefill keys that didn't map to any template field, so partners spot typos.
  • addedPOST /forms/generate — natural-language prompt → ready-to-send form (skips the template step).

2026-05-01

1.0.0 — Initial public v1

  • addedBearer-token auth with separate fk_live_* / fk_test_* key partitions. Test partition is fully isolated; a live key cannot read test data and vice versa.
  • addedEndpoints: /health, /openapi.yaml, /templates, /forms (CRUD), /forms/{id}/send, /forms/{id}/signed-pdf, /files/pdf/{token}.
  • addedStandard error envelope { error: { type, code, message, param?, request_id } } on every non-2xx.
  • addedFormfy-Request-Id: req_<32hex> on every response (success and error).
  • addedPer-endpoint sliding-window rate limiting with X-RateLimit-{Limit,Remaining,Reset} headers.
  • addedOpenAPI 3.1 spec at /api/v1/openapi.yaml — auto-consumable by openapi-generator, openapi-typescript, @hey-api/openapi-ts.

Want to be notified about deprecations and major releases? Drop us a line at dev@formfy.ai and we'll add you to the API announcements list.