List the pinned versions that cover a project

GET

/v1/projects/{projectId}/pinned-versions

curl --request GET \
  --url 'https://example.com/v1/projects/example/pinned-versions?limit=25' \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Every agent’s pinned versions that cover the project: the tenant’s, the project’s org’s, the project’s own and its segments’, ordered by agent id, then scope. A run in the project takes the most specific one that covers it, else its agent’s latest version. For readers of the project (read), and only the pins of agents and versions the caller can read, as GET /v1/agents/{agentId}/pinned-versions shows them. A page can hold fewer pins than limit, or none, with hasMore true: page on nextCursor, not the count. 501 pinned-versions-not-supported from a runtime that can’t list them.

Authorizations

• bearerAuth

Parameters

Path Parameters

projectId

required

string

ProjectId — opaque branded string.

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.

Responses

200

Page of pinned versions.

Media typeapplication/json

object

data

required

Array<object>

object

agentId

required

string

scope

required

One of: discriminator: kind

object

The whole tenant.

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

version

required

string

changeId

required

The pin change that set it.

string format: uuid

setAt

required

string format: date-time

hasMore

required

boolean

nextCursor

string

Example

{
  "data": [
    {
      "scope": {
        "kind": "tenant"
      }
    }
  ]
}

400

A malformed project id 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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No project 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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

501

The runtime can’t list a project’s pinned versions (pinned-versions-not-supported).

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

Example^generated

{
  "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.

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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also

• GET /v1/projects/{projectId}: Fetch a project by id
• PATCH /v1/projects/{projectId}: Partially update a project
• DELETE /v1/projects/{projectId}: Delete a project (idempotent)
• GET /v1/projects/{projectId}/queue-rules: List a project's queue rules
• Error code database-busy
• Error code pinned-versions-not-supported
• Every error code