Blocks
Blocks API: 3 endpoints under /v1.
List memory blocks
GET /v1/blocks/{workspaceId}
Returns the memory blocks that enter every context for the given agent: blocks shared by all agents (agentScope *) plus blocks scoped to that agent, from the workspace-wide pool and, when applicationId is given, that application. Requires the read permission.
See also: Blocks and user profiles.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
workspaceId (required) | path | string (uuid) | Workspace to act in. A workspace the credential cannot access returns 404. |
agentId | query | string | Agent to act as. Omit to use the credential's default agent; an agent the credential is not bound to returns 403 policy_denied. |
applicationId | query | string (uuid) | Application scope. Omit to use the workspace's shared pool; a credential bound to an application cannot request another one. |
Responses
| Status | Description |
|---|---|
200 | A list of memory blocks with their label, value, agent scope, character limit and read-only flag. |
Example
curl -X GET "$API/v1/blocks/$WS" \
-H "Authorization: Bearer $KEY"Write a memory block
PUT /v1/blocks/{workspaceId}
Writes the whole value of the block with the given label, creating it if it does not exist. The content is screened, and blocks marked read-only or values over the block's character limit are rejected. Requires the write permission.
See also: Blocks and user profiles.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
workspaceId (required) | path | string (uuid) | Workspace to act in. A workspace the credential cannot access returns 404. |
Request body (UpdateBlockRequest)
| Field | Type | Description |
|---|---|---|
agentScope | string | Agent the block belongs to; * (default) means all agents. |
applicationId | string (uuid) | Application scope of the block; omit for a workspace-wide block. |
label | string | Block label, such as tech_stack or coding_conventions. |
value | string | The block's full new value. Limited by the block's character limit (2000 by default). |
Responses
| Status | Description |
|---|---|
200 | Confirmation with status updated. |
Response fields
| Field | Description |
|---|---|
status | Always updated on success. |
Example
curl -X PUT "$API/v1/blocks/$WS" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-d '{}'Edit a memory block line by line
POST /v1/blocks/{workspaceId}/curate
Adds, replaces or removes a single line of a block instead of rewriting it. add appends value as a new line; replace swaps the line containing match for value; remove deletes the line containing match. Requires the curate permission.
See also: Blocks and user profiles.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
workspaceId (required) | path | string (uuid) | Workspace to act in. A workspace the credential cannot access returns 404. |
Request body (CurateBlockRequest)
| Field | Type | Description |
|---|---|---|
action | string | add appends a line, replace swaps the line containing match, remove deletes the line containing match. |
agentScope | string | Agent the block belongs to; * (default) means all agents. |
applicationId | string (uuid) | Application scope of the block. |
label | string | Label of the block to edit. |
match | string | Text identifying the line to replace or remove (case-insensitive substring). Required for replace and remove. |
value | string | New line text. Required for add and replace. |
Responses
| Status | Description |
|---|---|
200 | Confirmation with status curated. |
Response fields
| Field | Description |
|---|---|
status | Always curated on success. |
Example
curl -X POST "$API/v1/blocks/$WS/curate" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-d '{}'