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

# Versioning

> How Operata versions the API by URL prefix, what counts as a breaking change, and how deprecations are announced via response headers.

Operata versions the API by URL prefix. The current stable version is `v1`. Endpoints under `/v2/` are stable but scoped to admin-only surfaces today. Breaking changes ship behind a new prefix; additive changes ship in place.

## Endpoint

```http theme={null}
https://api.operata.io/v1/...
https://api.operata.io/v2/...
```

## Parameters

There's no version header — the version lives in the path. Pin your client to the prefix you tested against.

| Prefix | Status | Surface                                                                                                                                                 |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/v1/` | stable | Data endpoints (`/v1/data/calls`, `/v1/data/{contactId}`, `/v1/data/calls/{contactId}/details`, `/v1/data/ccpLogs`), redaction config (`/v1/config/*`). |
| `/v2/` | stable | Admin endpoints (`/v2/admin/users`). New admin endpoints land here, not under `/v1/`.                                                                   |

## Response

Operata signals deprecation on the response headers of any endpoint scheduled for removal:

```http theme={null}
HTTP/1.1 200 OK
Deprecation: true
Sunset: Tue, 17 Nov 2026 00:00:00 GMT
Link: <https://operata.io/docs/api-changelog>; rel="deprecation"
```

| Header        | When present                    | Meaning                                                            |
| ------------- | ------------------------------- | ------------------------------------------------------------------ |
| `Deprecation` | the endpoint is deprecated      | Always the literal string `true`.                                  |
| `Sunset`      | the endpoint has a removal date | RFC 7231 HTTP date. The endpoint stops responding after this date. |
| `Link`        | always with `Deprecation`       | Points at the changelog entry that describes the replacement.      |

The Operata change policy:

* **Additive changes ship in place.** New optional fields on responses, new optional query parameters, new endpoints under an existing version. Your client keeps working without changes.
* **Breaking changes ship under a new prefix.** Renamed fields, removed fields, changed types, new required parameters, changed status codes, changed error codes — these go to the next major version. Operata does not silently change the wire shape of an existing endpoint.
* **Deprecation window is six months minimum.** From the day a `Sunset` header first appears, you have at least six months before the endpoint stops responding. Watch the [API changelog](/docs/api-changelog) for the announcement.

## Example

A deprecation-aware client inspects response headers on every call:

<CodeGroup>
  ```bash curl theme={null}
  curl -i -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
    "https://api.operata.io/v1/data/calls?size=1" \
    | grep -iE '^(deprecation|sunset|link):'
  ```

  ```python Python theme={null}
  import os, requests
  from email.utils import parsedate_to_datetime

  response = requests.get(
      "https://api.operata.io/v1/data/calls",
      auth=(os.environ["OPERATA_GROUP_ID"], os.environ["OPERATA_API_TOKEN"]),
      params={"size": "1"},
  )
  if response.headers.get("Deprecation") == "true":
      sunset = response.headers.get("Sunset")
      print(f"deprecated; sunsets {sunset}")
      if sunset:
          deadline = parsedate_to_datetime(sunset)
          # Schedule the migration before deadline.
  ```
</CodeGroup>

## Errors

| Status | Code              | When                                                                                            | Recover                                                                        |
| ------ | ----------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 404    | `unknown_version` | The path begins with a version prefix the API does not recognize, for example `/v3/data/calls`. | Pin to a documented version: `v1` for data, `v2` for admin.                    |
| 410    | `version_sunset`  | You called an endpoint after its `Sunset` date.                                                 | Migrate to the replacement listed in the [API changelog](/docs/api-changelog). |

See [Errors](/docs/api-errors) for shared codes.