openapi: 3.1.0
info:
title: Letta Admin Internal 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: Internal Blocks
description: Internal Blocks operations.
paths:
/v1/_internal_blocks/:
get:
tags:
- Internal Blocks
summary: List Blocks
operationId: list_internal_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: 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/Block'
title: Response List Internal Blocks
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Internal Blocks
summary: Create Block
operationId: create_internal_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/Block'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/_internal_blocks/{block_id}:
delete:
tags:
- Internal Blocks
summary: Delete Block
operationId: delete_internal_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'
/v1/_internal_blocks/{block_id}/agents:
get:
tags:
- Internal 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_internal_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:
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 Internal Block
'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.
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
- type: 'null'
title: Pip Requirements
description: Optional list of pip packages required by this tool.
npm_requirements:
anyOf:
- items:
$ref: '#/components/schemas/NpmRequirement'
type: array
- type: 'null'
title: Npm Requirements
description: Optional list of npm packages required by this tool.
default_requires_approval:
anyOf:
- type: boolean
- type: 'null'
title: Default Requires Approval
description: Default value for whether or not executing this tool requires approval.
enable_parallel_execution:
anyOf:
- type: boolean
- type: 'null'
title: Enable Parallel Execution
description: If set to True, then this tool will potentially be executed concurrently with other tools. Default False.
default: false
created_by_id:
anyOf:
- type: string
- type: 'null'
title: Created By Id
description: The id of the user that made this Tool.
last_updated_by_id:
anyOf:
- type: string
- type: 'null'
title: Last Updated By Id
description: The id of the user that made this Tool.
metadata_:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
description: A dictionary of additional metadata for the tool.
project_id:
anyOf:
- type: string
- type: 'null'
title: Project Id
description: The project id of the tool.
additionalProperties: false
type: object
title: Tool
description: Representation of a tool, which is a function that can be called by the agent.
AgentEnvironmentVariable:
properties:
created_by_id:
anyOf:
- type: string
- type: 'null'
title: Created By Id
description: The id of the user that made this object.
last_updated_by_id:
anyOf:
- type: string
- type: 'null'
title: Last Updated By Id
description: The id of the user that made this object.
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: The timestamp when the object was created.
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
description: The timestamp when the object was last updated.
id:
type: string
pattern: ^agent-env-[a-fA-F0-9]{8}
title: Id
description: The human-friendly ID of the Agent-env
examples:
- agent-env-123e4567-e89b-12d3-a456-426614174000
key:
type: string
title: Key
description: The name of the environment variable.
value:
type: string
title: Value
description: The value of the environment variable.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: An optional description of the environment variable.
value_enc:
anyOf:
- type: string
description: Encrypted secret value (stored as encrypted string)
nullable: true
- type: 'null'
title: Value Enc
description: Encrypted value as Secret object
agent_id:
type: string
title: Agent Id
description: The ID of the agent this environment variable belongs to.
additionalProperties: false
type: object
required:
- key
- value
- agent_id
title: AgentEnvironmentVariable
ChatGPTOAuthModelSettings:
properties:
max_output_tokens:
type: integer
title: Max Output Tokens
description: The maximum number of tokens the model can generate.
default: 4096
parallel_tool_calls:
type: boolean
title: Parallel Tool Calls
description: Whether to enable parallel tool calling.
default: true
provider_type:
type: string
const: chatgpt_oauth
title: Provider Type
description: The type of the provider.
default: chatgpt_oauth
temperature:
type: number
title: Temperature
description: The temperature of the model.
default: 0.7
reasoning:
$ref: '#/components/schemas/ChatGPTOAuthReasoning'
description: The reasoning configuration for the model.
default:
reasoning_effort: medium
type: object
title: ChatGPTOAuthModelSettings
description: ChatGPT OAuth model configuration (uses ChatGPT backend API).
TextResponseFormat:
properties:
type:
type: string
const: text
title: Type
description: The type of the response format.
default: text
type: object
title: TextResponseFormat
description: Response format for plain text responses.
ToolType:
type: string
enum:
- custom
- letta_core
- letta_memory_core
- letta_multi_agent_core
- letta_sleeptime_core
- letta_voice_sleeptime_core
- letta_builtin
- letta_files_core
- external_langchain
- external_composio
- external_mcp
title: ToolType
ToolCallDelta:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
arguments:
anyOf:
- type: string
- type: 'null'
title: Arguments
tool_call_id:
anyOf:
- type: string
- type: 'null'
title: Tool Call Id
type: object
title: ToolCallDelta
ConditionalToolRule:
properties:
tool_name:
type: string
title: Tool Name
description: The name of the tool. Must exist in the database for the user's organization.
type:
type: string
const: conditional
title: Type
default: conditional
prompt_template:
anyOf:
- type: string
- type: 'null'
title: Prompt Template
description: Optional template string (ignored).
default_child:
anyOf:
- type: string
- type: 'null'
title: Default Child
description: The default child tool to be called. If None, any tool can be called.
child_output_mapping:
additionalProperties:
type: string
type: object
title: Child Output Mapping
description: The output case to check for mapping
require_output_mapping:
type: boolean
title: Require Output Mapping
description: Whether to throw an error when output doesn't match any case
default: false
additionalProperties: false
type: object
required:
- tool_name
- child_output_mapping
title: ConditionalToolRule
description: A ToolRule that conditionally maps to different child tools based on the output.
MaxCountPerStepToolRule:
properties:
tool_name:
type: string
title: Tool Name
description: The name of the tool. Must exist in the database for the user's organization.
type:
type: string
const: max_count_per_step
title: Type
default: max_count_per_step
prompt_template:
anyOf:
- type: string
- type: 'null'
title: Prompt Template
description: Optional template string (ignored).
max_count_limit:
type: integer
title: Max Count Limit
description: The max limit for the total number of times this tool can be invoked in a single step.
additionalProperties: false
type: object
required:
- tool_name
- max_count_limit
title: MaxCountPerStepToolRule
description: Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step.
ZAIThinking:
properties:
type:
type: string
enum:
- enabled
- disabled
title: Type
description: Whether thinking is enabled or disabled.
default: enabled
clear_thinking:
type: boolean
title: Clear Thinking
description: If False, preserved thinking is used (recommended for agents).
default: false
type: object
title: ZAIThinking
description: Thinking configuration for ZAI GLM-4.5+ models.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ContinueToolRule:
properties:
tool_name:
type: string
title: Tool Name
description: The name of the tool. Must exist in the database for the user's organization.
type:
type: string
const: continue_loop
title: Type
default: continue_loop
prompt_template:
anyOf:
- type: string
- type: 'null'
title: Prompt Template
description: Optional template string (ignored).
additionalProperties: false
type: object
required:
- tool_name
title: ContinueToolRule
description: Represents a tool rule configuration where if this tool gets called, it must continue the agent loop.
NpmRequirement:
properties:
name:
type: string
minLength: 1
title: Name
description: Name of the npm package.
version:
anyOf:
- type: string
- type: 'null'
title: Version
description: Optional version of the package, following semantic versioning.
type: object
required:
- name
title: NpmRequirement
GoogleVertexModelSettings:
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_vertex
title: Provider Type
description: The type of the provider.
default: google_vertex
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: GoogleVertexModelSettings
RequiresApprovalToolRule:
properties:
tool_name:
type: string
title: Tool Name
description: The name of the tool. Must exist in the database for the user's organization.
type:
type: string
const: requires_approval
# --- truncated at 32 KB (112 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/openapi/letta-internal-blocks-api-openapi.yml