Skip to content
reelspanDocs

Resources

Versioning

How the Reelspan API changes: what can change in v1 at any time, what counts as breaking, the notice and 12-month overlap you get, and SDK versions.

Code you write against /v1 keeps working. New features arrive without breaking it, and anything that would break it waits for a new version, with a year of overlap.

The version is in the path

Every endpoint lives under https://api.reelspan.com/v1. There is one stable version today, v1. A future v2 would live beside it at /v2, so you could move one call at a time.

Changes that can happen any time

These don't break a well-behaved client, so they ship to v1 whenever they are ready and are listed in the changelog:

  • New endpoints, and new optional request fields or query parameters.
  • New fields in responses and in webhook payloads. Ignore fields you don't know.
  • New values in lists such as networks, error codes, warnings and webhook events. Handle unknown values gracefully.
  • Higher limits, clearer error messages and new response headers. Match on error_code, never on the message text.

Write your client with that in mind: parse JSON leniently, treat an unknown error_code by its HTTP status, and don't rely on the order of keys.

Breaking changes

Removing or renaming a field or endpoint, changing a field's type or meaning, making an optional field required, or changing how authentication works. These only ship in a new version, and then:

  • We announce it at least 90 days before the new version becomes the default, by email to every account owner with an active API key, and in the changelog.
  • The old version keeps working for at least 12 months after the new one ships.
  • Responses from an endpoint that is going away carry Deprecation and Sunset headers with the date, and a Link to the migration guide.
Deprecation: @1798761600
Sunset: Mon, 01 Nov 2027 00:00:00 GMT
Link: <https://reelspan.com/…>; rel="deprecation"

A security problem is the one exception: if keeping something as it is would put accounts at risk, we change it as fast as needed and tell you why.

Networks change too

TikTok, Meta, Google and the other networks change their own APIs and rules. When a network drops or changes a feature, Reelspan adapts on its side. If a field can no longer work, the request still succeeds and the result carries a warning before the field is ever refused.

SDKs and tools

The SDKs follow semantic versioning: a new major version only when their own interface changes, never just because the API added something. Both send their version in an X-Reelspan-SDK header.

Something unclear or missing? Write to [email protected] and we’ll fix the page.