client.blocks

client.blocks — the blocks operations.

On AsyncKindgi every method is the same, awaited.

client.blocks.list()

list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    kind: Literal['prompt', 'settings'] | None = None,
    name: str | None = None,
    scope_kind: Literal['tenant', 'org', 'project'] | None = None,
    scope_id: str | UUID | None = None,
    include_retired: bool | None = None,
    timeout: float | None = None,
) -> BlockCollectionPage

Signature

List data blocks (latest version of each). GET /v1/blocks

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.

client.blocks.publish()

publish(
    body: PublishBlockBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> PublishBlockResult

Signature

Publish a data block version. POST /v1/blocks

Needs write on the project. A prompt's template must parse as Liquid; a settings block's values must satisfy its schema and the latest version's. A settings block an agent version uses as its model settings takes only model settings, which never name the model that agent version names too. The version records the caller as publishedBy, and source: { kind: "api" }. A taken version is 409 block-already-registered (versions never change); a block keeps its kind, and its versions stay in its first version's project, or another project of that project's environment order (409 block-project-mismatch). A later environment of an order takes no publishes (409 environment-takes-promotions). Idempotency-Key applies.

client.blocks.get()

get(
    block_id: str | UUID,
    /,
    *,
    project_id: str | UUID | None = None,
    timeout: float | None = None,
) -> Block

Signature

Fetch a data block (latest version). GET /v1/blocks/{blockId}

An item more than one project serves (an environment order carries it to later environments) answers its newest active version that can run in a project the caller reads, and 404 when there is none. projectId narrows that to one project. An item with one project answers its latest active version.

client.blocks.runs_in()

runs_in(block_id: str | UUID, /, *, timeout: float | None = None) -> BlockRunsInList

Signature

List where a data block's versions run. GET /v1/blocks/{blockId}/runs-in

Where the block's versions run now: one row for each project, and each segment pin inside one, whose running version of an agent pins a version of the block (as a prompt, a settings block or its model settings). Each agent's projects are the ones agents.projects lists, and what runs in each is what it says: a pin that covers the project, else its Latest. Only the projects the caller can read are named, and an agent version the caller can't see is left out. A block no running version pins answers an empty list. Without the agents' pins and Latest in this runtime, 501 runs-in-unsupported.