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 — we treat unannounced breakage as a P0.