Versioning & Deprecation

Every SocialCrawl endpoint lives under /v1. This page states exactly what that prefix promises, so you can build on the API without wondering whether the next release will break your integration.

The short version: /v1 is stable, we add to it freely, and we never make a breaking change to it. When a breaking change is genuinely unavoidable, it ships under a new version prefix, and anything we retire gets at least 90 days' notice with machine-readable headers. A CI check enforces this on every pull request, so the promise is not a wishlist, it is a build gate.

What /v1 promises

/v1 is the stable contract. Once an endpoint, parameter, or response field is live under /v1, it keeps working the same way. You can point production traffic at it and leave it running.

Additive changes ship freely

Most of what we ship is additive, and additive changes are never breaking. We can release any of these at any time, without warning, and your integration keeps working:

• New endpoints and new platforms.
• New optional parameters on existing endpoints. Omitting them behaves exactly as before.
• New fields in a response body or new headers on a response.
• New enum values in a field that already documents itself as open-ended.

The one rule this asks of you: ignore fields you do not recognise. A response is a superset, not a fixed shape. Parse the fields you need and let unknown keys pass through untouched. If your client throws on an unexpected field, a routine additive release will look like a breakage on your side. Every mainstream JSON library ignores unknown keys by default, so this is usually free.

What counts as a breaking change

A change is breaking only if a well-behaved existing integration could stop working because of it. That means:

• Removing or renaming an endpoint, a parameter, or a response field.
• Changing the type or meaning of an existing field.
• Adding a new required parameter to an existing endpoint.
• Changing an error's status or type for the same failure.
• Tightening validation so a request that used to succeed now fails.

We do not make these changes to /v1. If one becomes unavoidable, it ships under a new prefix (/v2), and /v1 keeps running alongside it. You migrate on your own schedule, not ours.

Deprecation and sunset

On the rare occasion we retire something, we do not pull it out from under you. The process is fixed:

1. A minimum 90-day notice window. From the day a deprecation is announced to the day the endpoint stops responding is at least 90 days. Enterprise commitments can extend this.
2. Machine-readable headers. While an endpoint is deprecated, its responses carry the standard Deprecation and Sunset headers. Deprecation marks that the endpoint is on notice; Sunset gives the date it will stop responding. Watch for these headers in your monitoring and you will never be surprised by a retirement.
3. A changelog entry and a replacement. Every deprecation is recorded in the changelog, names the endpoint or field affected, and points at what to use instead.

If you are not reading deprecation headers today, the changelog is the backstop: nothing is ever removed without appearing there first.

Everything is in the changelog

The changelog is the running record of every change to the API: new platforms, new endpoints, new fields, and every deprecation. It is the one place to check what moved between the last time you integrated and now. Additive releases are logged there too, so you can see exactly what a new field is for before you decide to use it.

Enforced in CI, on every pull request

This policy is not a matter of good intentions. The OpenAPI specification that describes the entire /v1 surface is diffed on every pull request, and any change classified as breaking fails the build. A breaking change cannot merge unless a maintainer explicitly applies an override label to approve it, which creates a written record of the exception. In practice that means an accidental breaking change, a removed field, a tightened type, a renamed parameter, is caught by automation before it can ever reach you.

Most APIs promise stability in prose. Ours is checked by a machine on every change, which is why we can make it a guarantee rather than a hope.

What this means for you

• Build against /v1 and leave it running. It will not break under you.
• Tolerate new fields. Parse what you need, ignore the rest, and additive releases become invisible.
• Watch for Deprecation and Sunset headers, or follow the changelog, and you will have at least 90 days to act on anything we retire.
• You will never be migrated without warning. Breaking changes live under a new prefix, on your timeline.

Related

• Changelog: every change to the API, including deprecations.
• Response schema: the envelope shape additive fields extend.
• Error handling: the stable type and status values this policy protects.