Skip to content
Kindgi

List data blocks (latest version of each)

View as Markdown
GET
/v1/blocks
curl --request GET \
  --url 'https://example.com/v1/blocks?limit=25&kind=prompt&scopeKind=tenant&includeRetired=false' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated. Only the blocks of projects the caller can read. ?kind= narrows to prompts or settings, ?name= is a prefix match on the id, and ?scopeKind= + ?scopeId= narrow to a project or an org, as the other lists do. A retired block (every version unregistered) is listed only with ?includeRetired=true, as its highest version with unregisteredAt, so it can be found and a version reinstated.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “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.

kind

prompt: a Liquid template an agent renders as its instructions. settings: a JSON object tools and templates read.

string
Allowed values: prompt settings

Only blocks of this kind: prompt or settings.

name
string

Prefix match on the block id.

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string
Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId
string
>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (the workspace is implicit from the session). Malformed combinations return 400 scope-invalid.

includeRetired
boolean

When true, retired items (every version unregistered) are listed too, each as its highest version with that version’s unregisteredAt. Default: false (items with an active version only).

Responses

Section titled “Responses”

200

Section titled “200”

Page of blocks.

Media typeapplication/json
object
data
required
Array<object>

A data block version: a prompt or settings, versioned like a tool (immutable versions, soft unregister). An agent version pins the block versions it uses when it is published. Belongs to one project and is authorized through it.

object
id
required

Dotted lowercase id (e.g. acme.intake-prompt).

string
version
required
string
/^\d+\.\d+\.\d+$/
kind
required

prompt: a Liquid template an agent renders as its instructions. settings: a JSON object tools and templates read.

string
Allowed values: prompt settings
description
string
content
required
One of:
object
template
required

Liquid, rendered as an agent’s instructions are (same parameters and auto-injected variables).

string
>= 1 characters
parameters
Array<object>
object
name
required
string
description
string
type
required
string
Allowed values: string number boolean date
required
boolean
default

Default value used when the caller omits this parameter.

projectId
required
string format: uuid
publishedAt
required
string format: date-time
unregisteredAt

Present only on an unregistered version; agent versions that pin it still read it. A retired block (every version unregistered) carries it as GET /v1/blocks?includeRetired=true lists it.

string format: date-time
publishedBy

Who published the version: a user, or a service token. Absent on a version published before it was recorded.

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

Where a block version came from: api (POST /v1/blocks), deploy (a deploy’s pack; id is the deployment’s) or suggested-change (id is the suggested change’s). Absent on a version published before it was recorded.

object
kind
required
string
Allowed values: api deploy suggested-change
id

Present for deploy and suggested-change.

string
nextCursor
string
hasMore
required
boolean
Example
{
  "data": [
    {
      "kind": "prompt",
      "content": {
        "parameters": [
          {
            "type": "string"
          }
        ]
      },
      "publishedBy": {
        "kind": "user"
      },
      "source": {
        "kind": "api"
      }
    }
  ]
}

400

Section titled “400”

Malformed query parameter: an unknown kind, or scope-invalid for a malformed scope.

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

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