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

GET

/v1/agents/{agentId}/projects

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

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

## Parameters

### Path Parameters

**agentId**

required

string

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

## Responses

### 200

The projects.

application/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 workspace’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

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

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

```json
{
  "data": [
    {
      "follows": "pin",
      "runs": {
        "by": {
          "kind": "user"
        },
        "pinnedScope": {
          "kind": "tenant"
        }
      }
    }
  ]
}
```

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

No agent with that id under this workspace.

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

### 503

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

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}/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)
- [`PUT /v1/agents/{agentId}/owner`: Set an agent's owner](https://docs.kindgi.com/reference/api/operations/agentssetowner.md)
- [Projects, packs and values](https://docs.kindgi.com/concepts/projects-packs-values.md)
- [Agent and tool versions](https://docs.kindgi.com/guides/agents/agent-and-tool-versions.md)
- [Pinned versions reference](https://docs.kindgi.com/guides/improve/pinned-versions-reference.md)
- [Error code `database-busy`](https://docs.kindgi.com/reference/errors.md#database-busy)
- [Every error code](https://docs.kindgi.com/reference/errors.md)