v36

latestOpenAPI 3.1.0raw.githubusercontent.com2025-10-091882241.2 MB

blocks

List Blocks

get/v1/blocks/

Query parameters

labelstring nullable

Labels to include (e.g. human, persona)

templates_onlyboolean

Whether to include only templates

namestring nullable

Name of the block

identity_idstring nullable

Search agents by identifier id

identifier_keysstring[] nullable

Search agents by identifier keys

project_idstring nullable

Search blocks by project id

limitinteger nullable

Number of blocks to return

beforestring nullable

Block ID cursor for pagination. Returns blocks that come before this block ID in the specified sort order

afterstring nullable

Block ID cursor for pagination. Returns blocks that come after this block ID in the specified sort order

order'asc' | 'desc'

Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest first

order_by'created_at'

Field to sort by

label_searchstring nullable

Search blocks by label. If provided, returns blocks that match this label. This is a full-text search on labels.

description_searchstring nullable

Search blocks by description. If provided, returns blocks that match this description. This is a full-text search on block descriptions.

value_searchstring nullable

Search blocks by value. If provided, returns blocks that match this value.

connected_to_agents_count_gtinteger nullable

Filter blocks by the number of connected agents. If provided, returns blocks that have more than this number of connected agents.

connected_to_agents_count_ltinteger nullable

Filter blocks by the number of connected agents. If provided, returns blocks that have less than this number of connected agents.

connected_to_agents_count_eqinteger[] nullable

Filter blocks by the exact number of connected agents. If provided, returns blocks that have exactly this number of connected agents.

Response

Successful Response

valuestring required

Value of the block.

limitinteger

Character limit of the block.

project_idstring nullable

The associated project id.

namestring nullable

The id of the template.

is_templateboolean

Whether the block is a template (e.g. saved human/persona options).

base_template_idstring nullable

The base template id of the block.

deployment_idstring nullable

The id of the deployment.

entity_idstring nullable

The id of the entity within the template.

preserve_on_migrationboolean nullable

Preserve the block on template migration.

labelstring nullable

Label of the block (e.g. 'human', 'persona') in the context window.

read_onlyboolean

Whether the agent has read-only access to the block.

descriptionstring nullable

Description of the block.

metadataobject nullable

Metadata of the block.

hiddenboolean nullable

If set to True, the block will be hidden.

idstring

The human-friendly ID of the Block

created_by_idstring nullable

The id of the user that made this Block.

last_updated_by_idstring nullable

The id of the user that last updated this Block.

Example response

[
  {
    "id": "block-123e4567-e89b-12d3-a456-426614174000"
  }
]