---
title: "Cork API versioning and deprecation policy"
description: "How the Cork REST API is versioned, what may change inside v1, and how a deprecation is announced."
canonical: "https://corkcli.com/docs/api/versioning"
last_updated: "2026-10-17"
---

# API versioning and deprecation policy

Agents integrate once and then run unattended. This is what the [Cork REST API](https://corkcli.com/docs/api.md) promises about change, and how you will hear about one.

## The version is in the path

- The current major version is 1: `https://api.corkcli.com/api/v1/...`.
- Every response carries `API-Version: 1`.
- A new major version gets a new path (/api/v2/...). v1 keeps answering beside it.

## What may change inside v1

Only additive changes, at any time and without notice:

- new endpoints, new optional parameters and request fields;
- new fields in responses (clients must ignore fields they do not know);
- new values of open-ended strings such as an error's code or a job's operation.

Removing or renaming a field, changing a type or a status code, or making an optional parameter required is a breaking change, and breaking changes only ship in a new major version.

## How a deprecation is announced

- A deprecated path answers with a `Deprecation` header (RFC 9745) and a `Link` header naming its successor (`rel="successor-version"`) and this policy (`rel="deprecation"`).
- At least six months before anything is removed, its responses also carry a `Sunset` header (RFC 8594) with the date, and the change is listed in the [changelog](https://corkcli.com/changelog).
- Until that date it keeps working exactly as before.

## The unversioned paths

The API was first served without a version (`/api/workspaces`, `/api/activity/...`). Those paths are deprecated aliases of the same v1 handlers. They keep working, no removal date is set, and their responses say so:

```http
GET /api/workspaces

API-Version: 1
Deprecation: @1792281600
Link: <https://api.corkcli.com/api/v1/workspaces>; rel="successor-version", <https://corkcli.com/docs/api/versioning>; rel="deprecation"
```

The hooks' own routes (`/report`, `/gate`, `/brief`...) are a separate contract with the hook binaries, versioned by the hooks' own version number, and are not deprecated. They are also reachable under `/api/v1/`.