Skip to content
Kindgi

List the projects an agent runs in, and what runs in each

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

The project the agent was first published in, then each other project a version of it can run in: one that a deployment which is not retired shipped a version into, an unregistered version included. A change to the agent reaches each of them. Only the projects the caller can read are named, its first project included. A retired agent still answers. Without environment orders, an agent has one project. Under kindgi dev, whose pack names no project, the list is empty. Each project says what a run there that names no version gets (runs) and why (follows): a pin that covers the project, else its Latest. Latest moves only when a deployment into the project ships a version, or when a person publishes a full version or adds one as the latest version; a pin never moves it. segments lists the pins on segments inside the project. highest is the agent’s highest version, which numbers the next one. A version the caller can’t see is left out.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agentId
required
string

AgentId — dotted namespace (acme.drafting).

Responses

Section titled “Responses”

200

Section titled “200”

The projects.

Media typeapplication/json
object
data
required

Its first project first, then the others, each once.

Array<object>
object
projectId
required
string format: uuid
follows

Why runs runs there: pin, a pin that covers the project (its own, its org’s or the tenant’s); latest, no pin covers it, so it runs its Latest. Absent when neither has a version the caller can see, or when the server doesn’t pin versions.

string
Allowed values: pin latest
runs

The version a run in the project that names none gets (and isn’t a follow-up turn of a conversation).

object
version
required
string
since

When it began to run there: when the pin was set; or, for Latest, the deployment into the project that shipped it, or when a person published it or added it as the latest version. Absent when nothing records a time, as for a pack’s version under kindgi dev.

string format: date-time
by

Who: the requester of the promotion that set the pin, or the person who published it or added it as the latest version. Absent when a deployment made it Latest.

object
kind
required
string
Allowed values: user service
id
required
string
deploymentId

With follows: latest: the deployment into the project that made it Latest, when one did.

string
pinnedScope
One of: discriminator: kind

The whole tenant.

object
kind
required
string
Allowed values: tenant
pinChangeId

With follows: pin: the pin change that set the pin, in the agent’s pin history.

string
segments

The pins on segments inside the project, which those segment paths run instead.

Array<object>
object
path
required
Array<object>
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
version
required
string
highest

The agent’s highest active version, which numbers the next one. It isn’t what a project runs: that’s each project’s runs. Absent when the caller can’t see it, or when the server doesn’t pin versions.

object
version
required
string
Example
{
  "data": [
    {
      "follows": "pin",
      "runs": {
        "by": {
          "kind": "user"
        },
        "pinnedScope": {
          "kind": "tenant"
        }
      }
    }
  ]
}

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 under this tenant.

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