Letta · Capability
Letta API — Blocks
Memory blocks — manage labeled in-context memory blocks shared across agents. 9 operations. Lead operation: List Blocks. Self-contained Naftiko capability covering one Letta business surface.
Letta API — Blocks is a Naftiko capability published by Letta, one of 36 capabilities the APIs.io network indexes for this provider. It bundles 9 operations across the GET, PATCH, POST, and DELETE methods rooted at /v1/blocks.
The capability includes 4 read-only operations and 5 state-changing operations. Lead operation: List Blocks. Can be deployed as a REST endpoint, MCP tool, or Agent Skill via Naftiko.
Tagged areas include Letta, Stateful Agents, and Blocks.
What You Can Do
GET
List_blocks
— List Blocks
/v1/blocks/
POST
Create_block
— Create Block
/v1/blocks/
GET
Count_blocks
— Count Blocks
/v1/blocks/count
PATCH
Modify_block
— Modify Block
/v1/blocks/{block-id}
DELETE
Delete_block
— Delete Block
/v1/blocks/{block-id}
GET
Retrieve_block
— Retrieve Block
/v1/blocks/{block-id}
GET
List_agents_for_block
— List Agents for Block
/v1/blocks/{block-id}/agents
PATCH
Attach_identity_to_block
— Attach Identity to Block
/v1/blocks/{block-id}/identities/attach/{identity-id}
PATCH
Detach_identity_from_block
— Detach Identity from Block
/v1/blocks/{block-id}/identities/detach/{identity-id}
MCP Tools
list-blocks
List Blocks
read-only
idempotent
create-block
Create Block
count-blocks
Count Blocks
read-only
idempotent
modify-block
Modify Block
idempotent
delete-block
Delete Block
idempotent
retrieve-block
Retrieve Block
read-only
idempotent
list-agents-block
List Agents for Block
read-only
idempotent
attach-identity-block
Attach Identity to Block
idempotent
detach-identity-block
Detach Identity from Block
idempotent
Capability Spec
naftiko: "1.0.0-alpha2"
info:
label: "Letta API — Blocks"
description: >-
Memory blocks — manage labeled in-context memory blocks shared across agents. 9 operations. Lead operation: List Blocks. Self-contained Naftiko capability covering one Letta business surface.
tags:
- Letta
- Stateful Agents
- Blocks
created: "2026-05-08"
modified: "2026-05-22"
binds:
- namespace: env
keys:
LETTA_API_KEY: LETTA_API_KEY
capability:
consumes:
- type: http
namespace: "letta-blocks"
baseUri: "https://api.letta.com"
description: "Letta API — Blocks business capability. Self-contained, no shared references."
authentication:
type: bearer
token: "{{env.LETTA_API_KEY}}"
resources:
- name: "blocks"
path: "/v1/blocks/"
operations:
- name: "list_blocks"
method: GET
description: "List Blocks"
inputParameters:
- name: "label"
in: query
type: string
required: false
description: "Label to include (alphanumeric, hyphens, underscores, forward slashes)"
- name: "templates_only"
in: query
type: boolean
required: false
description: "Whether to include only templates"
- name: "name"
in: query
type: string
required: false
description: "Name filter (alphanumeric, spaces, hyphens, underscores)"
- name: "identity_id"
in: query
type: string
required: false
description: "The ID of the identity in the format 'identity-<uuid4>'"
- name: "identifier_keys"
in: query
type: string
required: false
description: "Search agents by identifier keys"
- name: "project_id"
in: query
type: string
required: false
description: "Search blocks by project id"
- name: "tags"
in: query
type: string
required: false
description: "List of tags to filter blocks by"
- name: "match_all_tags"
in: query
type: boolean
required: false
description: "If True, only returns blocks that match ALL given tags. Otherwise, return blocks that have ANY of the passed-in tags."
- name: "limit"
in: query
type: string
required: false
description: "Number of blocks to return"
- name: "before"
in: query
type: string
required: false
description: "Block ID cursor for pagination. Returns blocks that come before this block ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Block ID cursor for pagination. Returns blocks that come after this block ID in the specified sort order"
- name: "order"
in: query
type: string
required: false
description: "Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest first"
- name: "order_by"
in: query
type: string
required: false
description: "Field to sort by"
- name: "label_search"
in: query
type: string
required: false
description: "Search blocks by label. If provided, returns blocks whose label matches the search query. This is a full-text search on block labels."
- name: "description_search"
in: query
type: string
required: false
description: "Search blocks by description. If provided, returns blocks whose description matches the search query. This is a full-text search on block descriptions."
- name: "value_search"
in: query
type: string
required: false
description: "Search blocks by value. If provided, returns blocks whose value matches the search query. This is a full-text search on block values."
- name: "connected_to_agents_count_gt"
in: query
type: string
required: false
description: "Filter blocks by the number of connected agents. If provided, returns blocks that have more than this number of connected agents."
- name: "connected_to_agents_count_lt"
in: query
type: string
required: false
description: "Filter blocks by the number of connected agents. If provided, returns blocks that have less than this number of connected agents."
- name: "connected_to_agents_count_eq"
in: query
type: string
required: false
description: "Filter blocks by the exact number of connected agents. If provided, returns blocks that have exactly this number of connected agents."
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "create_block"
method: POST
description: "Create Block"
inputParameters:
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "blocks-count"
path: "/v1/blocks/count"
operations:
- name: "count_blocks"
method: GET
description: "Count Blocks"
inputParameters:
- name: "label"
in: query
type: string
required: false
description: "Label to include (alphanumeric, hyphens, underscores, forward slashes)"
- name: "templates_only"
in: query
type: boolean
required: false
description: "Whether to include only templates"
- name: "name"
in: query
type: string
required: false
description: "Name filter (alphanumeric, spaces, hyphens, underscores)"
- name: "tags"
in: query
type: string
required: false
description: "List of tags to filter blocks by"
- name: "match_all_tags"
in: query
type: boolean
required: false
description: "If True, only counts blocks that match ALL given tags. Otherwise, counts blocks that have ANY of the passed-in tags."
- name: "project_id"
in: query
type: string
required: false
description: "Search blocks by project id"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "blocks-by-id"
path: "/v1/blocks/{block_id}"
operations:
- name: "modify_block"
method: PATCH
description: "Modify Block"
inputParameters:
- name: "block_id"
in: path
type: string
required: true
description: "The ID of the block in the format 'block-<uuid4>'"
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "delete_block"
method: DELETE
description: "Delete Block"
inputParameters:
- name: "block_id"
in: path
type: string
required: true
description: "The ID of the block in the format 'block-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "retrieve_block"
method: GET
description: "Retrieve Block"
inputParameters:
- name: "block_id"
in: path
type: string
required: true
description: "The ID of the block in the format 'block-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "blocks-by-id-agents"
path: "/v1/blocks/{block_id}/agents"
operations:
- name: "list_agents_for_block"
method: GET
description: "List Agents for Block"
inputParameters:
- name: "block_id"
in: path
type: string
required: true
description: "The ID of the block in the format 'block-<uuid4>'"
- name: "before"
in: query
type: string
required: false
description: "Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of agents to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first"
- name: "order_by"
in: query
type: string
required: false
description: "Field to sort by"
- name: "include_relationships"
in: query
type: string
required: false
description: "Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in the response. If not provided, all relationships are loaded by default. Using this can optimize performance by reduci"
- name: "include"
in: query
type: array
required: false
description: "Specify which relational fields to include in the response. No relationships are included by default."
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "blocks-by-id-identities-attach-by-id"
path: "/v1/blocks/{block_id}/identities/attach/{identity_id}"
operations:
- name: "attach_identity_to_block"
method: PATCH
description: "Attach Identity to Block"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "identity_id parameter"
- name: "block_id"
in: path
type: string
required: true
description: "The ID of the block in the format 'block-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "blocks-by-id-identities-detach-by-id"
path: "/v1/blocks/{block_id}/identities/detach/{identity_id}"
operations:
- name: "detach_identity_from_block"
method: PATCH
description: "Detach Identity from Block"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "identity_id parameter"
- name: "block_id"
in: path
type: string
required: true
description: "The ID of the block in the format 'block-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
exposes:
- type: rest
namespace: "letta-blocks-rest"
port: 8080
description: "REST adapter for Letta API — Blocks. One Spectral-compliant resource per consumed operation."
resources:
- path: "/v1/blocks/"
name: "blocks"
description: "REST surface for blocks."
operations:
- method: GET
name: "list_blocks"
description: "List Blocks"
call: "letta-blocks.list_blocks"
with:
"label": "rest.label"
"templates_only": "rest.templates_only"
"name": "rest.name"
"identity_id": "rest.identity_id"
"identifier_keys": "rest.identifier_keys"
"project_id": "rest.project_id"
"tags": "rest.tags"
"match_all_tags": "rest.match_all_tags"
"limit": "rest.limit"
"before": "rest.before"
"after": "rest.after"
"order": "rest.order"
"order_by": "rest.order_by"
"label_search": "rest.label_search"
"description_search": "rest.description_search"
"value_search": "rest.value_search"
"connected_to_agents_count_gt": "rest.connected_to_agents_count_gt"
"connected_to_agents_count_lt": "rest.connected_to_agents_count_lt"
"connected_to_agents_count_eq": "rest.connected_to_agents_count_eq"
outputParameters:
- type: object
mapping: "$."
- method: POST
name: "create_block"
description: "Create Block"
call: "letta-blocks.create_block"
with:
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/blocks/count"
name: "blocks-count"
description: "REST surface for blocks-count."
operations:
- method: GET
name: "count_blocks"
description: "Count Blocks"
call: "letta-blocks.count_blocks"
with:
"label": "rest.label"
"templates_only": "rest.templates_only"
"name": "rest.name"
"tags": "rest.tags"
"match_all_tags": "rest.match_all_tags"
"project_id": "rest.project_id"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/blocks/{block-id}"
name: "blocks-by-id"
description: "REST surface for blocks-by-id."
operations:
- method: PATCH
name: "modify_block"
description: "Modify Block"
call: "letta-blocks.modify_block"
with:
"block_id": "rest.block_id"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- method: DELETE
name: "delete_block"
description: "Delete Block"
call: "letta-blocks.delete_block"
with:
"block_id": "rest.block_id"
outputParameters:
- type: object
mapping: "$."
- method: GET
name: "retrieve_block"
description: "Retrieve Block"
call: "letta-blocks.retrieve_block"
with:
"block_id": "rest.block_id"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/blocks/{block-id}/agents"
name: "blocks-by-id-agents"
description: "REST surface for blocks-by-id-agents."
operations:
- method: GET
name: "list_agents_for_block"
description: "List Agents for Block"
call: "letta-blocks.list_agents_for_block"
with:
"block_id": "rest.block_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
"include_relationships": "rest.include_relationships"
"include": "rest.include"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/blocks/{block-id}/identities/attach/{identity-id}"
name: "blocks-by-id-identities-attach-by-id"
description: "REST surface for blocks-by-id-identities-attach-by-id."
operations:
- method: PATCH
name: "attach_identity_to_block"
description: "Attach Identity to Block"
call: "letta-blocks.attach_identity_to_block"
with:
"identity_id": "rest.identity_id"
"block_id": "rest.block_id"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/blocks/{block-id}/identities/detach/{identity-id}"
name: "blocks-by-id-identities-detach-by-id"
description: "REST surface for blocks-by-id-identities-detach-by-id."
operations:
- method: PATCH
name: "detach_identity_from_block"
description: "Detach Identity from Block"
call: "letta-blocks.detach_identity_from_block"
with:
"identity_id": "rest.identity_id"
"block_id": "rest.block_id"
outputParameters:
- type: object
mapping: "$."
- type: mcp
namespace: "letta-blocks-mcp"
port: 9090
transport: http
description: "MCP adapter for Letta API — Blocks. One verb-noun tool per consumed operation."
tools:
- name: "list-blocks"
description: "List Blocks"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-blocks.list_blocks"
with:
"label": "tools.label"
"templates_only": "tools.templates_only"
"name": "tools.name"
"identity_id": "tools.identity_id"
"identifier_keys": "tools.identifier_keys"
"project_id": "tools.project_id"
"tags": "tools.tags"
"match_all_tags": "tools.match_all_tags"
"limit": "tools.limit"
"before": "tools.before"
"after": "tools.after"
"order": "tools.order"
"order_by": "tools.order_by"
"label_search": "tools.label_search"
"description_search": "tools.description_search"
"value_search": "tools.value_search"
"connected_to_agents_count_gt": "tools.connected_to_agents_count_gt"
"connected_to_agents_count_lt": "tools.connected_to_agents_count_lt"
"connected_to_agents_count_eq": "tools.connected_to_agents_count_eq"
outputParameters:
- type: object
mapping: "$."
- name: "create-block"
description: "Create Block"
hints:
readOnly: false
destructive: false
idempotent: false
call: "letta-blocks.create_block"
with:
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "count-blocks"
description: "Count Blocks"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-blocks.count_blocks"
with:
"label": "tools.label"
"templates_only": "tools.templates_only"
"name": "tools.name"
"tags": "tools.tags"
"match_all_tags": "tools.match_all_tags"
"project_id": "tools.project_id"
outputParameters:
- type: object
mapping: "$."
- name: "modify-block"
description: "Modify Block"
hints:
readOnly: false
destructive: false
idempotent: true
call: "letta-blocks.modify_block"
with:
"block_id": "tools.block_id"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "delete-block"
description: "Delete Block"
hints:
readOnly: false
destructive: true
idempotent: true
call: "letta-blocks.delete_block"
with:
"block_id": "tools.block_id"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-block"
description: "Retrieve Block"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-blocks.retrieve_block"
with:
"block_id": "tools.block_id"
outputParameters:
- type: object
mapping: "$."
- name: "list-agents-block"
description: "List Agents for Block"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-blocks.list_agents_for_block"
with:
"block_id": "tools.block_id"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
"include_relationships": "tools.include_relationships"
"include": "tools.include"
outputParameters:
- type: object
mapping: "$."
- name: "attach-identity-block"
description: "Attach Identity to Block"
hints:
readOnly: false
destructive: false
idempotent: true
call: "letta-blocks.attach_identity_to_block"
with:
"identity_id": "tools.identity_id"
"block_id": "tools.block_id"
outputParameters:
- type: object
mapping: "$."
- name: "detach-identity-block"
description: "Detach Identity from Block"
hints:
readOnly: false
destructive: false
idempotent: true
call: "letta-blocks.detach_identity_from_block"
with:
"identity_id": "tools.identity_id"
"block_id": "tools.block_id"
outputParameters:
- type: object
mapping: "$."