Versioning & deprecation

Version identifier

Every operation lives under /api/external/v1/*. The v1 segment is the major version — it will not change for backward-incompatible edits. When we need to make a truly breaking change (see below for what qualifies), we ship a v2 alongside v1, keep v1 live for the duration below, and help partners migrate.

Non-breaking changes (can happen in v1)

We will ship these without warning. Your integration must handle them gracefully:

• Adding new endpoints (new paths under /api/external/v1/*)
• Adding new optional request fields (body, query, header)
• Adding new fields to response bodies — treat unknown fields as ignorable
• Adding new enum values — your deserializer should accept and pass through unknown enum values rather than crash
• Adding new error codes under the RFC 7807 envelope — always branch on the stable code field, not HTTP status + message
• Tightening validation rejections when the previous behavior was a bug (e.g. returning 400 for an input that previously 500'd)
• Security-mandated breakage — revoking a leaked key, disabling a scope we announce as deprecated when a vulnerability is active

Breaking changes (require a new major version)

We consider the following breaking and will never do them in v1:

• Removing or renaming an endpoint, field, or query parameter
• Changing a field's type or semantics
• Removing an enum value
• Tightening validation on previously-accepted input shapes
• Changing authentication / scope semantics (e.g. requiring a new scope for an existing operation)
• Changing error code values — codes are the stable contract; title / detail text may evolve

Support window

• Each major version is supported for at least 12 months after its successor ships.
• During overlap, both v1 and v2 respond to requests. No feature freeze on v1 — bug fixes and new non-breaking additions continue on the older version.
• Six months before sunset, every response on the deprecated version carries the Deprecation and Sunset headers per RFC 8594. Your monitoring should alert on these.

How we announce changes

• Additive changes: appear in the OpenAPI spec at docs.parseo.app and in the changelog within 24 hours of shipping.
• Deprecations: the Deprecation header goes live on the first affected response. We also email the team owner with a migration guide.
• Breaking changes / new major versions: announced at least 90 days in advance via email + dashboard banner, with a migration guide and a v2 test-mode endpoint available for integration testing before v2 is generally available.

Client libraries

We don't ship first-party SDKs yet. Partners use the OpenAPI spec (openapi-v1.json) directly with their preferred generator (openapi-generator, OpenAPI TypeScript, Speakeasy). We track the spec JSON as a versioned artifact — pin your generator to a specific commit of the spec if you want deterministic behavior across deploys.

Questions

Drop them in support@parseo.app. We'll update this page as the policy evolves.