Skip to main content

​
The version is in the URL

The Synthpop Public API is versioned by its URL path. Every request goes to a base URL that ends in a version segment:
The v1 in that path is the version of the contract you program against. Pin it in your integration and it cannot change under you: a request to /public/v1 will always speak the v1 contract.
There is exactly one version today: v1. Every endpoint, request shape, and response field documented on this site is v1.

​
The version field is decorative — do not rely on it

The API’s OpenAPI document carries an info.version string (currently 1.0.0pre). Ignore it. It is not the contract version, it does not drive routing or compatibility, and it is not guaranteed to change when the contract does.
Do not branch your integration on the info.version value from openapi.json, and do not treat 1.0.0pre as a semantic version of the API. The only version signal that matters is the v1 path segment in the base URL. Keying behavior off the decorative field is a trap — it can move without a contract change, and stay put across one.

​
The stability contract

While you stay on /public/v1, you can rely on the following:
  • Existing fields keep their meaning. A field documented in v1 will not be removed or repurposed within v1.
  • Enums may grow. New values can be added to fields like task status or issue keys. Treat unknown values defensively — for example, keep polling on a status you do not recognize rather than assuming it is terminal. The terminal statuses (completed, failed, invalid) are stable.
  • Responses may gain fields. New optional fields and new endpoints can be added without a version bump. Parse responses tolerantly and ignore fields you do not use.
  • Breaking changes do not happen in place. A change that would break an existing v1 integration is not shipped to /public/v1.

​
How breaking changes arrive

A genuinely breaking revision is introduced as a new path segment — /public/v2 — served alongside /public/v1. Both versions run at the same time during a migration window, so you upgrade on your own schedule by changing the base URL in one place, not on a flag day. When a v2 exists, this documentation will cover the differences and the migration path.
Because a new version means a new mount path, breaking changes are deliberately rare and explicit. You will never be silently moved from v1 to a newer contract.

​
Recommendations

Pin the base URL

Store https://<host>/public/v1 as a single configurable value. When a v2 ships, you change one setting to migrate.

Parse tolerantly

Ignore unknown response fields and handle unknown enum values gracefully so additive changes never break you.

Watch the changelog

Additive changes and any future version are announced there.

Keep environments paired

Staging and production have separate hosts and separate secrets — both on the same v1 contract.