Versioning & Deprecation
What the /v1 prefix promises, what counts as a breaking change, and the 90-day deprecation window
Every SocialCrawl endpoint lives under /v1, and /v1 does not break. We add to it freely, we do not change what is already there, and anything we retire gets at least 90 days of notice in the changelog.
The policy is a build gate, not a statement of intent. The OpenAPI description of the whole /v1 surface is diffed on every change to the API, and a breaking diff fails the build.
What /v1 promises
Once an endpoint, parameter, or response field is live under /v1, it keeps working the same way. Point production traffic at it and leave it running.
Which changes ship without notice
Additive changes cannot break a well-behaved client, so we release them at any time:
- New endpoints and new platforms.
- New optional parameters. Omitting them behaves exactly as before.
- New fields in a response body, and new response headers.
- New values in an enum that already documents itself as open-ended.
The one rule this asks of you: ignore fields you do not recognize. 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. Most JSON libraries ignore unknown keys by default, so this is usually free.
What counts as a breaking change
A change is breaking if a well-behaved existing integration could stop working because of it:
- Removing or renaming an endpoint, a parameter, or a response field.
- Changing the type or the meaning of an existing field.
- Adding a required parameter to an existing endpoint.
- Changing an error's
statusortypefor 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.
How a deprecation runs
Announcement
The deprecation appears in the changelog with the endpoint or field affected, the sunset date, and what to use instead.
At least 90 days of notice
From the announcement to the day the endpoint stops responding is a minimum of 90 days. Enterprise commitments can extend that window.
Sunset
The endpoint stops responding on the published date. A withdrawn endpoint answers 503 SERVICE_UNAVAILABLE permanently and sends no Retry-After header, which is how your client tells it apart from a transient outage. See Error handling.
The changelog is the authoritative notice channel today. Nothing is removed without appearing there first.
Machine-readable Deprecation and Sunset response headers are on the roadmap. We do not emit them yet, so do not build retirement monitoring on them. They will be announced in the changelog when they ship.
How the promise is enforced
The OpenAPI specification that describes the entire /v1 surface is diffed on every change that touches the API, and any diff classified as breaking fails the build. It cannot ship unless a maintainer explicitly approves the exception, which leaves a written record.
That is why this reads as a guarantee rather than a hope. A removed field, a tightened type, or a renamed parameter is caught by automation before it can reach you.
What this means for you
- Build against
/v1and leave it running. It will not break under you. - Tolerate new fields. Parse what you need and ignore the rest, and additive releases become invisible.
- Watch the changelog. It gives you 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.