Skip to content
Kindgi

Check a pin against its gate

View as Markdown
POST
/v1/agents/{agentId}/pinned/check
curl --request POST \
  --url https://example.com/v1/agents/example/pinned/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "version": "example", "scope": { "kind": "tenant" }, "reason": "example", "testRunId": "example", "stopFollowingLatest": true }'

What POST …/pinned/pin with the same body would do, with nothing recorded: would-pin, needs-approval (with the approval it needs) or gate-failed, with every check. For a pipeline: evaluate, check, pin. Under kindgi dev, where a pin writes the version into the pack’s files, it also warns about the files it would write over that git hasn’t committed (uncommittedFiles), or that the pack isn’t in git (notInGit). Needs read on the agent.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agentId
required
string

AgentId — dotted namespace (acme.drafting).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
version
required

The agent version to pin (registered, active).

string
scope
required
One of: discriminator: kind

The whole workspace.

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

The comparison behind this pin.

string
stopFollowingLatest

Pin even when it takes a project that follows Latest now off it: the project then runs the pinned version, not each new Latest. Without it, such a pin is refused (409 pin-stops-latest). POST …/pinned/check ignores it.

boolean

Responses

Section titled “Responses”

200

Section titled “200”

The gate’s answer.

Media typeapplication/json

What the gate would say about a pin. Nothing is recorded.

object
outcome
required
string
Allowed values: would-pin needs-approval gate-failed
releaseGate
required
One of:
object
id
required
string
version
required
string
checks
required
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>
approval

The approval a passing pin waits for.

object
role
required
string
Allowed values: standard senior admin
count
required
integer
>= 1
separateApprover
required

Whoever asked for the pin may not approve it.

boolean
uncommittedFiles

Under kindgi dev, where pinning a version writes it into the pack’s files: the files this pin would write over that git hasn’t committed (changed, staged, untracked or ignored, or in a nested repository such as a submodule), relative to the pack’s folder. Git can’t bring back what they hold once they’re written over, so commit them first. A warning: the pin still goes. Absent when there are none, when the pin writes nothing, when the gate fails, when git can’t say (no git, or no answer in time), and on every other runtime.

Array<string>
>= 1 items
notInGit

Under kindgi dev: the pack isn’t in a git repository, so git can’t bring back the files this pin would write over. A warning: the pin still goes. Absent otherwise.

boolean
Example
{
  "outcome": "would-pin",
  "approval": {
    "role": "standard"
  },
  "notInGit": true
}

400

Section titled “400”

Malformed body, or the test run isn’t a completed comparison: a cancelled or failed one is refused, even with the summary of the cases it got through. Or reference-out-of-scope: a project scope whose project doesn’t reach the agent (details.issues).

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"
  }
}

404

Section titled “404”

The version, the agent or the test run is not found.

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”

nothing-runs-in-scope or project-suspended, as POST …/promotions answers: no version of the agent runs in the scope yet.

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"
  }
}

See also