API changelog
Dated changes to the public REST API, newest first, with the API version, the kind of change, the affected operations, and the sunset dates of deprecations.
This changelog lists the changes to the public REST API, newest first. Each entry gives its date, the API version and the contract version, the kind of change, and the operations that it affects. The contract version is the info.version of the OpenAPI document at https://<api-host>/openapi.json.
A breaking change is announced here at least 6 months before it takes effect. For the rules, see API versioning and deprecation.
| Kind | Meaning |
|---|---|
| Added | A new operation, field, header, or feature. Backward compatible. |
| Changed | Changed behavior. Before general availability, such a change could be breaking. |
| Deprecated | The operation keeps working until its sunset date and can be removed or changed after it. |
| Removed | The operation or field was removed after its sunset date. |
| Security | A change that closes a security gap. |
2026-10-18
API version v1, contract version 1.4.0.
Deprecated
These operations are deprecated. Sunset: 2027-04-18. Their responses carry the Deprecation, Sunset, and Link headers.
Added
- The versioning and deprecation policy of the API.
- The
Deprecation,Sunset, andLinkheaders on every response of a deprecated operation, and thex-deprecation-dateandx-sunsetfields on deprecated operations in the OpenAPI document.
Changes before general availability
These changes were made before general availability, so they weren't subject to the notice period. They apply to API version v1.
| Date | Kind | Change |
|---|---|---|
| 2026-10-19 | Changed | With an API token or a service account key, the Idempotency-Key header is required only on POST requests that create a resource and answer 202 Accepted. DELETE, PATCH, and PUT requests and actions on existing resources are accepted without the key again. When you send a key with them, a retry with the same key still returns the first response, for the operations that use the key. The API reference no longer lists the Idempotency-Key header on the operations that ignore it. |
| 2026-10-19 | Security | Breaking change. Creating a subscription with an API token, POST /tenants/{tenantId}/subscriptions, needs billing:write in addition to iam:write. Without it, the request returns 403 Forbidden with the reason TOKEN_SCOPE_MISSING. Service account keys stay refused. |
| 2026-10-18 | Security | Service account keys have scopes and pass the same scope check as API tokens. A key created without scopes gets every scope except iam:write. A key can't have iam:write: such a request returns 422 Unprocessable Entity. Operations that need iam:write, the writes under /tenants/ included, refuse service account keys with 403 Forbidden and the code INTERACTIVE_SESSION_REQUIRED. |
| 2026-10-18 | Added | The API host serves an interactive API explorer at https://<api-host>/docs and the OpenAPI document at https://<api-host>/openapi.json. |
| 2026-10-18 | Changed | List operations that returned every item now take page and pageSize. pageSize is 1–200, and its default is 200. A larger value returns 422 Unprocessable Entity. |
| 2026-10-18 | Changed | The server of the OpenAPI document is /api/v1 on the API host. The published API reference is generated from the API contract by a rule that leaves out the operations that aren't public. |
| 2026-10-18 | Changed | A write with an API token or a service account key must carry an Idempotency-Key header if the operation takes one. Without it, the request returns 400 Bad Request with the code IDEMPOTENCY_KEY_REQUIRED. Keys are kept per tenant, so the same key in two tenants identifies two different requests. |
| 2026-10-18 | Changed | Requests with an API token or a service account key are limited per credential and per tenant. Their responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A request over the limit returns 429 Too Many Requests with the code RATE_LIMITED and a Retry-After header. |
| 2026-10-18 | Changed | The token scope catalog has 17 scopes, so that every area of the API can be reached with an explicit scope. The OpenAPI document lists the scopes that each operation needs in x-required-scopes. The Activity Log accepts iam:read or audit:read. A token can't create a token or a key with a scope that it doesn't have itself: 403 Forbidden with details.reason TOKEN_SCOPE_MISSING. A token also can't create a token that expires later than itself, or one whose IP allowlist isn't within its own: 403 Forbidden with details.reason TOKEN_FENCE_EXCEEDED. |
| 2026-10-17 | Security | Disabling or deleting a service account revokes its keys and the API tokens that it created. Enabling the account again doesn't restore them. A custom expiry date of an API token can be at most 365 days ahead; a later date returns 422 Unprocessable Entity with details.reason token_lifetime_exceeds_maximum. |
| 2026-10-17 | Added | Activity Log events carry actorType, which tells how the caller authenticated: user, api_token, service_account_key, or system. They also carry credentialId, the public ID of the API token or service account key that made the call. |