Skip to content
Kindgi

Remove a scope's pinned version

View as Markdown
POST
/v1/agents/{agentId}/pinned/unpin
curl --request POST \
  --url https://example.com/v1/agents/example/pinned/unpin \
  --header 'Authorization: Bearer <token>' \
  --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:<changeId> of the unpin, whose outcome changes the corrections’ statuses when it ends. An unpin reuses no run, so fixed and reopened are empty.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agentId
required
string

AgentId — dotted namespace (acme.drafting).

Header Parameters

Section titled “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

Section titled “Request Bodyrequired”
Media typeapplication/json
object
scope
required
One of: discriminator: kind

The whole workspace.

object
kind
required
string
Allowed values: tenant
reason
string
<= 2000 characters

Responses

Section titled “Responses”

201

Section titled “201”

Unpinned, with the test runs that check what each project runs now (testRuns).

Media typeapplication/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

The whole workspace.

object
kind
required
string
Allowed values: tenant
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
id
required
string
version
required
string
checks
Array<object>

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.<metric>.minCases|minWeight|baselineMinCases|baselineMinWeight, metric.<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<string>
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<object>

A test run a pin checks a project with: the one the pin named, reused, or one it started, with correlation id pin:<changeId>.

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<string>
reopened
required

The corrections a reused run reopened at pin time, as fixed’s.

Array<string>
Example
{
  "pin": {
    "scope": {
      "kind": "tenant"
    },
    "action": "pin",
    "requestedBy": {
      "kind": "user"
    },
    "status": "pinned"
  }
}

400

Section titled “400”

Malformed request body.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “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.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

Section titled “413”

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “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.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also