Versioning and changes

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, with "deprecated": true on the operation.
• In the API reference, 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.

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.

curl "https://api.pozy.ai/v1/changelog?type=breaking_change&limit=20"

// 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);

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"])

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.

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