> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning & Deprecation

> How the API is versioned, how deprecations are announced, and the sunset guarantees you can build against

## Versioning

The API is versioned in the URL path. `v1` is the current and only version:

```
https://api.politicalcomms.com/v1
```

* **Breaking changes ship as a new version path** (`/v2`), never inside `v1`. A breaking change is anything that removes an endpoint or field, renames one, changes a type, tightens validation on existing input, or changes the meaning of an existing response value.
* **Additive changes land in `v1` without notice**: new endpoints, new optional request fields, new response fields, new enum values on fields documented as extensible. Build clients that ignore unknown response fields.

## Deprecation policy

When an endpoint, parameter, or field is deprecated:

1. It is marked `deprecated: true` in the [OpenAPI specification](https://politicalcomms.com/openapi.json) — the spec is the source of truth.
2. The deprecation is announced in the [changelog](/changelog).
3. When an endpoint is scheduled for removal, its responses will carry a `Deprecation` header, and once a removal date is committed, a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the removal timestamp. No endpoint is deprecated today, so no live response currently carries these headers.
4. The deprecated surface keeps working alongside its replacement for **at least 90 days** after the `Sunset` date is announced. Nothing is removed silently.

An example already live today: `phone_number_id` on `POST /projects` is deprecated in favor of `phone_number_ids[]`; both are accepted while the migration window is open.

## What agents should do

* Check the spec's `deprecated` flags before generating integration code; prefer the replacement surface whenever one is documented.
* Watch for `Deprecation` and `Sunset` response headers and surface them to a human operator.
* Treat unknown response fields as additive evolution, not an error.