# Versioning & Deprecation (/docs/versioning)

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](/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 `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.

## How a deprecation runs

### Announcement

The deprecation appears in the [changelog](/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](/docs/errors.md#service-unavailable).

The changelog is the authoritative notice channel today. Nothing is removed without appearing there first.

Machine-readable [`Deprecation`](https://www.rfc-editor.org/rfc/rfc9745) and [`Sunset`](https://www.rfc-editor.org/rfc/rfc8594) 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 `/v1` and 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](/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.

## Next steps

- [Changelog](/changelog): Every change to the API, including deprecations.
- [Response schema](/docs/response-schema.md): The envelope shape that additive fields extend.
- [Error handling](/docs/errors.md): The stable status and type values this policy protects.