# Versioning and changes

How the Pozy API changes over time, how deprecations are flagged, and how to follow changes with the changelog endpoint.

The Pozy API is one continuously updated surface under `/v1`. There is no version header to pin and no dated releases to opt into. Instead, changes follow a few rules so code you write today keeps working.

## What can change without notice

These changes are additive. Write your integration so they never break it:

- New endpoints.
- New optional request fields and query parameters.
- New fields in responses, including new nested objects.
- New values in enums that describe state, such as a new post status, error code, platform id or webhook event.
- New webhook events (you only receive events you subscribed to).
- Reworded `error` messages. Branch on `code`, never on text.

In practice: ignore fields you do not know, keep a default branch when you switch on an enum, and do not fail on unknown webhook event types.

## What counts as breaking

Removing or renaming an endpoint, a field or an error `code`, making an optional field required, or changing what an existing value means. Breaking changes are announced in the changelog with `type: "breaking_change"` and `impact: "action_required"`, along with what you need to do.

## Deprecations

Endpoints that are on their way out stay working and are flagged:

- In the [OpenAPI spec](https://pozy.ai/openapi.json), with `"deprecated": true` on the operation.
- In the [API reference](https://pozy.ai/docs/api), with a deprecated label on the endpoint page.
- In the changelog, as a `deprecation` entry.

Move to the replacement when you see the flag. If a deprecated endpoint is later removed, that removal is announced as a `breaking_change` entry.

## The spec version

The spec carries a version number in `info.version` (for example `1.424.0`). It goes up with every published change to the spec. Use it to tell whether a client you generated is out of date; it is not something you send with requests.

```bash Terminal
curl -s https://pozy.ai/openapi.json | jq -r .info.version
```

## Follow changes from code

`GET /v1/changelog` lists changes newest first. It is public: no key needed.

```bash cURL
curl "https://api.pozy.ai/v1/changelog?type=breaking_change&limit=20"
```
```ts Node
// Public endpoint: no API key, so a plain fetch is enough.
const res = await fetch("https://api.pozy.ai/v1/changelog?type=breaking_change&limit=20");
const { entries } = await res.json();
for (const entry of entries) console.log(entry.publishedAt, entry.title);
```
```python Python
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/changelog",
    params={"type": "breaking_change", "limit": 20},
    timeout=30,
)
for entry in resp.json()["entries"]:
    print(entry["publishedAt"], entry["title"])
```

| Query parameter | Values |
| --- | --- |
| `type` | `new_feature`, `breaking_change`, `improvement`, `deprecation`, `minor` |
| `platform` | A platform id, such as `instagram` |
| `before` | A timestamp. Pass the previous response's `nextCursor` here for the next page. |
| `limit` | 1 to 100, default 50 |

Each entry has an `id`, `type`, `impact`, `platforms`, `title`, `summary`, `message`, `publishedAt` and a `url` to read it on the web. `impact` is `action_required` for breaking changes and `additive` for everything else. It is part of each entry, not a filter, so filter on `type=breaking_change` to get the entries that need action. When an entry is tied to spec changes, `changes.endpoints` lists the operations added, removed and modified.

A simple routine: once a day, fetch entries with `type=breaking_change` published since your last check and send them to your team's channel.

Read the same feed on the web at [/docs/changelog](https://pozy.ai/docs/changelog).

## Generated clients

If you generate a client from the spec, regenerate it when `info.version` changes and review the diff. Because changes are additive, an old client keeps working; it just cannot see new fields and endpoints.