# Check a pin against its gate

POST

/v1/agents/{agentId}/pinned/check

```sh
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

- **[bearerAuth](https://docs.kindgi.com/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**agentId**

required

string

AgentId — dotted namespace (`acme.drafting`).

## 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\<object>

  \>= 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

**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

### 200

The gate’s answer.

application/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**

  object

  **id**

  required

  string

  **version**

  required

  string

- **null**

  null

**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

```json
{
  "outcome": "would-pin",
  "approval": {
    "role": "standard"
  },
  "notInGit": true
}
```

### 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`).

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

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

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

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

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

## See also

- [`GET /v1/agents/{agentId}`: Fetch the highest version of an agent](https://docs.kindgi.com/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/reference/api/operations/agentsprojects.md)
- [`GET /v1/agents/{agentId}/versions`: List versions of an agent](https://docs.kindgi.com/reference/api/operations/agentslistversions.md)
- [`GET /v1/agents/{agentId}/versions/{version}`: Fetch a specific agent version](https://docs.kindgi.com/reference/api/operations/agentsgetversion.md)
- [Suggest a change, and test it](https://docs.kindgi.com/guides/improve/suggest-a-change.md)
- [Error code `nothing-runs-in-scope`](https://docs.kindgi.com/reference/errors.md#nothing-runs-in-scope)
- [Error code `project-suspended`](https://docs.kindgi.com/reference/errors.md#project-suspended)
- [Error code `reference-out-of-scope`](https://docs.kindgi.com/reference/errors.md#reference-out-of-scope)
- [Error code `request-too-large`](https://docs.kindgi.com/reference/errors.md#request-too-large)
- [Every error code](https://docs.kindgi.com/reference/errors.md)