> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synthpop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> The API version lives in the URL — the v1 in /public/v1. There is one version today, and breaking changes arrive as a new path segment.

## 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:

```
https://app.synthpop.ai/public/v1
                              ^^
                        the contract version
```

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.

<Note>
  There is exactly **one version today: `v1`.** Every endpoint, request shape,
  and response field documented on this site is v1.
</Note>

## 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.

<Warning>
  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.
</Warning>

## 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.

<Info>
  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.
</Info>

## Recommendations

<CardGroup cols={2}>
  <Card title="Pin the base URL" icon="thumbtack">
    Store `https://<host>/public/v1` as a single configurable value. When a `v2`
    ships, you change one setting to migrate.
  </Card>

  <Card title="Parse tolerantly" icon="filter">
    Ignore unknown response fields and handle unknown enum values gracefully so
    additive changes never break you.
  </Card>

  <Card title="Watch the changelog" icon="clock-rotate-left" href="/reference/changelog">
    Additive changes and any future version are announced there.
  </Card>

  <Card title="Keep environments paired" icon="server" href="/authentication">
    Staging and production have separate hosts and separate secrets — both on the
    same `v1` contract.
  </Card>
</CardGroup>