Developer policy
GoFaceless API versioning and deprecation
A predictable contract for agents, SDKs, automation platforms, and long-running integrations.
Stable path and calendar contract
The public REST surface is served below /api/v1. Clients can pin a calendar contract with the GoFaceless-Version request header. Omitting that header selects the current stable contract. An unsupported value returns a 400 problem-detail response before the requested operation runs, so a version mistake cannot trigger generation or spend.
Deprecation signals
When a supported contract enters deprecation, every response using it includes Deprecation: true, an HTTP-date Sunset header, and a Link back to this policy. The announced sunset date is the end of support for that contract, not an automatic migration date. GoFaceless publishes a replacement contract and updated OpenAPI description before the sunset date.
Migration guidance
Clients should record version and deprecation headers, compare the new OpenAPI schema, regenerate typed clients where applicable, exercise deterministic sandbox fixtures, and then replay their own integration tests. Keep idempotency keys stable only for identical retries. Generate a new key when the intended command changes.