Skip to content
Kindgi

The version a run would use

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

Resolves the version a run of this agent would use for a project and segment path: the most specific live version (segment path, project, org, tenant), else the latest registered. 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 tenant-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 live pin chose it, or nothing is live on the way up and it is the latest.

string
Allowed values: live latest
liveScope
One of: discriminator: kind

The agent’s default for the whole tenant.

object
kind
required
string
Allowed values: tenant
Example
{
  "via": "live",
  "liveScope": {
    "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 agent with that id.

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