openapi: 3.1.0
info:
title: Letta Admin Blocks API
version: 1.0.0
description: REST API for Letta, the stateful agents platform. Manage agents, memory blocks, archival passages, sources, custom tools, MCP servers, multi-agent groups, runs, and streaming responses. Available as Letta Cloud (managed) at https://api.letta.com/v1 and as the self-hosted open-source server (Apache-2.0) typically run at http://localhost:8283.
contact:
name: Letta
url: https://www.letta.com/
email: support@letta.com
license:
name: Apache-2.0
url: https://github.com/letta-ai/letta/blob/main/LICENSE
x-logo:
url: https://www.letta.com/favicon.ico
servers:
- url: https://api.letta.com
description: Letta Cloud (managed)
- url: https://app.letta.com
description: Letta Cloud (app)
- url: http://localhost:8283
description: Self-hosted Letta server
security:
- bearerAuth: []
tags:
- name: Blocks
description: Manage in-context memory blocks (core memory) shared across agents.
paths:
/v1/blocks/:
get:
tags:
- Blocks
summary: List Blocks
operationId: list_blocks
parameters:
- name: label
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 50
pattern: ^[a-zA-Z0-9_/-]+$
- type: 'null'
description: Label to include (alphanumeric, hyphens, underscores, forward slashes)
examples:
- human
- persona
- the_label_of-a-block
- the_label_of-a-block/with-forward-slash
title: Label
description: Label to include (alphanumeric, hyphens, underscores, forward slashes)
- name: templates_only
in: query
required: false
schema:
type: boolean
description: Whether to include only templates
default: false
title: Templates Only
description: Whether to include only templates
- name: name
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 100
pattern: ^[a-zA-Z0-9 _-]+$
- type: 'null'
description: Name filter (alphanumeric, spaces, hyphens, underscores)
examples:
- My Agent
- test_tool
- default-config
title: Name
description: Name filter (alphanumeric, spaces, hyphens, underscores)
- name: identity_id
in: query
required: false
schema:
anyOf:
- type: string
minLength: 45
maxLength: 45
pattern: ^identity-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
- type: 'null'
description: The ID of the identity in the format 'identity-<uuid4>'
examples:
- identity-123e4567-e89b-42d3-8456-426614174000
title: Identity Id
description: The ID of the identity in the format 'identity-<uuid4>'
- name: identifier_keys
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Search agents by identifier keys
title: Identifier Keys
description: Search agents by identifier keys
- name: project_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search blocks by project id
title: Project Id
description: Search blocks by project id
- name: tags
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: List of tags to filter blocks by
title: Tags
description: List of tags to filter blocks by
- name: match_all_tags
in: query
required: false
schema:
type: boolean
description: If True, only returns blocks that match ALL given tags. Otherwise, return blocks that have ANY of the passed-in tags.
default: false
title: Match All Tags
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
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Number of blocks to return
default: 50
title: Limit
description: Number of blocks to return
- name: before
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Block ID cursor for pagination. Returns blocks that come before this block ID in the specified sort order
title: Before
description: Block ID cursor for pagination. Returns blocks that come before this block ID in the specified sort order
- name: after
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Block ID cursor for pagination. Returns blocks that come after this block ID in the specified sort order
title: After
description: Block ID cursor for pagination. Returns blocks that come after this block ID in the specified sort order
- name: order
in: query
required: false
schema:
enum:
- asc
- desc
type: string
description: Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest first
default: asc
title: Order
description: Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest first
- name: order_by
in: query
required: false
schema:
const: created_at
type: string
description: Field to sort by
default: created_at
title: Order By
description: Field to sort by
- name: label_search
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 50
pattern: ^[a-zA-Z0-9_/-]+$
- type: 'null'
description: Search blocks by label. If provided, returns blocks whose label matches the search query. This is a full-text search on block labels.
examples:
- human
- persona
- the_label_of-a-block
- the_label_of-a-block/with-forward-slash
title: Label Search
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
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 200
- type: 'null'
description: Search blocks by description. If provided, returns blocks whose description matches the search query. This is a full-text search on block descriptions.
title: Description Search
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
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 200
- type: 'null'
description: Search blocks by value. If provided, returns blocks whose value matches the search query. This is a full-text search on block values.
title: Value Search
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
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Filter blocks by the number of connected agents. If provided, returns blocks that have more than this number of connected agents.
title: Connected To Agents Count Gt
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
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Filter blocks by the number of connected agents. If provided, returns blocks that have less than this number of connected agents.
title: Connected To Agents Count Lt
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
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: Filter blocks by the exact number of connected agents. If provided, returns blocks that have exactly this number of connected agents.
title: Connected To Agents Count Eq
description: Filter blocks by the exact number of connected agents. If provided, returns blocks that have exactly this number of connected agents.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BlockResponse'
title: Response List Blocks
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Blocks
summary: Create Block
operationId: create_block
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBlock'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BlockResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/blocks/count:
get:
tags:
- Blocks
summary: Count Blocks
description: 'Count all blocks with optional filtering.
Supports the same filters as list_blocks for consistent querying.'
operationId: count_blocks
parameters:
- name: label
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 50
pattern: ^[a-zA-Z0-9_/-]+$
- type: 'null'
description: Label to include (alphanumeric, hyphens, underscores, forward slashes)
examples:
- human
- persona
- the_label_of-a-block
- the_label_of-a-block/with-forward-slash
title: Label
description: Label to include (alphanumeric, hyphens, underscores, forward slashes)
- name: templates_only
in: query
required: false
schema:
type: boolean
description: Whether to include only templates
default: false
title: Templates Only
description: Whether to include only templates
- name: name
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 100
pattern: ^[a-zA-Z0-9 _-]+$
- type: 'null'
description: Name filter (alphanumeric, spaces, hyphens, underscores)
examples:
- My Agent
- test_tool
- default-config
title: Name
description: Name filter (alphanumeric, spaces, hyphens, underscores)
- name: tags
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: List of tags to filter blocks by
title: Tags
description: List of tags to filter blocks by
- name: match_all_tags
in: query
required: false
schema:
type: boolean
description: If True, only counts blocks that match ALL given tags. Otherwise, counts blocks that have ANY of the passed-in tags.
default: false
title: Match All Tags
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
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search blocks by project id
title: Project Id
description: Search blocks by project id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: integer
title: Response Count Blocks
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/blocks/{block_id}:
patch:
tags:
- Blocks
summary: Modify Block
operationId: modify_block
parameters:
- name: block_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^block-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
description: The ID of the block in the format 'block-<uuid4>'
examples:
- block-123e4567-e89b-42d3-8456-426614174000
title: Block Id
description: The ID of the block in the format 'block-<uuid4>'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BlockUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BlockResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Blocks
summary: Delete Block
operationId: delete_block
parameters:
- name: block_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^block-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
description: The ID of the block in the format 'block-<uuid4>'
examples:
- block-123e4567-e89b-42d3-8456-426614174000
title: Block Id
description: The ID of the block in the format 'block-<uuid4>'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Blocks
summary: Retrieve Block
operationId: retrieve_block
parameters:
- name: block_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^block-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
description: The ID of the block in the format 'block-<uuid4>'
examples:
- block-123e4567-e89b-42d3-8456-426614174000
title: Block Id
description: The ID of the block in the format 'block-<uuid4>'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BlockResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/blocks/{block_id}/agents:
get:
tags:
- Blocks
summary: List Agents for Block
description: 'Retrieves all agents associated with the specified block.
Raises a 404 if the block does not exist.'
operationId: list_agents_for_block
parameters:
- name: block_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^block-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
description: The ID of the block in the format 'block-<uuid4>'
examples:
- block-123e4567-e89b-42d3-8456-426614174000
title: Block Id
description: The ID of the block in the format 'block-<uuid4>'
- name: before
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order
title: Before
description: Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order
- name: after
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order
title: After
description: Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Maximum number of agents to return
default: 50
title: Limit
description: Maximum number of agents to return
- name: order
in: query
required: false
schema:
enum:
- asc
- desc
type: string
description: Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first
default: desc
title: Order
description: Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first
- name: order_by
in: query
required: false
schema:
const: created_at
type: string
description: Field to sort by
default: created_at
title: Order By
description: Field to sort by
- name: include_relationships
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
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 reducing unnecessary joins.This is a legacy parameter, and no longer supported after 1.0.0 SDK versions.
deprecated: true
title: Include Relationships
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 reducing unnecessary joins.This is a legacy parameter, and no longer supported after 1.0.0 SDK versions.
deprecated: true
- name: include
in: query
required: false
schema:
type: array
items:
enum:
- agent.blocks
- agent.identities
- agent.managed_group
- agent.pending_approval
- agent.secrets
- agent.sources
- agent.tags
- agent.tools
type: string
description: Specify which relational fields to include in the response. No relationships are included by default.
default: []
title: Include
description: Specify which relational fields to include in the response. No relationships are included by default.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentState'
title: Response List Agents For Block
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/blocks/{block_id}/identities/attach/{identity_id}:
patch:
tags:
- Blocks
summary: Attach Identity to Block
description: Attach an identity to a block.
operationId: attach_identity_to_block
parameters:
- name: identity_id
in: path
required: true
schema:
type: string
title: Identity Id
- name: block_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^block-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
description: The ID of the block in the format 'block-<uuid4>'
examples:
- block-123e4567-e89b-42d3-8456-426614174000
title: Block Id
description: The ID of the block in the format 'block-<uuid4>'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BlockResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/blocks/{block_id}/identities/detach/{identity_id}:
patch:
tags:
- Blocks
summary: Detach Identity from Block
description: Detach an identity from a block.
operationId: detach_identity_from_block
parameters:
- name: identity_id
in: path
required: true
schema:
type: string
title: Identity Id
- name: block_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^block-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
description: The ID of the block in the format 'block-<uuid4>'
examples:
- block-123e4567-e89b-42d3-8456-426614174000
title: Block Id
description: The ID of the block in the format 'block-<uuid4>'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BlockResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
JsonObjectResponseFormat:
properties:
type:
type: string
const: json_object
title: Type
description: The type of the response format.
default: json_object
type: object
title: JsonObjectResponseFormat
description: Response format for JSON object responses.
BlockResponse:
properties:
value:
type: string
title: Value
description: Value of the block.
limit:
type: integer
title: Limit
description: Character limit of the block.
default: 100000
project_id:
anyOf:
- type: string
- type: 'null'
title: Project Id
description: The associated project id.
template_name:
anyOf:
- type: string
- type: 'null'
title: Template Name
description: (Deprecated) The name of the block template (if it is a template).
deprecated: true
is_template:
type: boolean
title: Is Template
description: Whether the block is a template (e.g. saved human/persona options).
default: false
template_id:
anyOf:
- type: string
- type: 'null'
title: Template Id
description: (Deprecated) The id of the template.
deprecated: true
base_template_id:
anyOf:
- type: string
- type: 'null'
title: Base Template Id
description: (Deprecated) The base template id of the block.
deprecated: true
deployment_id:
anyOf:
- type: string
- type: 'null'
title: Deployment Id
description: (Deprecated) The id of the deployment.
deprecated: true
entity_id:
anyOf:
- type: string
- type: 'null'
title: Entity Id
description: (Deprecated) The id of the entity within the template.
deprecated: true
preserve_on_migration:
anyOf:
- type: boolean
- type: 'null'
title: Preserve On Migration
description: (Deprecated) Preserve the block on template migration.
default: false
deprecated: true
label:
anyOf:
- type: string
- type: 'null'
title: Label
description: Label of the block (e.g. 'human', 'persona') in the context window.
read_only:
type: boolean
title: Read Only
description: (Deprecated) Whether the agent has read-only access to the block.
default: false
deprecated: true
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Description of the block.
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
description: Metadata of the block.
default: {}
hidden:
anyOf:
- type: boolean
- type: 'null'
title: Hidden
description: (Deprecated) If set to True, the block will be hidden.
deprecated: true
id:
type: string
title: Id
description: The id of the block.
created_by_id:
anyOf:
- type: string
- type: 'null'
title: Created By Id
description: The id of the user that made this Block.
last_updated_by_id:
anyOf:
- type: string
- type: 'null'
title: Last Updated By Id
description: The id of the user that last updated this Block.
tags:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Tags
description: The tags associated with the block.
default: []
type: object
required:
- value
- id
title: BlockResponse
GoogleAIModelSettings:
properties:
max_output_tokens:
type: integer
title: Max Output Tokens
description: The maximum number of tokens the model can generate.
default: 65536
parallel_tool_calls:
type: boolean
title: Parallel Tool Calls
description: Whether to enable parallel tool calling.
default: true
provider_type:
type: string
const: google_ai
title: Provider Type
description: The type of the provider.
default: google_ai
temperature:
type: number
title: Temperature
description: The temperature of the model.
default: 0.7
thinking_config:
$ref: '#/components/schemas/GeminiThinkingConfig'
description: The thinking configuration for the model.
default:
include_thoughts: true
thinking_budget: 1024
response_schema:
anyOf:
- oneOf:
- $ref: '#/components/schemas/TextResponseFormat'
- $ref: '#/components/schemas/JsonSchemaResponseFormat'
- $ref: '#/components/schemas/JsonObjectResponseFormat'
discriminator:
propertyName: type
mapping:
json_object: '#/components/schemas/JsonObjectResponseFormat'
json_schema: '#/components/schemas/JsonSchemaResponseFormat'
text: '#/components/schemas/TextResponseFormat'
- type: 'null'
title: Response Schema
description: The response schema for the model.
type: object
title: GoogleAIModelSettings
StopReasonType:
type: string
enum:
- end_turn
- error
- llm_api_error
- invalid_llm_response
- invalid_tool_call
- max_steps
- max_tokens_exceeded
- no_tool_call
- tool_rule
- cancelled
- insufficient_credits
- requires_approval
- context_window_overflow_in_system_prompt
title: StopReasonType
Tool:
properties:
id:
type: string
pattern: ^tool-[a-fA-F0-9]{8}
title: Id
description: The human-friendly ID of the Tool
examples:
- tool-123e4567-e89b-12d3-a456-426614174000
tool_type:
$ref: '#/components/schemas/ToolType'
description: The type of the tool.
default: custom
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: The description of the tool.
source_type:
anyOf:
- type: string
- type: 'null'
title: Source Type
description: The type of the source code.
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the function.
tags:
items:
type: string
type: array
title: Tags
description: Metadata tags.
default: []
source_code:
anyOf:
- type: string
- type: 'null'
title: Source Code
description: The source code of the function.
json_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Json Schema
description: The JSON schema of the function.
args_json_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Args Json Schema
description: The args JSON schema of the function.
return_char_limit:
type: integer
maximum: 1000000
minimum: 1
title: Return Char Limit
description: The maximum number of characters in the response.
default: 50000
pip_requirements:
anyOf:
- items:
$ref: '#/components/schemas/PipRequirement'
type: array
# --- truncated at 32 KB (127 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/openapi/letta-blocks-api-openapi.yml