# Pin a version for a scope POST /v1/agents/{agentId}/pinned/pin ```sh curl --request POST \ --url https://example.com/v1/agents/example/pinned/pin \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "version": "example", "scope": { "kind": "tenant" }, "reason": "example", "testRunId": "example", "stopFollowingLatest": true }' ``` Pins `version` for `scope`: runs in that scope that don’t name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every pin is recorded, with who asked and why. Needs `pin` on the agent. The pin checks the version in each project whose running version it changes and that has active cases, on the project’s agent test set (`testRuns`): with the run `testRunId` names when that run completed there on the test set as it stands, whose outcome changes the corrections’ statuses at once (`fixed`, `reopened`); otherwise with a run it starts, correlation id `pin:`, whose outcome changes them when it ends. A pin that waits for approval starts its runs at once, and its statuses change once it’s approved. A pin that would take a project that follows Latest now off it (a project or segment pin there, or a workspace or org pin over it) is refused with `409 pin-stops-latest` before any gate, whether or not its version changes, unless the body has `stopFollowingLatest: true`. The pin then records `stoppedFollowingLatest`, and the project runs the pinned version from then on, not each new Latest. With a release gate for the scope (`GET …/release-gate`), the pin is checked first against the comparison named by `testRunId`: `201` pinned; `202` the gate passed and wants a reviewer’s approval (a HITL approval, subject `agent-pin`; the pinned version moves once it’s approved, if nothing changed meanwhile); `422 gate-failed` with `details.changeId`, `details.releaseGate` and every check in `details.checks`. A refused pin is recorded too. A pin in place skips the gate: when the scope has no pinned version of its own and already serves exactly `version` (from a scope above, or as the latest), pinning it there changes nothing any run gets, so it is pinned (`201`) with one passing `pinInPlace` check, no comparison and no approval, its reason starting `pin-in-place`. It is re-checked as it is written; if the scope moved meanwhile, `409 pin-superseded`: check again. Under `kindgi dev`, nothing is pinned, since the pack’s files are what runs: pinning a version writes the data blocks it changes into the pack’s own files (each block’s new version and content, and a prompt’s template into its template file), and the dev server reloads them. Only for the whole workspace (the `tenant` scope), which the pack’s files serve. If one of those files changed since the version was made (the changed block’s file holds another version than the one its suggested change changed, or other content than its suggested change was drafted from, even at that version, or another block’s file a version not older), or the block left the pack, `409 pin-superseded`, and the message names the file; an approval’s decision settles it `superseded` the same way. Once the dev server reloads the files, the pinned version is what runs, and the pin’s test runs check it in the agent’s project (the default one) and change the corrections’ statuses as anywhere else. ## 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 **version** required The agent version to pin (registered, active). 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\