Versioning

The version is in the path

https://feedhorizon.com/api/v1

All endpoints are under v1. A new major version would get a new path (/api/v2), and v1 would keep working alongside it for a transition period announced in the Changelog.

What may change within v1

These changes happen without a new version, so your code should tolerate them:

• New endpoints.
• New optional request fields and query parameters.
• New fields in responses and webhook payloads. Ignore fields you do not know.
• New values in lists that are open by nature: webhook events, error codes, publishing error codes, platforms and account statuses. Handle unknown values with a default branch.
• New warnings in POST /posts/validate.
• Wording of message texts. Branch on code, never on message.
• Platform limits, when a platform changes them. Platform support and GET /platforms always show the current ones.

What does not change within v1

• Removing or renaming an endpoint, a field or an enum value.
• Changing the type or meaning of a field.
• Making an optional request field required.
• Changing the status code or error code of an existing error case.
• Changing the format of ids, webhook signatures or rate limit headers.

If a platform forces such a change on us, for example by ending an API, we announce it in the Changelog as early as we can.

How you hear about changes

• The Changelog lists every change with its date.
• The reference pages and /openapi.json are generated from the code that serves the API, so they always describe the API as it runs now.