Skip to content
Kindgi

The version a run would use

View as Markdown
GET
/v1/agents/{agentId}/pinned
curl --request GET \
  --url https://example.com/v1/agents/example/pinned \
  --header 'Authorization: Bearer <token>'

Resolves the version a run of this agent would use for a project and segment path: the most specific pinned version (segment path, project, org, workspace), else the project’s Latest: the version the newest deployment into the project shipped, or that a person published or added as the latest version there, whichever is newer. Without a project, Latest is taken over every version of the agent. A run that names its version, or a follow-up turn in a conversation, isn’t resolved this way.

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”
projectId
string format: uuid

The run’s project; omit → only the agent’s workspace-wide pin applies.

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”

The resolved version.

Media typeapplication/json
object
agentId
required
string
version
required

The version a run would use (semver).

string
via
required

A pin chose it, or nothing is pinned on the way up and it is the project’s Latest.

string
Allowed values: pinned latest
pinnedScope
One of: discriminator: kind

The whole workspace.

object
kind
required
string
Allowed values: tenant
Example
{
  "via": "pinned",
  "pinnedScope": {
    "kind": "tenant"
  }
}

400

Section titled “400”

A malformed project id or segment, or a segment without a project.

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”

No version of the agent runs in this scope: none is pinned there, and none is its Latest.

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