Skip to content
Kindgi

The version in use for a project

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

Resolves the version in use for a project (or an org, or the whole workspace): the most specific pin covering it (the project, its org, then the workspace) whose version is still active, else the newest active version, the one a flow version made now would lock its tool step to. via says which; pinnedScope names the pin that matched.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
toolId
required
string

ToolId — dotted namespace (acme.lookup-order).

Query Parameters

Section titled “Query Parameters”
projectId
string format: uuid

The project to resolve for; omit → only the org’s pin (with orgId) and the workspace-wide pin apply.

orgId
string format: uuid

The project’s org, when it has one. A runtime may look it up from projectId itself.

Responses

Section titled “Responses”

200

Section titled “200”

The version in use.

Media typeapplication/json
object
itemId
required

The flow or tool.

string
version
required

The version in use there (semver): what a run that names no flow version takes, or what the next agent or flow version made there locks for a tool.

string
via
required

A pin chose it, or nothing is pinned on the way up and it is the newest version (for a flow, the newest the project reaches; for a tool, the newest active one).

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 or org 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"
  }
}

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”

tool-not-found: no tool with that id, or no version of it for that 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"
  }
}

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