> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Versioning

The Pivotal API is on **v1**. The version lives in the URL: `https://my.pivotal.app/api/v1/…`. There is no `X-API-Version` header to set, no date pinning, and no per-key version selector.

## What we promise inside v1

Pivotal will not break your integration mid-version. Specifically, within `v1`:

* We will **not** remove an endpoint.
* We will **not** remove a field from a response.
* We will **not** rename a field, an enum value, or an `operationId`.
* We will **not** narrow a field's type (e.g. flip `string | null` to `string`).
* We will **not** add a required request field to an existing endpoint.
* We will **not** change HTTP status codes for documented outcomes.
* We will **not** change error `type` or `code` for documented errors.

## What we WILL change inside v1

Additive changes ship without a version bump:

* **New endpoints** (e.g. a future `/customers/count`).
* **New optional response fields** — design your parsers to ignore unknown keys.
* **New optional request fields** — your existing requests keep working.
* **New enum values** — design your code to fall back gracefully on unknown values (don't `switch` exhaustively without a default).
* **New error `code` values inside an existing `type`** — branch on `type` for control flow, `code` only for fine-grained recovery.
* **Tighter validation that brings a previously-loose endpoint in line with the spec.** We try to avoid this. When we do it, we'll announce in the changelog and stage it (warn first, reject later).

If a change feels like it might surprise you, we'll ship it behind a feature flag on the workspace first, then announce.

## When v2 ships

A new major version (`v2`) ships only for changes that can't be made additively:

* Renaming a resource or top-level field shape.
* Restructuring the error envelope.
* Changing auth (we don't anticipate this).

When v2 ships:

* `v1` keeps working for **at least 12 months** alongside `v2` — no overnight cutover.
* The deprecation window will be announced on the changelog and via in-app banner.
* This documentation site will surface both versions in the version switcher in the navbar.

## Detecting deprecation

When an endpoint or field is marked for deprecation:

* The OpenAPI spec adds `"deprecated": true`.
* Responses include a `Deprecation` header (date the field/endpoint goes away).
* The Pivotal admin console shows a banner on the API Keys page surfacing recent calls to deprecated endpoints.

## Changelog

The Pivotal changelog lives in this docs site (linked from the navbar once we ship our first post-launch change). Until then, the closest thing to a changelog is the `/api/v1/health` response — it reports the deployed version of the API surface.

## Reporting compatibility breaks

If something you wrote against v1 stops working without an announcement, that's a bug on our side. Send the request/response pair to [help@pivotal.app](mailto:help@pivotal.app) — we treat unannounced breakage as a P0.