Versioning & Deprecation Policy
API/schema version metadata and how Plaidly deprecates endpoints and fields
Versioning & Deprecation Policy
Version metadata
| Surface | Current value | Where to check it |
|---|---|---|
| REST API path version | /v1 (no /v2 exists yet) | Every endpoint path in api/index |
| OpenAPI spec version | openapi: "3.1.0", info.version: "1.0" | plaidly-api/api/openapi.yaml (checked in) or GET /openapi.json with a valid X-API-Key/bearer token — see the note below, this endpoint is not currently public |
| Docs content revision | Tracked via this repo's git history | plaidly-docs commit log |
| Webhook signature scheme version | v1 (the v1=<hex> prefix in X-Plaidly-Signature) | Webhooks, HMAC verification |
GET /openapi.json currently requires the same authentication as merchant-scoped endpoints (verified live 2026-07-11: an unauthenticated request returns 401 with {"code":7,"message":"missing or invalid authorization header"}). Until it is made public, fetch a spec by registering a sandbox merchant first (see Register a merchant) and passing its api_key, or use the copy checked into plaidly-api/api/openapi.yaml.
Deprecation policy
- Additive changes ship without notice. New optional request fields, new response fields, and new endpoints are not breaking changes and are documented in place.
- Breaking changes get a new major path prefix. A breaking change to an existing
/v1endpoint (removed/renamed field, changed required-ness, changed status code semantics) ships under/v2, never as a silent change to/v1. - Minimum overlap window: 90 days. Once
/v2for a given resource is available, the corresponding/v1surface stays live for at least 90 days before removal. - Sunset is announced in-docs first. A deprecated endpoint gets a
{/* status: deprecated, sunset: YYYY-MM-DD */}marker on its docs page (and, once the planned envelope in the error model ships, aretryable: falseerror withremediationpointing at the replacement) before the removal date, not only in a changelog. - Schema fields are never repurposed. A field's type and meaning are fixed for the lifetime of
/v1; if the meaning needs to change, that's a new field or a new major version, not a silent redefinition.
Status markers used throughout these docs
Every recipe and contract page in this docs set carries one of these inline prose markers so agents (and humans) can tell what is safe to call today:
{/* status: live, verified against <source> <date> */}— the endpoint/behavior exists in production and was checked against the source listed.{/* status: planned, tracked in <ticket> */}— described here because it is a locked design decision, but not deployed; calling it will 404 or behave differently than documented.{/* status: known gap, no tracking ticket yet as of <date> */}— a real discrepancy between documented intent and current behavior that doesn't have a fix in flight yet.
These are MDX comments ({/* ... */}, not raw HTML <!-- ... --> — MDX's JSX parser chokes on a bare <!--) in the .mdx source, invisible on the rendered page. Grep the docs source for status: planned or status: known gap to get a live punch list of what's not production-ready yet.