Changelog & deprecation policy
What we promise not to break, and what has changed so far.
What is stable
/v1 is a promise. Inside a major version we will make additive changes and nothing else.
| We may | We will not |
|---|---|
| Add a new endpoint | Remove or rename an endpoint inside a major version |
| Add an optional request field | Add a required request field, or tighten validation on an existing one |
| Add a field to a response | Remove or rename a response field, or change its type |
| Add a value to an enum-like field | Remove a value, or change what an existing one means |
| Add a webhook event | Change the payload of an existing event incompatibly |
| Add an error code | Reuse an error code for a different failure |
If we ever have to break something
- It goes in a new major version —
/v2— and never into/v1. /v1keeps working for at least twelve months after/v2is generally available.- We tell you before, not after, and we tell you which of your keys are calling the affected routes — we can see that, and it is more useful than a blanket announcement.
- A migration guide ships with the new version, naming every changed shape.
What is not covered
Three things are explicitly outside the promise, so nobody builds on them by accident:
- The design document’s internal shape. It carries a
schemaVersionand is migrated forward as the editor evolves. Read it through the API; do not store a copy and parse it yourself. - Anything outside
/v1. The first-party product API is private and changes freely. - The sandbox. Its data is wiped without notice; that is what makes it a sandbox.
SDK versioning
@foldkit/embed and @foldkit/node follow semantic versioning. Pin a major version; minors are additive.
The SDK and the editor are versioned independently, and that is worth understanding rather than treating as an accident: you pin an SDK version in your page, and the iframe is whatever we deployed this morning. Both ends therefore ignore messages and fields they do not recognise, which is what lets us ship the editor daily without breaking a page nobody has redeployed in a year.
Changes
v1.0.0
The first public version of the partner API.
/v1/designs— create, list, read, update, archive, delete; versions andpreview.png./v1/exports— start an export, list and read jobs. SVG, DXF, dieline PDF and PDF/X-4./v1/assets— presigned upload, confirm, read./v1/styles,/v1/templates,/v1/quotes— your filtered catalog and your leads./v1/webhooks— endpoints, deliveries, replay, secret rotation with an overlap./v1/usage— metered consumption against allowance, for reconciling an invoice./v1/embed-sessions— mint a single-use session token.
@foldkit/embed 0.1.0 · @foldkit/node 0.1.0
Foldkit.mount(), the command set, the event set, silent token renewal.- Webhook signature verification and signing, with the raw-body discipline enforced by the type.
Keeping up
This page is the record. If you want to be told rather than to check, say so and we will add you to the API announcements list — it is low volume and carries breaking-change notices first.
The generated spec at the API reference is regenerated from the contract on every build, so a diff of openapi.json is the most precise view of what changed.