# Remove a scope's pinned version POST /v1/agents/{agentId}/pinned/unpin ```sh curl --request POST \ --url https://example.com/v1/agents/example/pinned/unpin \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "scope": { "kind": "tenant" }, "reason": "example" }' ``` Removes the scope’s own pin: its runs use the next scope up (and the latest when nothing is pinned). Recorded like a pin. Needs `pin` on the agent. The unpin answers as a pin does, with the unpin change under `pin`. It checks each project the pin covered that now runs another version and has active cases, on the project’s agent test set (`testRuns`), with a run of the version it runs now that it starts, correlation id `pin:` of the unpin, whose outcome changes the corrections’ statuses when it ends. An unpin reuses no run, so `fixed` and `reopened` are empty. ## Authorizations - **[bearerAuth](https://docs.kindgi.com/v0.5.0/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 workspace 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). A request whose key store can’t be read before it runs is answered `503 idempotency-store-unavailable` with `Retry-After`: nothing ran, so retry with the same key (from 0.3.0). ## Request Bodyrequired application/json object **scope** required One of: discriminator: kind - **object** The whole workspace. 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 **reason** string <= 2000 characters ## Responses ### 201 Unpinned, with the test runs that check what each project runs now (`testRuns`). application/json A pin, and the test runs that check it. object **pin** required One change of a scope’s pinned version, kept for good: what was pinned 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 whole workspace. 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: pin 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 **testRunId** The comparison behind the change. string **createdAt** required string format: date-time **status** A `pin` row’s state: it changes once, from `pending-approval` to its final state. Absent on unpin rows, and on pins made before gates (`pinned`). string Allowed values: pinned pending-approval refused superseded rejected expired **releaseGate** One of: - **object** object **id** required string **version** required string - **null** null **checks** Array\ One of a gate’s checks, as the pin records it. object **name** required Stable: `comparison.required`, `comparison.status`, `comparison.freshness`, `comparison.testSet`, `sameContents`, `baselineIsPinned`, `scopeCovered`, `evidence..minCases|minWeight|baselineMinCases|baselineMinWeight`, `metric..k|minCandidate|maxDrop`, `replay.maxDiverged|maxErrors|maxRefusedWrites|maxStopped`, `cases.minPassing|noNewFailures`, `groupWeights.expertsOnly`, and `approval.recheck`, which an approval adds to a pin it supersedes, to say what changed since the check. string **passed** required boolean **message** required A plain sentence: what was found against what the gate asks. string **value** number | string **threshold** number | string **caseIds** The cases it names: for `cases.noNewFailures`, the ones that passed before and fail now (empty when none does). Absent when it could not tell, and on other checks. Array\ **approvalId** The approval a `pending-approval` pin waits on (kept once decided). string **resolvedAt** When a `pending-approval` pin reached its final state. string format: date-time **stoppedFollowingLatest** A `pin`’s: `true` when it took a project that followed Latest off it, as its request asked (`stopFollowingLatest`) or as a promotion’s pin does. Absent otherwise. boolean **testRuns** required One per project whose running version the pin changes and that has active cases: a project pin has one, a workspace or org pin one per such project, a segment pin none. While the pin waits for approval, its runs are already started. Array\ A test run a pin checks a project with: the one the pin named, reused, or one it started, with correlation id `pin:`. object **projectId** required string format: uuid **testRunId** required string **fixed** required The corrections a reused run made `fixed` at pin time. Empty when the runs were started: their outcome changes the statuses when each ends. Array\ **reopened** required The corrections a reused run reopened at pin time, as `fixed`’s. Array\ ##### Example ```json { "pin": { "scope": { "kind": "tenant" }, "action": "pin", "requestedBy": { "kind": "user" }, "status": "pinned" } } ``` ### 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" } } ``` ### 409 `not-pinned`: the scope has no pin of its own. `release-gate-needs-pin`: the scope has a release gate of its own, and a gated scope keeps its own pin; unregister the gate first, or pin an earlier version instead. `release-gate-descendant-unpinned`: the change would also move a narrower scope a release gate applies to, which has no pinned version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first. Or `registry-read-only`: under `kindgi dev`, a pinned version was written into the pack’s files; to undo a pin, pin the version before. 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" } } ``` ### 503 The `Idempotency-Key` store couldn’t be read before the request ran (`idempotency-store-unavailable`), so nothing was changed; `Retry-After` (whole seconds) says when to try again with the same key. 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 highest version of an agent](https://docs.kindgi.com/v0.5.0/reference/api/operations/agentsget.md) - [`GET /v1/agents/{agentId}/projects`: List the projects an agent runs in, and what runs in each](https://docs.kindgi.com/v0.5.0/reference/api/operations/agentsprojects.md) - [`GET /v1/agents/{agentId}/versions`: List versions of an agent](https://docs.kindgi.com/v0.5.0/reference/api/operations/agentslistversions.md) - [`GET /v1/agents/{agentId}/versions/{version}`: Fetch a specific agent version](https://docs.kindgi.com/v0.5.0/reference/api/operations/agentsgetversion.md) - [Kindgi 0.4.0](https://docs.kindgi.com/v0.5.0/releases/0.4.0.md) - [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/v0.5.0/reference/errors.md#idempotency-store-unavailable) - [Error code `not-pinned`](https://docs.kindgi.com/v0.5.0/reference/errors.md#not-pinned) - [Error code `registry-read-only`](https://docs.kindgi.com/v0.5.0/reference/errors.md#registry-read-only) - [Error code `release-gate-descendant-unpinned`](https://docs.kindgi.com/v0.5.0/reference/errors.md#release-gate-descendant-unpinned) - [Error code `release-gate-needs-pin`](https://docs.kindgi.com/v0.5.0/reference/errors.md#release-gate-needs-pin) - [Error code `request-too-large`](https://docs.kindgi.com/v0.5.0/reference/errors.md#request-too-large) - [Every error code](https://docs.kindgi.com/v0.5.0/reference/errors.md)