openapi: 3.1.0
info:
title: Letta Admin Agents 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: Agents
description: Create, list, modify, export, and delete stateful agents with memory and tools.
paths:
/v1/agents/:
get:
tags:
- Agents
summary: List Agents
description: Get a list of all agents.
operationId: list_agents
parameters:
- name: name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Name of the agent
title: Name
description: Name of the agent
- name: tags
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: List of tags to filter agents by
title: Tags
description: List of tags to filter agents by
- name: match_all_tags
in: query
required: false
schema:
type: boolean
description: If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags.
default: false
title: Match All Tags
description: If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags.
- name: before
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Cursor for pagination
title: Before
description: Cursor for pagination
- name: after
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Cursor for pagination
title: After
description: Cursor for pagination
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Limit for pagination
default: 50
title: Limit
description: Limit for pagination
- name: query_text
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by name
title: Query Text
description: Search agents by name
- name: project_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by project ID - this will default to your default project on cloud
title: Project Id
description: Search agents by project ID - this will default to your default project on cloud
- name: template_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by template ID
title: Template Id
description: Search agents by template ID
- name: base_template_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by base template ID
title: Base Template Id
description: Search agents by base template ID
- name: identity_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by identity ID
title: Identity Id
description: Search agents by identity ID
- 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: 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.
- 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:
enum:
- created_at
- updated_at
- last_run_completion
type: string
description: Field to sort by
default: created_at
title: Order By
description: Field to sort by
- name: ascending
in: query
required: false
schema:
type: boolean
description: Whether to sort agents oldest to newest (True) or newest to oldest (False, default)
deprecated: true
default: false
title: Ascending
description: Whether to sort agents oldest to newest (True) or newest to oldest (False, default)
deprecated: true
- name: sort_by
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'Field to sort by. Options: ''created_at'' (default), ''last_run_completion'''
deprecated: true
default: created_at
title: Sort By
description: 'Field to sort by. Options: ''created_at'' (default), ''last_run_completion'''
deprecated: true
- name: last_stop_reason
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/StopReasonType'
- type: 'null'
description: Filter agents by their last stop reason.
title: Last Stop Reason
description: Filter agents by their last stop reason.
- name: created_by_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter agents by the user who created them.
title: Created By Id
description: Filter agents by the user who created them.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentState'
title: Response List Agents
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Agents
summary: Create Agent
description: Create an agent.
operationId: create_agent
parameters:
- name: X-Project
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The project slug to associate with the agent (cloud only).
title: X-Project
description: The project slug to associate with the agent (cloud only).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgentRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentState'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/count:
get:
tags:
- Agents
summary: Count Agents
description: 'Get the total number of agents with optional filtering.
Supports the same filters as list_agents for consistent querying.'
operationId: count_agents
parameters:
- name: name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Name of the agent
title: Name
description: Name of the agent
- name: tags
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: List of tags to filter agents by
title: Tags
description: List of tags to filter agents by
- name: match_all_tags
in: query
required: false
schema:
type: boolean
description: If True, only counts agents that match ALL given tags. Otherwise, counts agents that have ANY of the passed-in tags.
default: false
title: Match All Tags
description: If True, only counts agents that match ALL given tags. Otherwise, counts agents that have ANY of the passed-in tags.
- name: query_text
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by name
title: Query Text
description: Search agents by name
- name: project_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by project ID - this will default to your default project on cloud
title: Project Id
description: Search agents by project ID - this will default to your default project on cloud
- name: template_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by template ID
title: Template Id
description: Search agents by template ID
- name: base_template_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by base template ID
title: Base Template Id
description: Search agents by base template ID
- name: identity_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search agents by identity ID
title: Identity Id
description: Search agents by identity ID
- 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: last_stop_reason
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/StopReasonType'
- type: 'null'
description: Filter agents by their last stop reason.
title: Last Stop Reason
description: Filter agents by their last stop reason.
- name: created_by_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter agents by the user who created them.
title: Created By Id
description: Filter agents by the user who created them.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: integer
title: Response Count Agents
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/{agent_id}/export:
get:
tags:
- Agents
summary: Export Agent
description: Export the serialized JSON representation of an agent, formatted with indentation.
operationId: export_agent
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
- name: max_steps
in: query
required: false
schema:
type: integer
deprecated: true
default: 100
title: Max Steps
deprecated: true
- name: use_legacy_format
in: query
required: false
schema:
type: boolean
description: If True, exports using the legacy single-agent 'v1' format with inline tools/blocks. If False, exports using the new multi-entity 'v2' format, with separate agents, tools, blocks, files, etc.
deprecated: true
default: false
title: Use Legacy Format
description: If True, exports using the legacy single-agent 'v1' format with inline tools/blocks. If False, exports using the new multi-entity 'v2' format, with separate agents, tools, blocks, files, etc.
deprecated: true
- name: conversation_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Conversation ID to export. If provided, uses messages from this conversation instead of the agent's global message history.
title: Conversation Id
description: Conversation ID to export. If provided, uses messages from this conversation instead of the agent's global message history.
- name: scrub_messages
in: query
required: false
schema:
type: boolean
description: If True, excludes all messages from the export. Useful for sharing agent configs without conversation history.
default: false
title: Scrub Messages
description: If True, excludes all messages from the export. Useful for sharing agent configs without conversation history.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_export_agent'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: string
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Agents
summary: Export Agent with Skills
description: 'Export the serialized JSON representation of an agent with optional skills.
This POST endpoint allows including skills in the export by providing them in the request body.
Skills are resolved client-side and passed as SkillSchema objects containing the skill files.'
operationId: export_agent_with_skills
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ExportAgentRequest'
- type: 'null'
title: Request
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: string
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/import:
post:
tags:
- Agents
summary: Import Agent
description: 'Import a serialized agent file and recreate the agent(s) in the system.
Returns the IDs of all imported agents.'
operationId: import_agent
parameters:
- name: x-override-embedding-model
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Override-Embedding-Model
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_import_agent'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ImportedAgentsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/{agent_id}/context:
get:
tags:
- Agents
summary: Retrieve Agent Context Window
description: Retrieve the context window of a specific agent.
operationId: retrieve_agent_context_window
deprecated: true
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^agent-[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 agent in the format 'agent-<uuid4>'
examples:
- agent-123e4567-e89b-42d3-8456-426614174000
title: Agent Id
description: The ID of the agent in the format 'agent-<uuid4>'
- name: conversation_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Conversation ID to get context window for. If provided, uses messages from this conversation.
title: Conversation Id
description: Conversation ID to get context window for. If provided, uses messages from this conversation.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContextWindowOverview'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/{agent_id}:
patch:
tags:
- Agents
summary: Modify Agent
description: Update an existing agent.
operationId: modify_agent
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^agent-[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 agent in the format 'agent-<uuid4>'
examples:
- agent-123e4567-e89b-42d3-8456-426614174000
title: Agent Id
description: The ID of the agent in the format 'agent-<uuid4>'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAgent'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentState'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Agents
summary: Retrieve Agent
description: Get the state of the agent.
operationId: retrieve_agent
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^agent-[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 agent in the format 'agent-<uuid4>'
examples:
- agent-123e4567-e89b-42d3-8456-426614174000
title: Agent Id
description: The ID of the agent in the format 'agent-<uuid4>'
- 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:
$ref: '#/components/schemas/AgentState'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Agents
summary: Delete Agent
description: Delete an agent.
operationId: delete_agent
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^agent-[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 agent in the format 'agent-<uuid4>'
examples:
- agent-123e4567-e89b-42d3-8456-426614174000
title: Agent Id
description: The ID of the agent in the format 'agent-<uuid4>'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/{agent_id}/tools:
get:
tags:
- Agents
summary: List Tools for Agent
description: Get tools from an existing agent.
operationId: list_tools_for_agent
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^agent-[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 agent in the format 'agent-<uuid4>'
examples:
- agent-123e4567-e89b-42d3-8456-426614174000
title: Agent Id
description: The ID of the agent in the format 'agent-<uuid4>'
- name: before
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Tool ID cursor for pagination. Returns tools that come before this tool ID in the specified sort order
title: Before
description: Tool ID cursor for pagination. Returns tools that come before this tool ID in the specified sort order
- name: after
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Tool ID cursor for pagination. Returns tools that come after this tool ID in the specified sort order
title: After
description: Tool ID cursor for pagination. Returns tools that come after this tool ID in the specified sort order
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Maximum number of tools to return
default: 10
title: Limit
description: Maximum number of tools to return
- name: order
in: query
required: false
schema:
enum:
- asc
- desc
type: string
description: Sort order for tools by creation time. 'asc' for oldest first, 'desc' for newest first
default: desc
title: Order
description: Sort order for tools 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Tool'
title: Response List Tools For Agent
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/{agent_id}/tools/attach/{tool_id}:
patch:
tags:
- Agents
summary: Attach Tool to Agent
description: Attach a tool to an agent.
operationId: attach_tool_to_agent
parameters:
- name: tool_id
in: path
required: true
schema:
type: string
minLength: 41
maxLength: 41
pattern: ^tool-[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 tool in the format 'tool-<uuid4>'
examples:
- tool-123e4567-e89b-42d3-8456-426614174000
title: Tool Id
description: The ID of the tool in the format 'tool-<uuid4>'
- name: agent_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^agent-[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 agent in the format 'agent-<uuid4>'
examples:
- agent-123e4567-e89b-42d3-8456-426614174000
title: Agent Id
description: The ID of the agent in the format 'agent-<uuid4>'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AgentState'
- type: 'null'
title: Response Attach Tool To Agent
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/{agent_id}/tools/detach/{tool_id}:
patch:
tags:
- Agents
summary: Detach Tool from Agent
description: Detach a tool from an agent.
operationId: detach_tool_from_agent
parameters:
- name: tool_id
in: path
required: true
schema:
type: string
minLength: 41
maxLength: 41
pattern: ^tool-[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 tool in the format 'tool-<uuid4>'
examples:
- tool-123e4567-e89b-42d3-8456-426614174000
title: Tool Id
description: The ID of the tool in the format 'tool-<uuid4>'
- name: agent_id
in: path
required: true
schema:
type: string
minLength: 42
maxLength: 42
pattern: ^agent-[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 agent in the format 'agent-<uuid4>'
examples:
- agent-123e4567-e89b-42d3-8456-426614174000
title: Agent Id
description: The ID of the agent in the format 'agent-<uuid4>'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AgentState'
- type: 'null'
title: Response Detach Tool From Agent
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/agents/{agent_id}/tools/approval/{tool_name}:
patch:
tags:
- Agents
summary: Modify Approval for Tool
description: 'Modify the approval requirement for a tool attached to an agent.
Accepts requires_approval via request body (preferred) or query parameter (deprecated).'
operationId: modify_approval_for_tool
parameters:
- name: tool_name
in: path
# --- truncated at 32 KB (436 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/openapi/letta-agents-api-openapi.yml