# Roll a scope back to its previous live version POST /v1/agents/{agentId}/live/rollback ```sh curl --request POST \ --url https://example.com/v1/agents/example/live/rollback \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "scope": { "kind": "tenant" }, "toVersion": "example", "reason": "example" }' ``` Back to the scope’s previous live version, or `toVersion`. Recorded like a promotion. Needs `promote` on the agent. ## Authorizations - **[bearerAuth](https://docs.kindgi.com/v0.1.10/reference/api.md#bearerauth)** ## Parameters ### Path Parameters **agentId** required string AgentId — dotted namespace (`acme.drafting`). ### Header Parameters **Idempotency-Key** string \>= 1 characters Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per `docs/API-ROUTE-CONVENTIONS.md` §3.1). A retry sent while the first request still runs is answered `409 idempotency-key-in-flight` with `Retry-After`, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets `409 idempotency-key-replay-withheld`, with the first request’s status and when it succeeded (from 0.1.5). ## Request Bodyrequired application/json object **scope** required One of: discriminator: kind - **object** The agent’s default for the whole tenant. object **kind** required string Allowed values: tenant - **object** An org’s projects. object **kind** required string Allowed values: org **orgId** required string format: uuid - **object** One project. object **kind** required string Allowed values: project **projectId** required string format: uuid - **object** A segment path within a project: it covers every run whose path starts with it. object **kind** required string Allowed values: segment **projectId** required string format: uuid **path** required Array\ \>= 1 items <= 8 items object **key** required Lowercase, like an identifier: `company`, `contact-role`. string /^\[a-z]\[a-z0-9\_-]{0,63}$/ **value** required string \>= 1 characters <= 256 characters **toVersion** An earlier version to go back to; omit → the scope’s previous live version. string **reason** string <= 2000 characters ## Responses ### 200 Rolled back. application/json One change of a scope’s live version, kept for good: what was live before, what is after, who asked and why. object **id** required string format: uuid **agentId** required string **scope** required One of: discriminator: kind - **object** The agent’s default for the whole tenant. object **kind** required string Allowed values: tenant - **object** An org’s projects. object **kind** required string Allowed values: org **orgId** required string format: uuid - **object** One project. object **kind** required string Allowed values: project **projectId** required string format: uuid - **object** A segment path within a project: it covers every run whose path starts with it. object **kind** required string Allowed values: segment **projectId** required string format: uuid **path** required Array\ \>= 1 items <= 8 items object **key** required Lowercase, like an identifier: `company`, `contact-role`. string /^\[a-z]\[a-z0-9\_-]{0,63}$/ **value** required string \>= 1 characters <= 256 characters **action** required string Allowed values: promote rollback unpin **fromVersion** required The scope’s own pin before; null when it had none. string | null **toVersion** required The scope’s own pin after; null after an unpin. string | null **requestedBy** required object **kind** required string Allowed values: user service **id** required string **reason** string **evalRunId** The comparison the change was judged on. string **createdAt** required string format: date-time **status** A `promote` row’s state: it changes once, from `pending-approval` to its final state. Absent on rollback and unpin rows, and on promotions made before gates (`promoted`). string Allowed values: promoted pending-approval refused superseded rejected expired **policy** One of: - **object** object **id** required string **version** required string - **null** null **checks** Array\ One of a gate’s checks, as the promotion records it. object **name** required Stable: `comparison.required`, `comparison.status`, `comparison.freshness`, `comparison.suite`, `sameContents`, `baselineIsLive`, `scopeCovered`, `evidence..minCases|minWeight|baselineMinCases|baselineMinWeight`, `metric..k|minCandidate|maxDrop`, `replay.maxDiverged|maxErrors|maxRefusedWrites|maxStopped`, `classWeights.restrictedOnly`. string **passed** required boolean **message** required A plain sentence: what was found against what the policy asks. string **value** number | string **threshold** number | string **approvalId** The approval a `pending-approval` promotion waits on (kept once decided). string **resolvedAt** When a `pending-approval` promotion reached its final state. string format: date-time ##### Example ```json { "scope": { "kind": "tenant" }, "action": "promote", "requestedBy": { "kind": "user" }, "status": "promoted" } ``` ### 400 Malformed request body. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 401 Missing / malformed / expired / revoked bearer token. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 404 `toVersion` is not registered, or was unregistered. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 409 `not-pinned`: the scope has no pin of its own. `nothing-to-roll-back`: no earlier version to go back to. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first. `live-scope-spans-environments`: the agent has a project in an environment order, and a tenant- or org-wide rollback would act in every environment of the order at once; roll back a project (or a segment of it) instead. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 413 The request body is over the API’s limit (`request-too-large`; `details.maxBytes` says how much). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 500 Server error (unmapped domain code or framework crash). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ## See also - [`GET /v1/agents/{agentId}`: Fetch the latest version of an agent](https://docs.kindgi.com/v0.1.10/reference/api/operations/agentsget.md) - [`GET /v1/agents/{agentId}/versions`: List versions of an agent](https://docs.kindgi.com/v0.1.10/reference/api/operations/agentslistversions.md) - [`POST /v1/agents/{agentId}/versions`: Derive an agent version with data-block pins swapped](https://docs.kindgi.com/v0.1.10/reference/api/operations/agentsderiveversion.md) - [`GET /v1/agents/{agentId}/versions/{version}`: Fetch a specific agent version](https://docs.kindgi.com/v0.1.10/reference/api/operations/agentsgetversion.md) - [Error code `gate-policy-descendant-unpinned`](https://docs.kindgi.com/v0.1.10/reference/errors.md#gate-policy-descendant-unpinned) - [Error code `live-scope-spans-environments`](https://docs.kindgi.com/v0.1.10/reference/errors.md#live-scope-spans-environments) - [Error code `not-pinned`](https://docs.kindgi.com/v0.1.10/reference/errors.md#not-pinned) - [Error code `nothing-to-roll-back`](https://docs.kindgi.com/v0.1.10/reference/errors.md#nothing-to-roll-back) - [Error code `request-too-large`](https://docs.kindgi.com/v0.1.10/reference/errors.md#request-too-large) - [Every error code](https://docs.kindgi.com/v0.1.10/reference/errors.md)