Skip to content
Kindgi

List an agent's pin history

View as Markdown
GET
/v1/agents/{agentId}/pin-history
curl --request GET \
  --url 'https://example.com/v1/agents/example/pin-history?limit=25&scopeKind=tenant' \
  --header 'Authorization: Bearer <token>'

The history of pinned-version changes (pins and unpins), newest first. scopeKind (tenant, org, project, segment) with scopeId and segment narrows it to one scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agentId
required
string

AgentId — dotted namespace (acme.drafting).

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

scopeKind
string
Allowed values: tenant org project segment

Only one scope: tenant, org or project (with scopeId), or segment (with scopeId and segment).

scopeId
string
>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (the workspace is implicit from the session). Malformed combinations return 400 scope-invalid.

segment
Array<string>

One step of the segment path, key:value; repeat it in order, coarse to fine.

Responses

Section titled “Responses”

200

Section titled “200”

Page of pin changes.

Media typeapplication/json
object
data
required
Array<object>

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
hasMore
required
boolean
nextCursor
string
Example
{
  "data": [
    {
      "scope": {
        "kind": "tenant"
      },
      "action": "pin",
      "requestedBy": {
        "kind": "user"
      },
      "status": "pinned"
    }
  ]
}

400

Section titled “400”

Malformed scope or cursor.

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

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

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