openapi: 3.1.0 info: title: Letta 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: [] paths: /v1/archives/: post: tags: - Archives summary: Create Archive description: Create a new archive. operationId: create_archive parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ArchiveCreateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Archive' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' get: tags: - Archives summary: List Archives description: Get a list of all archives for the current organization with optional filters and pagination. operationId: list_archives parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Archive ID cursor for pagination. Returns archives that come before this archive ID in the specified sort order title: Before description: Archive ID cursor for pagination. Returns archives that come before this archive ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Archive ID cursor for pagination. Returns archives that come after this archive ID in the specified sort order title: After description: Archive ID cursor for pagination. Returns archives that come after this archive ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of archives to return default: 50 title: Limit description: Maximum number of archives to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for archives by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for archives 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: name in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by archive name (exact match) title: Name description: Filter by archive name (exact match) - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only archives attached to this agent ID title: Agent Id description: Only archives attached to this agent ID responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Archive' title: Response List Archives '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/archives/{archive_id}: get: tags: - Archives summary: Retrieve Archive description: Get a single archive by its ID. operationId: retrieve_archive parameters: - name: archive_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^archive-[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 archive in the format 'archive-' examples: - archive-123e4567-e89b-42d3-8456-426614174000 title: Archive Id description: The ID of the archive in the format 'archive-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Archive' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Archives summary: Modify Archive description: Update an existing archive's name and/or description. operationId: modify_archive parameters: - name: archive_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^archive-[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 archive in the format 'archive-' examples: - archive-123e4567-e89b-42d3-8456-426614174000 title: Archive Id description: The ID of the archive in the format 'archive-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ArchiveUpdateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Archive' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Archives summary: Delete Archive description: Delete an archive by its ID. operationId: delete_archive parameters: - name: archive_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^archive-[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 archive in the format 'archive-' examples: - archive-123e4567-e89b-42d3-8456-426614174000 title: Archive Id description: The ID of the archive in the format 'archive-' responses: '204': description: Successful Response '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/archives/{archive_id}/agents: get: tags: - Archives summary: List Agents for Archive description: Get a list of agents that have access to an archive with pagination support. operationId: list_agents_for_archive parameters: - name: archive_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^archive-[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 archive in the format 'archive-' examples: - archive-123e4567-e89b-42d3-8456-426614174000 title: Archive Id description: The ID of the archive in the format 'archive-' - 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: 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 Archive '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/archives/{archive_id}/passages: post: tags: - Archives summary: Create Passage in Archive description: 'Create a new passage in an archive. This adds a passage to the archive and creates embeddings for vector storage.' operationId: create_passage_in_archive parameters: - name: archive_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^archive-[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 archive in the format 'archive-' examples: - archive-123e4567-e89b-42d3-8456-426614174000 title: Archive Id description: The ID of the archive in the format 'archive-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PassageCreateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Passage' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/archives/{archive_id}/passages/batch: post: tags: - Archives summary: Create Passages in Archive description: 'Create multiple passages in an archive. This adds passages to the archive and creates embeddings for vector storage.' operationId: create_passages_in_archive parameters: - name: archive_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^archive-[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 archive in the format 'archive-' examples: - archive-123e4567-e89b-42d3-8456-426614174000 title: Archive Id description: The ID of the archive in the format 'archive-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PassageBatchCreateRequest' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Passage' title: Response Create Passages In Archive '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/archives/{archive_id}/passages/{passage_id}: delete: tags: - Archives summary: Delete Passage from Archive description: 'Delete a passage from an archive. This permanently removes the passage from both the database and vector storage (if applicable).' operationId: delete_passage_from_archive parameters: - name: archive_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^archive-[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 archive in the format 'archive-' examples: - archive-123e4567-e89b-42d3-8456-426614174000 title: Archive Id description: The ID of the archive in the format 'archive-' - name: passage_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^passage-[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 passage in the format 'passage-' examples: - passage-123e4567-e89b-42d3-8456-426614174000 title: Passage Id description: The ID of the passage in the format 'passage-' responses: '204': description: Successful Response '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/{tool_id}: delete: tags: - Tools summary: Delete Tool description: Delete a tool by name operationId: delete_tool 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-' examples: - tool-123e4567-e89b-42d3-8456-426614174000 title: Tool Id description: The ID of the tool in the format 'tool-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' get: tags: - Tools summary: Retrieve Tool description: Get a tool by ID operationId: retrieve_tool 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-' examples: - tool-123e4567-e89b-42d3-8456-426614174000 title: Tool Id description: The ID of the tool in the format 'tool-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tool' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Tools summary: Modify Tool description: Update an existing tool operationId: modify_tool 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-' examples: - tool-123e4567-e89b-42d3-8456-426614174000 title: Tool Id description: The ID of the tool in the format 'tool-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ToolUpdate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tool' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/count: get: tags: - Tools summary: Count Tools description: Get a count of all tools available to agents belonging to the org of the user. operationId: count_tools parameters: - name: name in: query required: false schema: anyOf: - type: string - type: 'null' title: Name - name: names in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by specific tool names title: Names description: Filter by specific tool names - name: tool_ids in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by specific tool IDs - accepts repeated params or comma-separated values title: Tool Ids description: Filter by specific tool IDs - accepts repeated params or comma-separated values - name: search in: query required: false schema: anyOf: - type: string - type: 'null' description: Search tool names (case-insensitive partial match) title: Search description: Search tool names (case-insensitive partial match) - name: tool_types in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by tool type(s) - accepts repeated params or comma-separated values title: Tool Types description: Filter by tool type(s) - accepts repeated params or comma-separated values - name: exclude_tool_types in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Tool type(s) to exclude - accepts repeated params or comma-separated values title: Exclude Tool Types description: Tool type(s) to exclude - accepts repeated params or comma-separated values - name: return_only_letta_tools in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Count only tools with tool_type starting with 'letta_' default: false title: Return Only Letta Tools description: Count only tools with tool_type starting with 'letta_' - name: exclude_letta_tools in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Exclude built-in Letta tools from the count default: false title: Exclude Letta Tools description: Exclude built-in Letta tools from the count responses: '200': description: Successful Response content: application/json: schema: type: integer title: Response Count Tools '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/: get: tags: - Tools summary: List Tools description: Get a list of all tools available to agents. operationId: list_tools parameters: - 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: 50 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 - name: name in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by single tool name title: Name description: Filter by single tool name - name: names in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by specific tool names title: Names description: Filter by specific tool names - name: tool_ids in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by specific tool IDs - accepts repeated params or comma-separated values title: Tool Ids description: Filter by specific tool IDs - accepts repeated params or comma-separated values - name: search in: query required: false schema: anyOf: - type: string - type: 'null' description: Search tool names (case-insensitive partial match) title: Search description: Search tool names (case-insensitive partial match) - name: tool_types in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by tool type(s) - accepts repeated params or comma-separated values title: Tool Types description: Filter by tool type(s) - accepts repeated params or comma-separated values - name: exclude_tool_types in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Tool type(s) to exclude - accepts repeated params or comma-separated values title: Exclude Tool Types description: Tool type(s) to exclude - accepts repeated params or comma-separated values - name: return_only_letta_tools in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Return only tools with tool_type starting with 'letta_' default: false title: Return Only Letta Tools description: Return only tools with tool_type starting with 'letta_' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Tool' title: Response List Tools '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Tools summary: Create Tool description: Create a new tool operationId: create_tool parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ToolCreate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tool' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' put: tags: - Tools summary: Upsert Tool description: Create or update a tool operationId: upsert_tool parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ToolCreate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tool' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/search: post: tags: - Tools summary: Search Tools description: 'Search tools using semantic search. Requires tool embedding to be enabled (embed_tools=True). Uses vector search, full-text search, or hybrid mode to find tools matching the query. Returns tools ranked by relevance with their search scores.' operationId: search_tools parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ToolSearchRequest' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/ToolSearchResult' title: Response Search Tools '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/add-base-tools: post: tags: - Tools summary: Upsert Base Tools description: Upsert base tools operationId: add_base_tools parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Tool' title: Response Add Base Tools '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/run: post: tags: - Tools summary: Run Tool from Source description: Attempt to build a tool from source, then run it on the provided arguments operationId: run_tool_from_source parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ToolRunFromSource' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ToolReturnMessage' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/servers: get: tags: - Tools summary: List MCP Servers description: Get a list of all configured MCP servers operationId: list_mcp_servers parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: object additionalProperties: anyOf: - $ref: '#/components/schemas/SSEServerConfig' - $ref: '#/components/schemas/StdioServerConfig' - $ref: '#/components/schemas/StreamableHTTPServerConfig' title: Response List Mcp Servers '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' put: tags: - Tools summary: Add MCP Server to Config description: Add a new MCP server to the Letta MCP server config operationId: add_mcp_server parameters: [] requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/StdioServerConfig' - $ref: '#/components/schemas/SSEServerConfig' - $ref: '#/components/schemas/StreamableHTTPServerConfig' title: Request responses: '200': description: Successful Response content: application/json: schema: type: array items: anyOf: - $ref: '#/components/schemas/StdioServerConfig' - $ref: '#/components/schemas/SSEServerConfig' - $ref: '#/components/schemas/StreamableHTTPServerConfig' title: Response Add Mcp Server '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/servers/{mcp_server_name}/tools: get: tags: - Tools summary: List MCP Tools by Server description: Get a list of all tools for a specific MCP server operationId: list_mcp_tools_by_server parameters: - name: mcp_server_name in: path required: true schema: type: string title: Mcp Server Name responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/MCPTool' title: Response List Mcp Tools By Server '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/servers/{mcp_server_name}/resync: post: tags: - Tools summary: Resync MCP Server Tools description: 'Resync tools for an MCP server by: 1. Fetching current tools from the MCP server 2. Deleting tools that no longer exist on the server 3. Updating schemas for existing tools 4. Adding new tools from the server Returns a summary of changes made.' operationId: resync_mcp_server_tools parameters: - name: mcp_server_name in: path required: true schema: type: string title: Mcp Server Name - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Agent Id responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/servers/{mcp_server_name}/{mcp_tool_name}: post: tags: - Tools summary: Add MCP Tool description: Register a new MCP tool as a Letta server by MCP server + tool name operationId: add_mcp_tool parameters: - name: mcp_server_name in: path required: true schema: type: string title: Mcp Server Name - name: mcp_tool_name in: path required: true schema: type: string title: Mcp Tool Name responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tool' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/servers/{mcp_server_name}: patch: tags: - Tools summary: Update MCP Server description: Update an existing MCP server configuration operationId: update_mcp_server parameters: - name: mcp_server_name in: path required: true schema: type: string title: Mcp Server Name requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/letta__schemas__mcp__UpdateStdioMCPServer' - $ref: '#/components/schemas/letta__schemas__mcp__UpdateSSEMCPServer' - $ref: '#/components/schemas/letta__schemas__mcp__UpdateStreamableHTTPMCPServer' title: Request responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/StdioServerConfig' - $ref: '#/components/schemas/SSEServerConfig' - $ref: '#/components/schemas/StreamableHTTPServerConfig' title: Response Update Mcp Server '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Tools summary: Delete MCP Server from Config description: Delete a MCP server configuration operationId: delete_mcp_server parameters: - name: mcp_server_name in: path required: true schema: type: string title: Mcp Server Name responses: '200': description: Successful Response content: application/json: schema: type: array items: anyOf: - $ref: '#/components/schemas/StdioServerConfig' - $ref: '#/components/schemas/SSEServerConfig' - $ref: '#/components/schemas/StreamableHTTPServerConfig' title: Response Delete Mcp Server '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/servers/test: post: tags: - Tools summary: Test MCP Server description: 'Test connection to an MCP server without adding it. Returns the list of available tools if successful.' operationId: test_mcp_server parameters: [] requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/StdioServerConfig' - $ref: '#/components/schemas/SSEServerConfig' - $ref: '#/components/schemas/StreamableHTTPServerConfig' title: Request responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/servers/connect: post: tags: - Tools summary: Connect MCP Server description: 'Connect to an MCP server with support for OAuth via SSE. Returns a stream of events handling authorization state and exchange if OAuth is required.' operationId: connect_mcp_server parameters: [] requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/StdioServerConfig' - $ref: '#/components/schemas/SSEServerConfig' - $ref: '#/components/schemas/StreamableHTTPServerConfig' title: Request responses: '200': description: Successful response content: application/json: schema: {} text/event-stream: description: Server-Sent Events stream '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/servers/{mcp_server_name}/tools/{tool_name}/execute: post: tags: - Tools summary: Execute MCP Tool description: 'Execute a specific MCP tool from a configured server. Returns the tool execution result.' operationId: execute_mcp_tool parameters: - name: mcp_server_name in: path required: true schema: type: string title: Mcp Server Name - name: tool_name in: path required: true schema: type: string title: Tool Name requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/letta__server__rest_api__routers__v1__tools__ToolExecuteRequest' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tools/mcp/oauth/callback: get: tags: - Tools summary: MCP Oauth Callback description: 'Handle OAuth callback for MCP server authentication. Session is identified via the state parameter instead of URL path.' operationId: mcp_oauth_callback parameters: - name: code in: query required: false schema: anyOf: - type: string - type: 'null' description: OAuth authorization code title: Code description: OAuth authorization code - name: state in: query required: false schema: anyOf: - type: string - type: 'null' description: OAuth state parameter title: State description: OAuth state parameter - name: error in: query required: false schema: anyOf: - type: string - type: 'null' description: OAuth error title: Error description: OAuth error - name: error_description in: query required: false schema: anyOf: - type: string - type: 'null' description: OAuth error description title: Error Description description: OAuth error description responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/count: get: tags: - Sources summary: Count Sources description: Count all data sources created by a user. operationId: count_sources deprecated: true parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: integer title: Response Count Sources '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/{source_id}: get: tags: - Sources summary: Retrieve Source description: Get all sources operationId: retrieve_source deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Source' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Sources summary: Modify Source description: Update the name or documentation of an existing data source. operationId: modify_source deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SourceUpdate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Source' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Sources summary: Delete Source description: Delete a data source. operationId: delete_source deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/name/{source_name}: get: tags: - Sources summary: Get Source ID by Name description: Get a source by name operationId: get_source_id_by_name deprecated: true parameters: - name: source_name in: path required: true schema: type: string title: Source Name responses: '200': description: Successful Response content: application/json: schema: type: string title: Response Get Source Id By Name '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/metadata: get: tags: - Sources summary: Get Sources Metadata description: 'Get aggregated metadata for all sources in an organization. Returns structured metadata including: - Total number of sources - Total number of files across all sources - Total size of all files - Per-source breakdown with file details (file_name, file_size per file) if include_detailed_per_source_metadata is True' operationId: get_sources_metadata deprecated: true parameters: - name: include_detailed_per_source_metadata in: query required: false schema: type: boolean default: false title: Include Detailed Per Source Metadata responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OrganizationSourcesStats' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/: get: tags: - Sources summary: List Sources description: List all data sources created by a user. operationId: list_sources deprecated: true parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Source' title: Response List Sources '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Sources summary: Create Source description: Create a new data source. operationId: create_source deprecated: true parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SourceCreate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Source' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/{source_id}/upload: post: tags: - Sources summary: Upload File to Source description: Upload a file to a data source. operationId: upload_file_to_source deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' - name: duplicate_handling in: query required: false schema: $ref: '#/components/schemas/DuplicateFileHandling' description: How to handle duplicate filenames default: suffix description: How to handle duplicate filenames - name: name in: query required: false schema: anyOf: - type: string - type: 'null' description: Optional custom name to override the uploaded file's name title: Name description: Optional custom name to override the uploaded file's name requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/Body_upload_file_to_source' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FileMetadata' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/{source_id}/agents: get: tags: - Sources summary: Get Agents for Source description: Get all agent IDs that have the specified source attached. operationId: get_agents_for_source deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' responses: '200': description: Successful Response content: application/json: schema: type: array items: type: string title: Response Get Agents For Source '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/{source_id}/passages: get: tags: - Sources summary: List Source Passages description: List all passages associated with a data source. operationId: list_source_passages deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message after which to retrieve the returned messages. title: After description: Message after which to retrieve the returned messages. - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message before which to retrieve the returned messages. title: Before description: Message before which to retrieve the returned messages. - name: limit in: query required: false schema: type: integer description: Maximum number of messages to retrieve. default: 100 title: Limit description: Maximum number of messages to retrieve. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Passage' title: Response List Source Passages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/{source_id}/files: get: tags: - Sources summary: List Source Files description: List paginated files associated with a data source. operationId: list_source_files deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' - name: limit in: query required: false schema: type: integer description: Number of files to return default: 1000 title: Limit description: Number of files to return - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Pagination cursor to fetch the next set of results title: After description: Pagination cursor to fetch the next set of results - name: include_content in: query required: false schema: type: boolean description: Whether to include full file content default: false title: Include Content description: Whether to include full file content - name: check_status_updates in: query required: false schema: type: boolean description: Whether to check and update file processing status (from the vector db service). If False, will not fetch and update the status, which may lead to performance gains. default: true title: Check Status Updates description: Whether to check and update file processing status (from the vector db service). If False, will not fetch and update the status, which may lead to performance gains. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/FileMetadata' title: Response List Source Files '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/{source_id}/files/{file_id}: get: tags: - Sources summary: Get File Metadata description: Retrieve metadata for a specific file by its ID. operationId: get_file_metadata deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' - name: file_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^file-[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 file in the format 'file-' examples: - file-123e4567-e89b-42d3-8456-426614174000 title: File Id description: The ID of the file in the format 'file-' - name: include_content in: query required: false schema: type: boolean description: Whether to include full file content default: false title: Include Content description: Whether to include full file content responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FileMetadata' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/sources/{source_id}/{file_id}: delete: tags: - Sources summary: Delete File from Source description: Delete a data source. operationId: delete_file_from_source deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' - name: file_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^file-[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 file in the format 'file-' examples: - file-123e4567-e89b-42d3-8456-426614174000 title: File Id description: The ID of the file in the format 'file-' responses: '204': description: Successful Response '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/count: get: tags: - Folders summary: Count Folders description: Count all data folders created by a user. operationId: count_folders parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: integer title: Response Count Folders '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/{folder_id}: get: tags: - Folders summary: Retrieve Folder description: Get a folder by ID operationId: retrieve_folder parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Folder' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Folders summary: Modify Folder description: Update the name or documentation of an existing data folder. operationId: modify_folder parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SourceUpdate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Folder' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Folders summary: Delete Folder description: Delete a data folder. operationId: delete_folder parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/name/{folder_name}: get: tags: - Folders summary: Get Folder by Name description: '**Deprecated**: Please use the list endpoint `GET /v1/folders?name=` instead. Get a folder by name.' operationId: get_folder_by_name deprecated: true parameters: - name: folder_name in: path required: true schema: type: string title: Folder Name responses: '200': description: Successful Response content: application/json: schema: type: string title: Response Get Folder By Name '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/metadata: get: tags: - Folders summary: Retrieve Metadata description: 'Get aggregated metadata for all folders in an organization. Returns structured metadata including: - Total number of folders - Total number of files across all folders - Total size of all files - Per-source breakdown with file details (file_name, file_size per file) if include_detailed_per_source_metadata is True' operationId: retrieve_metadata parameters: - name: include_detailed_per_source_metadata in: query required: false schema: type: boolean default: false title: Include Detailed Per Source Metadata responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OrganizationSourcesStats' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/: get: tags: - Folders summary: List Folders description: List all data folders created by a user. operationId: list_folders parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Folder ID cursor for pagination. Returns folders that come before this folder ID in the specified sort order title: Before description: Folder ID cursor for pagination. Returns folders that come before this folder ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Folder ID cursor for pagination. Returns folders that come after this folder ID in the specified sort order title: After description: Folder ID cursor for pagination. Returns folders that come after this folder ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of folders to return default: 50 title: Limit description: Maximum number of folders to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for folders by creation time. 'asc' for oldest first, 'desc' for newest first default: asc title: Order description: Sort order for folders 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: name in: query required: false schema: anyOf: - type: string - type: 'null' description: Folder name to filter by title: Name description: Folder name to filter by responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Folder' title: Response List Folders '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Folders summary: Create Folder description: Create a new data folder. operationId: create_folder parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SourceCreate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Folder' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/{folder_id}/upload: post: tags: - Folders summary: Upload File to Folder description: Upload a file to a data folder. operationId: upload_file_to_folder parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' - name: duplicate_handling in: query required: false schema: $ref: '#/components/schemas/DuplicateFileHandling' description: How to handle duplicate filenames default: suffix description: How to handle duplicate filenames - name: name in: query required: false schema: anyOf: - type: string - type: 'null' description: Optional custom name to override the uploaded file's name title: Name description: Optional custom name to override the uploaded file's name requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/Body_upload_file_to_folder' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FileMetadata' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/{folder_id}/agents: get: tags: - Folders summary: List Agents for Folder description: Get all agent IDs that have the specified folder attached. operationId: list_agents_for_folder parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' - 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 responses: '200': description: Successful Response content: application/json: schema: type: array items: type: string title: Response List Agents For Folder '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/{folder_id}/passages: get: tags: - Folders summary: List Folder Passages description: List all passages associated with a data folder. operationId: list_folder_passages parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Passage ID cursor for pagination. Returns passages that come before this passage ID in the specified sort order title: Before description: Passage ID cursor for pagination. Returns passages that come before this passage ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Passage ID cursor for pagination. Returns passages that come after this passage ID in the specified sort order title: After description: Passage ID cursor for pagination. Returns passages that come after this passage ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of passages to return default: 100 title: Limit description: Maximum number of passages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for passages by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for passages 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/Passage' title: Response List Folder Passages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/{folder_id}/files: get: tags: - Folders summary: List Files for Folder description: List paginated files associated with a data folder. operationId: list_files_for_folder parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: File ID cursor for pagination. Returns files that come before this file ID in the specified sort order title: Before description: File ID cursor for pagination. Returns files that come before this file ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: File ID cursor for pagination. Returns files that come after this file ID in the specified sort order title: After description: File ID cursor for pagination. Returns files that come after this file ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of files to return default: 1000 title: Limit description: Maximum number of files to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for files 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_content in: query required: false schema: type: boolean description: Whether to include full file content default: false title: Include Content description: Whether to include full file content responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/FileMetadata' title: Response List Files For Folder '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/{folder_id}/files/{file_id}: get: tags: - Folders summary: Retrieve File description: Retrieve a file from a folder by ID. operationId: retrieve_file parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' - name: file_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^file-[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 file in the format 'file-' examples: - file-123e4567-e89b-42d3-8456-426614174000 title: File Id description: The ID of the file in the format 'file-' - name: include_content in: query required: false schema: type: boolean description: Whether to include full file content default: false title: Include Content description: Whether to include full file content responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FileMetadata' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/folders/{folder_id}/{file_id}: delete: tags: - Folders summary: Delete File from Folder description: Delete a file from a folder. operationId: delete_file_from_folder parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' - name: file_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^file-[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 file in the format 'file-' examples: - file-123e4567-e89b-42d3-8456-426614174000 title: File Id description: The ID of the file in the format 'file-' responses: '204': description: Successful Response '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - 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-' examples: - tool-123e4567-e89b-42d3-8456-426614174000 title: Tool Id description: The ID of the tool in the format 'tool-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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-' examples: - tool-123e4567-e89b-42d3-8456-426614174000 title: Tool Id description: The ID of the tool in the format 'tool-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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 required: true schema: type: string title: Tool Name - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: requires_approval in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Whether the tool requires approval before execution deprecated: true title: Requires Approval description: Whether the tool requires approval before execution deprecated: true requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/ModifyApprovalRequest' - type: 'null' title: Request responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/AgentState' - type: 'null' title: Response Modify Approval For Tool '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/tools/{tool_name}/run: post: tags: - Agents summary: Run Tool for Agent description: 'Trigger a tool by name on a specific agent, providing the necessary arguments. This endpoint executes a tool that is attached to the agent, using the agent''s state and environment variables for execution context.' operationId: run_tool_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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: tool_name in: path required: true schema: type: string title: Tool Name requestBody: content: application/json: schema: $ref: '#/components/schemas/letta__schemas__mcp_server__ToolExecuteRequest' default: args: {} responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ToolExecutionResult' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/sources/attach/{source_id}: patch: tags: - Agents summary: Attach Source description: Attach a source to an agent. operationId: attach_source_to_agent deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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/{agent_id}/folders/attach/{folder_id}: patch: tags: - Agents summary: Attach Folder to Agent description: Attach a folder to an agent. operationId: attach_folder_to_agent parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/AgentState' - type: 'null' title: Response Attach Folder To Agent '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/sources/detach/{source_id}: patch: tags: - Agents summary: Detach Source description: Detach a source from an agent. operationId: detach_source_from_agent deprecated: true parameters: - name: source_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Source Id description: The ID of the source in the format 'source-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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/{agent_id}/folders/detach/{folder_id}: patch: tags: - Agents summary: Detach Folder from Agent description: Detach a folder from an agent. operationId: detach_folder_from_agent parameters: - name: folder_id in: path required: true schema: type: string minLength: 43 maxLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 title: Folder Id description: The ID of the source in the format 'source-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/AgentState' - type: 'null' title: Response Detach Folder From Agent '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/files/close-all: patch: tags: - Agents summary: Close All Files for Agent description: 'Closes all currently open files for a given agent. This endpoint updates the file state for the agent so that no files are marked as open. Typically used to reset the working memory view for the agent.' operationId: close_all_files_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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' responses: '200': description: Successful Response content: application/json: schema: type: array items: type: string title: Response Close All Files For Agent '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/files/{file_id}/open: patch: tags: - Agents summary: Open File for Agent description: 'Opens a specific file for a given agent. This endpoint marks a specific file as open in the agent''s file state. The file will be included in the agent''s working memory view. Returns a list of file names that were closed due to LRU eviction.' operationId: open_file_for_agent parameters: - name: file_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^file-[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 file in the format 'file-' examples: - file-123e4567-e89b-42d3-8456-426614174000 title: File Id description: The ID of the file in the format 'file-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' responses: '200': description: Successful Response content: application/json: schema: type: array items: type: string title: Response Open File For Agent '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/files/{file_id}/close: patch: tags: - Agents summary: Close File for Agent description: 'Closes a specific file for a given agent. This endpoint marks a specific file as closed in the agent''s file state. The file will be removed from the agent''s working memory view.' operationId: close_file_for_agent parameters: - name: file_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^file-[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 file in the format 'file-' examples: - file-123e4567-e89b-42d3-8456-426614174000 title: File Id description: The ID of the file in the format 'file-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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}/sources: get: tags: - Agents summary: List Agent Sources description: Get the sources associated with an agent. operationId: list_agent_sources 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Source ID cursor for pagination. Returns sources that come before this source ID in the specified sort order title: Before description: Source ID cursor for pagination. Returns sources that come before this source ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Source ID cursor for pagination. Returns sources that come after this source ID in the specified sort order title: After description: Source ID cursor for pagination. Returns sources that come after this source ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of sources to return default: 100 title: Limit description: Maximum number of sources to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for sources by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for sources 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/Source' title: Response List Agent Sources '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/folders: get: tags: - Agents summary: List Folders for Agent description: Get the folders associated with an agent. operationId: list_folders_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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Source ID cursor for pagination. Returns sources that come before this source ID in the specified sort order title: Before description: Source ID cursor for pagination. Returns sources that come before this source ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Source ID cursor for pagination. Returns sources that come after this source ID in the specified sort order title: After description: Source ID cursor for pagination. Returns sources that come after this source ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of sources to return default: 100 title: Limit description: Maximum number of sources to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for sources by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for sources 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/Source' title: Response List Folders For Agent '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/files: get: tags: - Agents summary: List Files for Agent description: Get the files attached to an agent with their open/closed status. operationId: list_files_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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: File ID cursor for pagination. Returns files that come before this file ID in the specified sort order title: Before description: File ID cursor for pagination. Returns files that come before this file ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: File ID cursor for pagination. Returns files that come after this file ID in the specified sort order title: After description: File ID cursor for pagination. Returns files that come after this file ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of files to return default: 100 title: Limit description: Maximum number of files to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for files 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: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Pagination cursor from previous response (deprecated, use before/after) deprecated: true title: Cursor description: Pagination cursor from previous response (deprecated, use before/after) deprecated: true - name: is_open in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Filter by open status (true for open files, false for closed files) title: Is Open description: Filter by open status (true for open files, false for closed files) responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaginatedAgentFiles' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/core-memory: get: tags: - Agents summary: Retrieve Agent Memory description: 'Retrieve the memory state of a specific agent. This endpoint fetches the current memory state of the agent identified by the user ID and agent ID.' operationId: retrieve_agent_memory 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Memory' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/core-memory/blocks/{block_label}: get: tags: - Agents summary: Retrieve Block for Agent description: Retrieve a core memory block from an agent. operationId: retrieve_core_memory_block parameters: - name: block_label in: path required: true schema: type: string title: Block Label - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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' patch: tags: - Agents summary: Modify Block for Agent description: Updates a core memory block of an agent. operationId: modify_core_memory_block parameters: - name: block_label in: path required: true schema: type: string title: Block Label - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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' /v1/agents/{agent_id}/core-memory/blocks: get: tags: - Agents summary: List Blocks for Agent description: Retrieve the core memory blocks of a specific agent. operationId: list_core_memory_blocks 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - 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: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of blocks to return default: 100 title: Limit description: Maximum number of blocks to return - 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: desc 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 responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/BlockResponse' title: Response List Core Memory Blocks '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/recompile: post: tags: - Agents summary: Recompile Agent description: Manually trigger system prompt recompilation for an agent. operationId: recompile_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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: update_timestamp in: query required: false schema: type: boolean description: If True, update the in-context memory last edit timestamp embedded in the system prompt. default: false title: Update Timestamp description: If True, update the in-context memory last edit timestamp embedded in the system prompt. - name: dry_run in: query required: false schema: type: boolean description: If True, do not persist changes; still returns the compiled system prompt. default: false title: Dry Run description: If True, do not persist changes; still returns the compiled system prompt. responses: '200': description: Successful Response content: application/json: schema: type: string title: Response Recompile Agent '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/system-prompt/recompile: post: tags: - Agents summary: Recompile Agent System Prompt description: Deprecated alias for POST /v1/agents/{agent_id}/recompile. operationId: recompile_agent_system_prompt 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: update_timestamp in: query required: false schema: type: boolean description: If True, update the in-context memory last edit timestamp embedded in the system prompt. default: false title: Update Timestamp description: If True, update the in-context memory last edit timestamp embedded in the system prompt. - name: dry_run in: query required: false schema: type: boolean description: If True, do not persist changes; still returns the compiled system prompt. default: false title: Dry Run description: If True, do not persist changes; still returns the compiled system prompt. responses: '200': description: Successful Response content: application/json: schema: type: string title: Response Recompile Agent System Prompt '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/core-memory/blocks/attach/{block_id}: patch: tags: - Agents summary: Attach Block to Agent description: Attach a core memory block to an agent. operationId: attach_core_memory_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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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/{agent_id}/core-memory/blocks/detach/{block_id}: patch: tags: - Agents summary: Detach Block from Agent description: Detach a core memory block from an agent. operationId: detach_core_memory_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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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/{agent_id}/archives/attach/{archive_id}: patch: tags: - Agents summary: Attach Archive to Agent description: Attach an archive to an agent. operationId: attach_archive_to_agent parameters: - name: archive_id in: path required: true schema: type: string title: Archive Id - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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}/archives/detach/{archive_id}: patch: tags: - Agents summary: Detach Archive from Agent description: Detach an archive from an agent. operationId: detach_archive_from_agent parameters: - name: archive_id in: path required: true schema: type: string title: Archive Id - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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}/identities/attach/{identity_id}: patch: tags: - Agents summary: Attach Identity to Agent description: Attach an identity to an agent. operationId: attach_identity_to_agent parameters: - name: identity_id in: path required: true schema: type: string title: Identity Id - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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}/identities/detach/{identity_id}: patch: tags: - Agents summary: Detach Identity from Agent description: Detach an identity from an agent. operationId: detach_identity_from_agent parameters: - name: identity_id in: path required: true schema: type: string title: Identity Id - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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}/archival-memory: get: tags: - Agents summary: List Passages description: Retrieve the memories in an agent's archival memory store (paginated query). operationId: list_passages 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Unique ID of the memory to start the query range at. title: After description: Unique ID of the memory to start the query range at. - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Unique ID of the memory to end the query range at. title: Before description: Unique ID of the memory to end the query range at. - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: How many results to include in the response. default: 100 title: Limit description: How many results to include in the response. - name: search in: query required: false schema: anyOf: - type: string - type: 'null' description: Search passages by text title: Search description: Search passages by text - name: ascending in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Whether to sort passages oldest to newest (True, default) or newest to oldest (False) default: true title: Ascending description: Whether to sort passages oldest to newest (True, default) or newest to oldest (False) responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Passage' title: Response List Passages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Agents summary: Create Passage description: Insert a memory into an agent's archival memory store. operationId: create_passage 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateArchivalMemory' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Passage' title: Response Create Passage '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/archival-memory/search: get: tags: - Agents summary: Search Archival Memory description: 'Search archival memory using semantic (embedding-based) search with optional temporal filtering. This endpoint allows manual triggering of archival memory searches, enabling users to query an agent''s archival memory store directly via the API. The search uses the same functionality as the agent''s archival_memory_search tool but is accessible for external API usage.' operationId: search_archival_memory 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: query in: query required: true schema: type: string description: String to search for using semantic similarity title: Query description: String to search for using semantic similarity - name: tags in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Optional list of tags to filter search results title: Tags description: Optional list of tags to filter search results - name: tag_match_mode in: query required: false schema: enum: - any - all type: string description: How to match tags - 'any' to match passages with any of the tags, 'all' to match only passages with all tags default: any title: Tag Match Mode description: How to match tags - 'any' to match passages with any of the tags, 'all' to match only passages with all tags - name: top_k in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of results to return. Uses system default if not specified title: Top K description: Maximum number of results to return. Uses system default if not specified - name: start_datetime in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Filter results to passages created after this datetime title: Start Datetime description: Filter results to passages created after this datetime - name: end_datetime in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Filter results to passages created before this datetime title: End Datetime description: Filter results to passages created before this datetime responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ArchivalMemorySearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/archival-memory/{memory_id}: delete: tags: - Agents summary: Delete Passage description: Delete a memory from an agent's archival memory store. operationId: delete_passage parameters: - name: memory_id in: path required: true schema: type: string title: Memory Id - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' 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}/messages: get: tags: - Agents summary: List Messages description: Retrieve message history for an agent. operationId: list_messages 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for messages 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: group_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Group ID to filter messages by. title: Group Id description: Group ID to filter messages by. - name: conversation_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Conversation ID to filter messages by. title: Conversation Id description: Conversation ID to filter messages by. - name: use_assistant_message in: query required: false schema: type: boolean description: Whether to use assistant messages deprecated: true default: true title: Use Assistant Message description: Whether to use assistant messages deprecated: true - name: assistant_message_tool_name in: query required: false schema: type: string description: The name of the designated message tool. deprecated: true default: send_message title: Assistant Message Tool Name description: The name of the designated message tool. deprecated: true - name: assistant_message_tool_kwarg in: query required: false schema: type: string description: The name of the message argument. deprecated: true default: message title: Assistant Message Tool Kwarg description: The name of the message argument. deprecated: true - name: include_err in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Whether to include error messages and error statuses. For debugging purposes only. title: Include Err description: Whether to include error messages and error statuses. For debugging purposes only. - name: include_return_message_types in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/MessageType' - type: 'null' description: Message types to include in response. When null, all message types are returned. title: Include Return Message Types description: Message types to include in response. When null, all message types are returned. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/LettaMessageUnion' title: Response List Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Agents summary: Send Message description: 'Process a user message and return the agent''s response. This endpoint accepts a message from a user and processes it through the agent. **Note:** Sending multiple concurrent requests to the same agent can lead to undefined behavior. Each agent processes messages sequentially, and concurrent requests may interleave in unexpected ways. Wait for each request to complete before sending the next one. Use separate agents or conversations for parallel processing. The response format is controlled by the `streaming` field in the request body: - If `streaming=false` (default): Returns a complete LettaResponse with all messages - If `streaming=true`: Returns a Server-Sent Events (SSE) stream Additional streaming options (only used when streaming=true): - `stream_tokens`: Stream individual tokens instead of complete steps - `include_pings`: Include keepalive pings to prevent connection timeouts - `background`: Process the request in the background' operationId: send_message 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LettaStreamingRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/LettaResponse' text/event-stream: description: Server-Sent Events stream (when streaming=true in request body) '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/messages/{message_id}: patch: tags: - Agents summary: Modify Message description: 'Update the details of a message associated with an agent. **Deprecated**: Messages are now considered immutable since they can be shared across multiple conversations via forking. This endpoint will be removed in a future version.' operationId: modify_message 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: message_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^message-[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 message in the format 'message-' examples: - message-123e4567-e89b-42d3-8456-426614174000 title: Message Id description: The ID of the message in the format 'message-' requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/UpdateSystemMessage' - $ref: '#/components/schemas/UpdateUserMessage' - $ref: '#/components/schemas/UpdateReasoningMessage' - $ref: '#/components/schemas/UpdateAssistantMessage' title: Request responses: '200': description: Successful Response content: application/json: schema: oneOf: - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ReasoningMessage' - $ref: '#/components/schemas/HiddenReasoningMessage' - $ref: '#/components/schemas/ToolCallMessage' - $ref: '#/components/schemas/ToolReturnMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ApprovalRequestMessage' - $ref: '#/components/schemas/ApprovalResponseMessage' - $ref: '#/components/schemas/SummaryMessage' - $ref: '#/components/schemas/EventMessage' discriminator: propertyName: message_type mapping: system_message: '#/components/schemas/SystemMessage' user_message: '#/components/schemas/UserMessage' reasoning_message: '#/components/schemas/ReasoningMessage' hidden_reasoning_message: '#/components/schemas/HiddenReasoningMessage' tool_call_message: '#/components/schemas/ToolCallMessage' tool_return_message: '#/components/schemas/ToolReturnMessage' assistant_message: '#/components/schemas/AssistantMessage' approval_request_message: '#/components/schemas/ApprovalRequestMessage' approval_response_message: '#/components/schemas/ApprovalResponseMessage' summary_message: '#/components/schemas/SummaryMessage' event_message: '#/components/schemas/EventMessage' title: Response Modify Message '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/messages/stream: post: tags: - Agents summary: Send Message Streaming description: 'Process a user message and return the agent''s response. Deprecated: Use the `POST /{agent_id}/messages` endpoint with `streaming=true` in the request body instead. **Note:** Sending multiple concurrent requests to the same agent can lead to undefined behavior. Each agent processes messages sequentially, and concurrent requests may interleave in unexpected ways. Wait for each request to complete before sending the next one. Use separate agents or conversations for parallel processing. This endpoint accepts a message from a user and processes it through the agent. It will stream the steps of the response always, and stream the tokens if ''stream_tokens'' is set to True.' operationId: create_agent_message_stream 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LettaStreamingRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/LettaStreamingResponse' text/event-stream: description: Server-Sent Events stream '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/messages/cancel: post: tags: - Agents summary: Cancel Message description: 'Cancel runs associated with an agent. If run_ids are passed in, cancel those in particular. Note to cancel active runs associated with an agent, redis is required.' operationId: cancel_message 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: content: application/json: schema: $ref: '#/components/schemas/CancelAgentRunRequest' responses: '200': description: Successful Response content: application/json: schema: type: object additionalProperties: true title: Response Cancel Message '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/generate: post: tags: - Agents summary: Generate Completion description: 'Generate a completion directly from the LLM provider using the agent''s configuration. This endpoint makes a direct request to the LLM provider without any agent processing: - No memory or context retrieval - No tool calling - No message persistence - No agent state modification Simply provide a prompt, and the endpoint formats it as a user message. Optionally include a system_prompt for context/instructions. The agent''s LLM configuration (model, credentials, settings) is used by default. Use override_model to switch to a different model/provider while still using the organization''s configured providers. Example use cases: - Quick LLM queries without agent overhead - Testing different models with the same prompt - Simple chat completions using agent''s credentials - Comparing model outputs on identical prompts' operationId: generate_completion 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GenerateRequest' responses: '200': description: Successful generation content: application/json: schema: $ref: '#/components/schemas/GenerateResponse' '404': description: Agent not found '422': description: Invalid request parameters '502': description: LLM provider error /v1/agents/messages/search: post: tags: - Agents summary: Search Messages description: 'Search messages across the entire organization with optional project and template filtering. Returns messages with FTS/vector ranks and total RRF score. This is a cloud-only feature.' operationId: search_messages parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MessageSearchRequest' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/MessageSearchResult' title: Response Search Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/messages/async: post: tags: - Agents summary: Send Message Async description: 'Asynchronously process a user message and return a run object. The actual processing happens in the background, and the status can be checked using the run ID. This is "asynchronous" in the sense that it''s a background run and explicitly must be fetched by the run ID. **Note:** Sending multiple concurrent requests to the same agent can lead to undefined behavior. Each agent processes messages sequentially, and concurrent requests may interleave in unexpected ways. Wait for each request to complete before sending the next one. Use separate agents or conversations for parallel processing.' operationId: create_agent_message_async 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LettaAsyncRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Run' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/reset-messages: patch: tags: - Agents summary: Reset Messages description: Resets the messages for an agent operationId: reset_messages 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResetMessagesRequest' responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/AgentState' - type: 'null' title: Response Reset Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/groups: get: tags: - Agents summary: List Groups for Agent description: Lists the groups for an agent. operationId: list_groups_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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' - name: manager_type in: query required: false schema: anyOf: - type: string - type: 'null' description: Manager type to filter groups by title: Manager Type description: Manager type to filter groups by - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Group ID cursor for pagination. Returns groups that come before this group ID in the specified sort order title: Before description: Group ID cursor for pagination. Returns groups that come before this group ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Group ID cursor for pagination. Returns groups that come after this group ID in the specified sort order title: After description: Group ID cursor for pagination. Returns groups that come after this group ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of groups to return default: 100 title: Limit description: Maximum number of groups to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for groups by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for groups 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/Group' title: Response List Groups For Agent '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/messages/preview-raw-payload: post: tags: - Agents summary: Preview Model Request description: 'Inspect the raw LLM request payload without sending it. This endpoint processes the message through the agent loop up until the LLM request, then returns the raw request payload that would be sent to the LLM provider. Useful for debugging and inspection.' operationId: preview_model_request 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/LettaRequest' - $ref: '#/components/schemas/LettaStreamingRequest' title: Request responses: '200': description: Successful Response content: application/json: schema: type: object additionalProperties: true title: Response Preview Model Request '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/summarize: post: tags: - Agents summary: Summarize Messages description: Summarize an agent's conversation history. operationId: summarize_messages 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/letta__server__rest_api__routers__v1__agents__CompactionRequest' - type: 'null' title: Request responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CompactionResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/: post: tags: - Conversations summary: Create Conversation description: Create a new conversation for an agent. operationId: create_conversation parameters: - name: agent_id in: query required: true schema: type: string description: The agent ID to create a conversation for title: Agent Id description: The agent ID to create a conversation for requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateConversation' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Conversation' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' get: tags: - Conversations summary: List Conversations description: List all conversations for an agent (or all conversations if agent_id not provided). operationId: list_conversations parameters: - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The agent ID to list conversations for (optional - returns all conversations if not provided) title: Agent Id description: The agent ID to list conversations for (optional - returns all conversations if not provided) - name: limit in: query required: false schema: type: integer description: Maximum number of conversations to return default: 50 title: Limit description: Maximum number of conversations to return - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination (conversation ID) title: After description: Cursor for pagination (conversation ID) - name: summary_search in: query required: false schema: anyOf: - type: string - type: 'null' description: Search for text within conversation summaries title: Summary Search description: Search for text within conversation summaries - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for conversations. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for conversations. 'asc' for oldest first, 'desc' for newest first - name: order_by in: query required: false schema: enum: - created_at - last_run_completion - last_message_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/Conversation' title: Response List Conversations '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/{conversation_id}: get: tags: - Conversations summary: Retrieve Conversation description: Retrieve a specific conversation. operationId: retrieve_conversation parameters: - name: conversation_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^conv-[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 conv in the format 'conv-' examples: - conv-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The ID of the conv in the format 'conv-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Conversation' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Conversations summary: Update Conversation description: Update a conversation. operationId: update_conversation parameters: - name: conversation_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^conv-[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 conv in the format 'conv-' examples: - conv-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The ID of the conv in the format 'conv-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateConversation' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Conversation' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Conversations summary: Delete Conversation description: 'Delete a conversation (soft delete). This marks the conversation as deleted but does not permanently remove it from the database. The conversation will no longer appear in list operations. Any isolated blocks associated with the conversation will be permanently deleted.' operationId: delete_conversation parameters: - name: conversation_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^conv-[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 conv in the format 'conv-' examples: - conv-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The ID of the conv in the format 'conv-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/{conversation_id}/fork: post: tags: - Conversations summary: Fork Conversation description: 'Fork an existing conversation. Creates a new conversation that shares the same in-context messages as the source conversation, but with a newly compiled system message reflecting the latest memory block values. The forked conversation belongs to the same agent as the source. **Agent-direct mode**: Pass conversation_id="default" with agent_id query parameter to fork the agent''s default (agent-direct) message history into a new conversation. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed.' operationId: fork_conversation parameters: - name: conversation_id in: path required: true schema: type: string minLength: 1 maxLength: 42 pattern: ^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|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 conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). examples: - default - conv-123e4567-e89b-42d3-8456-426614174000 - agent-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Agent ID for agent-direct mode with 'default' conversation title: Agent Id description: Agent ID for agent-direct mode with 'default' conversation responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Conversation' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/{conversation_id}/messages: get: tags: - Conversations summary: List Conversation Messages description: 'List all messages in a conversation. Returns LettaMessage objects (UserMessage, AssistantMessage, etc.) for all messages in the conversation, with support for cursor-based pagination. **Agent-direct mode**: Pass conversation_id="default" with agent_id parameter to list messages from the agent''s default conversation. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed.' operationId: list_conversation_messages parameters: - name: conversation_id in: path required: true schema: type: string minLength: 1 maxLength: 42 pattern: ^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|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 conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). examples: - default - conv-123e4567-e89b-42d3-8456-426614174000 - agent-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Agent ID for agent-direct mode with 'default' conversation title: Agent Id description: Agent ID for agent-direct mode with 'default' conversation - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for messages 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: group_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Group ID to filter messages by. title: Group Id description: Group ID to filter messages by. - name: include_err in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Whether to include error messages and error statuses. For debugging purposes only. title: Include Err description: Whether to include error messages and error statuses. For debugging purposes only. - name: include_return_message_types in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/MessageType' - type: 'null' description: Message types to include in response. When null, all message types are returned. title: Include Return Message Types description: Message types to include in response. When null, all message types are returned. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/LettaMessageUnion' title: Response List Conversation Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Conversations summary: Send Conversation Message description: 'Send a message to a conversation and get a response. This endpoint sends a message to an existing conversation. By default (streaming=true), returns a streaming response (Server-Sent Events). Set streaming=false to get a complete JSON response. **Agent-direct mode**: Pass conversation_id="default" with agent_id in request body to send messages to the agent''s default conversation with locking. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed.' operationId: send_conversation_message parameters: - name: conversation_id in: path required: true schema: type: string minLength: 1 maxLength: 42 pattern: ^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|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 conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). examples: - default - conv-123e4567-e89b-42d3-8456-426614174000 - agent-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversationMessageRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/LettaResponse' description: JSON response (when streaming=false) text/event-stream: description: Server-Sent Events stream (default, when streaming=true) '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/{conversation_id}/messages/preview-raw-payload: post: tags: - Conversations summary: Preview Conversation Model Request description: 'Inspect the raw LLM request payload for a conversation message without sending it. This endpoint processes the message through the same path as send_conversation_message (including conversation-scoped messages, isolated blocks, model overrides, and client tools/skills) but stops before the LLM call and returns the raw request payload. Useful for debugging and verifying what the LLM will actually see.' operationId: preview_conversation_model_request parameters: - name: conversation_id in: path required: true schema: type: string minLength: 1 maxLength: 42 pattern: ^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|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 conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). examples: - default - conv-123e4567-e89b-42d3-8456-426614174000 - agent-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversationMessageRequest' responses: '200': description: Successful Response content: application/json: schema: type: object additionalProperties: true title: Response Preview Conversation Model Request '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/{conversation_id}/stream: post: tags: - Conversations summary: Retrieve Conversation Stream description: 'Resume the stream for the most recent active run in a conversation. This endpoint allows you to reconnect to an active background stream for a conversation, enabling recovery from network interruptions. **Agent-direct mode**: Pass conversation_id="default" with agent_id in request body to retrieve the stream for the agent''s most recent active run. **Direct run access**: Pass run_id directly to skip run lookup entirely. Useful for recovery from duplicate request 409 errors. **OTID lookup**: Pass otid to look up the run_id from Redis. Useful when you have the otid from a 409 error response. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed.' operationId: retrieve_conversation_stream parameters: - name: conversation_id in: path required: true schema: type: string minLength: 1 maxLength: 42 pattern: ^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|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 conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). examples: - default - conv-123e4567-e89b-42d3-8456-426614174000 - agent-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). requestBody: content: application/json: schema: $ref: '#/components/schemas/RetrieveStreamRequest' responses: '200': description: Successful response content: application/json: schema: {} text/event-stream: description: Server-Sent Events stream schema: oneOf: - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ReasoningMessage' - $ref: '#/components/schemas/HiddenReasoningMessage' - $ref: '#/components/schemas/ToolCallMessage' - $ref: '#/components/schemas/ToolReturnMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ApprovalRequestMessage' - $ref: '#/components/schemas/ApprovalResponseMessage' - $ref: '#/components/schemas/LettaPing' - $ref: '#/components/schemas/LettaErrorMessage' - $ref: '#/components/schemas/LettaStopReason' - $ref: '#/components/schemas/LettaUsageStatistics' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/{conversation_id}/cancel: post: tags: - Conversations summary: Cancel Conversation description: 'Cancel runs associated with a conversation. Note: To cancel active runs, Redis is required. **Agent-direct mode**: Pass conversation_id="default" with agent_id query parameter to cancel runs for the agent''s default conversation. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed.' operationId: cancel_conversation parameters: - name: conversation_id in: path required: true schema: type: string minLength: 1 maxLength: 42 pattern: ^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|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 conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). examples: - default - conv-123e4567-e89b-42d3-8456-426614174000 - agent-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Agent ID for agent-direct mode with 'default' conversation title: Agent Id description: Agent ID for agent-direct mode with 'default' conversation responses: '200': description: Successful Response content: application/json: schema: type: object additionalProperties: true title: Response Cancel Conversation '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/{conversation_id}/recompile: post: tags: - Conversations summary: Recompile Conversation description: Manually trigger system prompt recompilation for a conversation. operationId: recompile_conversation parameters: - name: conversation_id in: path required: true schema: type: string minLength: 1 maxLength: 42 pattern: ^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|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 conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). examples: - default - conv-123e4567-e89b-42d3-8456-426614174000 - agent-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). - name: dry_run in: query required: false schema: type: boolean description: If True, do not persist changes; still returns the compiled system prompt. default: false title: Dry Run description: If True, do not persist changes; still returns the compiled system prompt. requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/letta__server__rest_api__routers__v1__conversations__CompactionRequest' - type: 'null' title: Request responses: '200': description: Successful Response content: application/json: schema: type: string title: Response Recompile Conversation '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/conversations/{conversation_id}/compact: post: tags: - Conversations summary: Compact Conversation description: 'Compact (summarize) a conversation''s message history. This endpoint summarizes the in-context messages for a specific conversation, reducing the message count while preserving important context. **Agent-direct mode**: Pass conversation_id="default" with agent_id in request body to compact the agent''s default conversation messages. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed.' operationId: compact_conversation parameters: - name: conversation_id in: path required: true schema: type: string minLength: 1 maxLength: 42 pattern: ^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|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 conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). examples: - default - conv-123e4567-e89b-42d3-8456-426614174000 - agent-123e4567-e89b-42d3-8456-426614174000 title: Conversation Id description: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/letta__server__rest_api__routers__v1__conversations__CompactionRequest' - type: 'null' title: Request responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CompactionResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/chat/completions: post: tags: - Chat summary: Create Chat Completion description: 'Create a chat completion using a Letta agent (OpenAI-compatible). This endpoint provides full OpenAI API compatibility. The agent is selected based on: - The ''model'' parameter in the request (should contain an agent ID in format ''agent-...'') When streaming is enabled (stream=true), the response will be Server-Sent Events with ChatCompletionChunk objects.' operationId: create_chat_completion parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ChatCompletion' text/event-stream: description: Server-Sent Events stream (when stream=true) '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/groups/: get: tags: - Groups summary: List Groups description: Fetch all multi-agent groups matching query. operationId: list_groups deprecated: true parameters: - name: manager_type in: query required: false schema: anyOf: - $ref: '#/components/schemas/ManagerType' - type: 'null' description: Search groups by manager type title: Manager Type description: Search groups by manager type - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Group ID cursor for pagination. Returns groups that come before this group ID in the specified sort order title: Before description: Group ID cursor for pagination. Returns groups that come before this group ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Group ID cursor for pagination. Returns groups that come after this group ID in the specified sort order title: After description: Group ID cursor for pagination. Returns groups that come after this group ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of groups to return default: 50 title: Limit description: Maximum number of groups to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for groups by creation time. 'asc' for oldest first, 'desc' for newest first default: asc title: Order description: Sort order for groups 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: project_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Search groups by project id title: Project Id description: Search groups by project id responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Group' title: Response List Groups '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Groups summary: Create Group description: Create a new multi-agent group with the specified configuration. operationId: create_group deprecated: true parameters: - name: X-Project in: header required: false schema: anyOf: - type: string - type: 'null' description: The project slug to associate with the group (cloud only). title: X-Project description: The project slug to associate with the group (cloud only). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupCreate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Group' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/groups/count: get: tags: - Groups summary: Count Groups description: Get the count of all groups associated with a given user. operationId: count_groups deprecated: true parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: integer title: Response Count Groups '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/groups/{group_id}: get: tags: - Groups summary: Retrieve Group description: Retrieve the group by id. operationId: retrieve_group deprecated: true parameters: - name: group_id in: path required: true schema: type: string minLength: 42 maxLength: 42 pattern: ^group-[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 group in the format 'group-' examples: - group-123e4567-e89b-42d3-8456-426614174000 title: Group Id description: The ID of the group in the format 'group-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Group' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Groups summary: Modify Group description: Create a new multi-agent group with the specified configuration. operationId: modify_group deprecated: true parameters: - name: group_id in: path required: true schema: type: string minLength: 42 maxLength: 42 pattern: ^group-[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 group in the format 'group-' examples: - group-123e4567-e89b-42d3-8456-426614174000 title: Group Id description: The ID of the group in the format 'group-' - name: X-Project in: header required: false schema: anyOf: - type: string - type: 'null' description: The project slug to associate with the group (cloud only). title: X-Project description: The project slug to associate with the group (cloud only). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupUpdate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Group' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Groups summary: Delete Group description: Delete a multi-agent group. operationId: delete_group deprecated: true parameters: - name: group_id in: path required: true schema: type: string minLength: 42 maxLength: 42 pattern: ^group-[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 group in the format 'group-' examples: - group-123e4567-e89b-42d3-8456-426614174000 title: Group Id description: The ID of the group in the format 'group-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/groups/{group_id}/messages/{message_id}: patch: tags: - Groups summary: Modify Group Message description: Update the details of a message associated with an agent. operationId: modify_group_message deprecated: true parameters: - name: group_id in: path required: true schema: type: string minLength: 42 maxLength: 42 pattern: ^group-[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 group in the format 'group-' examples: - group-123e4567-e89b-42d3-8456-426614174000 title: Group Id description: The ID of the group in the format 'group-' - name: message_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^message-[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 message in the format 'message-' examples: - message-123e4567-e89b-42d3-8456-426614174000 title: Message Id description: The ID of the message in the format 'message-' requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/UpdateSystemMessage' - $ref: '#/components/schemas/UpdateUserMessage' - $ref: '#/components/schemas/UpdateReasoningMessage' - $ref: '#/components/schemas/UpdateAssistantMessage' title: Request responses: '200': description: Successful Response content: application/json: schema: oneOf: - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ReasoningMessage' - $ref: '#/components/schemas/HiddenReasoningMessage' - $ref: '#/components/schemas/ToolCallMessage' - $ref: '#/components/schemas/ToolReturnMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ApprovalRequestMessage' - $ref: '#/components/schemas/ApprovalResponseMessage' - $ref: '#/components/schemas/SummaryMessage' - $ref: '#/components/schemas/EventMessage' discriminator: propertyName: message_type mapping: system_message: '#/components/schemas/SystemMessage' user_message: '#/components/schemas/UserMessage' reasoning_message: '#/components/schemas/ReasoningMessage' hidden_reasoning_message: '#/components/schemas/HiddenReasoningMessage' tool_call_message: '#/components/schemas/ToolCallMessage' tool_return_message: '#/components/schemas/ToolReturnMessage' assistant_message: '#/components/schemas/AssistantMessage' approval_request_message: '#/components/schemas/ApprovalRequestMessage' approval_response_message: '#/components/schemas/ApprovalResponseMessage' summary_message: '#/components/schemas/SummaryMessage' event_message: '#/components/schemas/EventMessage' title: Response Modify Group Message '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/groups/{group_id}/messages: get: tags: - Groups summary: List Group Messages description: Retrieve message history for an agent. operationId: list_group_messages deprecated: true parameters: - name: group_id in: path required: true schema: type: string minLength: 42 maxLength: 42 pattern: ^group-[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 group in the format 'group-' examples: - group-123e4567-e89b-42d3-8456-426614174000 title: Group Id description: The ID of the group in the format 'group-' - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to retrieve default: 10 title: Limit description: Maximum number of messages to retrieve - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for messages 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: use_assistant_message in: query required: false schema: type: boolean description: Whether to use assistant messages deprecated: true default: true title: Use Assistant Message description: Whether to use assistant messages deprecated: true - name: assistant_message_tool_name in: query required: false schema: type: string description: The name of the designated message tool. deprecated: true default: send_message title: Assistant Message Tool Name description: The name of the designated message tool. deprecated: true - name: assistant_message_tool_kwarg in: query required: false schema: type: string description: The name of the message argument. deprecated: true default: message title: Assistant Message Tool Kwarg description: The name of the message argument. deprecated: true - name: include_return_message_types in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/MessageType' - type: 'null' description: Message types to include in response. When null, all message types are returned. title: Include Return Message Types description: Message types to include in response. When null, all message types are returned. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/LettaMessageUnion' title: Response List Group Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/groups/{group_id}/reset-messages: patch: tags: - Groups summary: Reset Group Messages description: Delete the group messages for all agents that are part of the multi-agent group. operationId: reset_group_messages deprecated: true parameters: - name: group_id in: path required: true schema: type: string minLength: 42 maxLength: 42 pattern: ^group-[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 group in the format 'group-' examples: - group-123e4567-e89b-42d3-8456-426614174000 title: Group Id description: The ID of the group in the format 'group-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/groups/{group_id}/blocks/attach/{block_id}: patch: tags: - Groups summary: Attach Block to Group description: 'Attach a block to a group. This will add the block to the group and all agents within the group.' operationId: attach_block_to_group deprecated: true parameters: - name: block_id in: path required: true schema: type: string title: Block Id - name: group_id in: path required: true schema: type: string minLength: 42 maxLength: 42 pattern: ^group-[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 group in the format 'group-' examples: - group-123e4567-e89b-42d3-8456-426614174000 title: Group Id description: The ID of the group in the format 'group-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/groups/{group_id}/blocks/detach/{block_id}: patch: tags: - Groups summary: Detach Block from Group description: 'Detach a block from a group. This will remove the block from the group and all agents within the group.' operationId: detach_block_from_group deprecated: true parameters: - name: block_id in: path required: true schema: type: string title: Block Id - name: group_id in: path required: true schema: type: string minLength: 42 maxLength: 42 pattern: ^group-[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 group in the format 'group-' examples: - group-123e4567-e89b-42d3-8456-426614174000 title: Group Id description: The ID of the group in the format 'group-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/identities/: get: tags: - Identities - Identities summary: List Identities description: Get a list of all identities in the database operationId: list_identities deprecated: true parameters: - name: name in: query required: false schema: anyOf: - type: string - type: 'null' title: Name - name: project_id in: query required: false schema: anyOf: - type: string - type: 'null' description: '[DEPRECATED: Use X-Project-Id header instead] Filter identities by project ID' deprecated: true title: Project Id description: '[DEPRECATED: Use X-Project-Id header instead] Filter identities by project ID' deprecated: true - name: identifier_key in: query required: false schema: anyOf: - type: string - type: 'null' title: Identifier Key - name: identity_type in: query required: false schema: anyOf: - $ref: '#/components/schemas/IdentityType' - type: 'null' title: Identity Type - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Identity ID cursor for pagination. Returns identities that come before this identity ID in the specified sort order title: Before description: Identity ID cursor for pagination. Returns identities that come before this identity ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Identity ID cursor for pagination. Returns identities that come after this identity ID in the specified sort order title: After description: Identity ID cursor for pagination. Returns identities that come after this identity ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of identities to return default: 50 title: Limit description: Maximum number of identities to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for identities by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for identities 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/Identity' title: Response List Identities '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Identities - Identities summary: Create Identity operationId: create_identity deprecated: true parameters: - name: X-Project in: header required: false schema: anyOf: - type: string - type: 'null' description: The project slug to associate with the identity (cloud only). title: X-Project description: The project slug to associate with the identity (cloud only). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IdentityCreate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Identity' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' put: tags: - Identities - Identities summary: Upsert Identity operationId: upsert_identity deprecated: true parameters: - name: X-Project in: header required: false schema: anyOf: - type: string - type: 'null' description: The project slug to associate with the identity (cloud only). title: X-Project description: The project slug to associate with the identity (cloud only). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IdentityUpsert' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Identity' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/identities/count: get: tags: - Identities - Identities summary: Count Identities description: Get count of all identities for a user operationId: count_identities deprecated: true parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: integer title: Response Count Identities '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/identities/{identity_id}: get: tags: - Identities - Identities summary: Retrieve Identity operationId: retrieve_identity deprecated: true parameters: - name: identity_id in: path required: true schema: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 title: Identity Id description: The ID of the identity in the format 'identity-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Identity' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Identities - Identities summary: Modify Identity operationId: update_identity deprecated: true parameters: - name: identity_id in: path required: true schema: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 title: Identity Id description: The ID of the identity in the format 'identity-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IdentityUpdate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Identity' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Identities - Identities summary: Delete Identity description: Delete an identity by its identifier key operationId: delete_identity deprecated: true parameters: - name: identity_id in: path required: true schema: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 title: Identity Id description: The ID of the identity in the format 'identity-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/identities/{identity_id}/properties: put: tags: - Identities - Identities summary: Upsert Properties for Identity operationId: upsert_properties_for_identity deprecated: true parameters: - name: identity_id in: path required: true schema: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 title: Identity Id description: The ID of the identity in the format 'identity-' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/IdentityProperty' title: Properties responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/identities/{identity_id}/agents: get: tags: - Identities summary: List Agents for Identity description: Get all agents associated with the specified identity. operationId: list_agents_for_identity deprecated: true parameters: - name: identity_id in: path required: true schema: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 title: Identity Id description: The ID of the identity in the format 'identity-' - 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 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 Identity '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/identities/{identity_id}/blocks: get: tags: - Identities summary: List Blocks for Identity description: Get all blocks associated with the specified identity. operationId: list_blocks_for_identity deprecated: true parameters: - name: identity_id in: path required: true schema: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 title: Identity Id description: The ID of the identity in the format 'identity-' - 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: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of blocks to return default: 50 title: Limit description: Maximum number of blocks to return - 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: desc 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 responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/BlockResponse' title: Response List Blocks For Identity '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/_internal_agents/count: get: tags: - Internal Agents summary: Count Agents description: Get the total number of agents for a user, with option to exclude hidden agents. operationId: count_internal_agents parameters: - name: exclude_hidden in: query required: false schema: type: boolean description: If True, excludes hidden agents from the count. If False, includes all agents. default: true title: Exclude Hidden description: If True, excludes hidden agents from the count. If False, includes all agents. responses: '200': description: Successful Response content: application/json: schema: type: integer title: Response Count Internal Agents '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/_internal_agents/{agent_id}/core-memory/blocks/{block_label}: patch: tags: - Internal Agents summary: Modify Block for Agent description: Updates a core memory block of an agent. operationId: modify_internal_core_memory_block parameters: - name: block_label in: path required: true schema: type: string title: Block Label - 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 title: Agent Id description: The ID of the agent in the format 'agent-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BlockUpdate' 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/: 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-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 title: Identity Id description: The ID of the identity in the format 'identity-' - 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' - 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' /v1/_internal_runs/: get: tags: - Internal Runs summary: List Runs description: List all runs. operationId: list_internal_runs parameters: - name: run_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by a specific run ID. title: Run Id description: Filter by a specific run ID. - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The unique identifier of the agent associated with the run. title: Agent Id description: The unique identifier of the agent associated with the run. - name: agent_ids in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field. deprecated: true title: Agent Ids description: The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field. deprecated: true - name: statuses in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter runs by status. Can specify multiple statuses. title: Statuses description: Filter runs by status. Can specify multiple statuses. - name: background in: query required: false schema: anyOf: - type: boolean - type: 'null' description: If True, filters for runs that were created in background mode. title: Background description: If True, filters for runs that were created in background mode. - name: stop_reason in: query required: false schema: anyOf: - $ref: '#/components/schemas/StopReasonType' - type: 'null' description: Filter runs by stop reason. title: Stop Reason description: Filter runs by stop reason. - name: template_family in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter runs by template family (base_template_id). title: Template Family description: Filter runs by template family (base_template_id). - name: step_count in: query required: false schema: anyOf: - type: integer - type: 'null' description: Filter runs by step count. Must be provided with step_count_operator. title: Step Count description: Filter runs by step count. Must be provided with step_count_operator. - name: step_count_operator in: query required: false schema: $ref: '#/components/schemas/ComparisonOperator' description: 'Operator for step_count filter: ''eq'' for equals, ''gte'' for greater than or equal, ''lte'' for less than or equal.' default: eq description: 'Operator for step_count filter: ''eq'' for equals, ''gte'' for greater than or equal, ''lte'' for less than or equal.' - name: tools_used in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter runs that used any of the specified tools. title: Tools Used description: Filter runs that used any of the specified tools. - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order title: Before description: Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order title: After description: Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' description: Maximum number of runs to return default: 100 title: Limit description: Maximum number of runs to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first - name: order_by in: query required: false schema: enum: - created_at - duration type: string description: Field to sort by default: created_at title: Order By description: Field to sort by - name: active in: query required: false schema: type: boolean description: Filter for active runs. default: false title: Active description: Filter for active runs. - 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 in favor of order field. deprecated: true default: false title: Ascending description: Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field. deprecated: true - name: project_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter runs by project ID. title: Project Id description: Filter runs by project ID. - name: conversation_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter runs by conversation ID. title: Conversation Id description: Filter runs by conversation ID. - name: duration_percentile in: query required: false schema: anyOf: - type: integer - type: 'null' description: Filter runs by duration percentile (1-100). Returns runs slower than this percentile. title: Duration Percentile description: Filter runs by duration percentile (1-100). Returns runs slower than this percentile. - name: duration_value in: query required: false schema: anyOf: - type: integer - type: 'null' description: Duration value in nanoseconds for filtering. Must be used with duration_operator. title: Duration Value description: Duration value in nanoseconds for filtering. Must be used with duration_operator. - name: duration_operator in: query required: false schema: anyOf: - enum: - gt - lt - eq type: string - type: 'null' description: 'Comparison operator for duration filter: ''gt'' (greater than), ''lt'' (less than), ''eq'' (equals).' title: Duration Operator description: 'Comparison operator for duration filter: ''gt'' (greater than), ''lt'' (less than), ''eq'' (equals).' - name: start_date in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Filter runs created on or after this date (ISO 8601 format). title: Start Date description: Filter runs created on or after this date (ISO 8601 format). - name: end_date in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Filter runs created on or before this date (ISO 8601 format). title: End Date description: Filter runs created on or before this date (ISO 8601 format). responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Run' title: Response List Internal Runs '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/_internal_templates/groups: post: tags: - Internal Templates summary: Create Group description: Create a new multi-agent group with the specified configuration. operationId: create_internal_template_group parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InternalTemplateGroupCreate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Group' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/_internal_templates/agents: post: tags: - Internal Templates summary: Create Agent description: Create a new agent with template-related fields. operationId: create_internal_template_agent parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InternalTemplateAgentCreate' 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/_internal_templates/blocks: post: tags: - Internal Templates summary: Create Block description: Create a new block with template-related fields. operationId: create_internal_template_block parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InternalTemplateBlockCreate' 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_templates/blocks/batch: post: tags: - Internal Templates summary: Create Blocks Batch description: Create multiple blocks with template-related fields. operationId: create_internal_template_blocks_batch parameters: [] requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/InternalTemplateBlockCreate' title: Blocks responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Block' title: Response Create Internal Template Blocks Batch '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/_internal_templates/deployment/{deployment_id}: get: tags: - Internal Templates summary: List Deployment Entities description: 'List all entities (blocks, agents, groups) with the specified deployment_id. Optionally filter by entity types.' operationId: list_deployment_entities parameters: - name: deployment_id in: path required: true schema: type: string title: Deployment Id - name: entity_types in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by entity types (block, agent, group) title: Entity Types description: Filter by entity types (block, agent, group) responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListDeploymentEntitiesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Internal Templates summary: Delete Deployment description: 'Delete all entities (blocks, agents, groups) with the specified deployment_id. Deletion order: blocks -> agents -> groups to maintain referential integrity.' operationId: delete_deployment parameters: - name: deployment_id in: path required: true schema: type: string title: Deployment Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteDeploymentResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/models/: get: tags: - Models - LLMs summary: List LLM Models description: 'List available LLM models using the asynchronous implementation for improved performance. Returns Model format which extends LLMConfig with additional metadata fields. Legacy LLMConfig fields are marked as deprecated but still available for backward compatibility.' operationId: list_models parameters: - name: provider_category in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/ProviderCategory' - type: 'null' title: Provider Category - name: provider_name in: query required: false schema: anyOf: - type: string - type: 'null' title: Provider Name - name: provider_type in: query required: false schema: anyOf: - $ref: '#/components/schemas/ProviderType' - type: 'null' title: Provider Type responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Model' title: Response List Models '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/models/embedding: get: tags: - Models - LLMs summary: List Embedding Models description: 'List available embedding models using the asynchronous implementation for improved performance. Returns EmbeddingModel format which extends EmbeddingConfig with additional metadata fields. Legacy EmbeddingConfig fields are marked as deprecated but still available for backward compatibility.' operationId: list_embedding_models parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/EmbeddingModel' title: Response List Embedding Models '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/mcp-servers/: post: tags: - MCP Servers summary: Create MCP Server description: Add a new MCP server to the Letta MCP server config operationId: mcp_create_mcp_server parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMCPServerRequest' responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/StdioMCPServer' - $ref: '#/components/schemas/SSEMCPServer' - $ref: '#/components/schemas/StreamableHTTPMCPServer' title: Response Mcp Create Mcp Server '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' get: tags: - MCP Servers summary: List MCP Servers description: Get a list of all configured MCP servers operationId: mcp_list_mcp_servers parameters: [] responses: '200': description: Successful Response content: application/json: schema: type: array items: anyOf: - $ref: '#/components/schemas/StdioMCPServer' - $ref: '#/components/schemas/SSEMCPServer' - $ref: '#/components/schemas/StreamableHTTPMCPServer' title: Response Mcp List Mcp Servers '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/mcp-servers/{mcp_server_id}: get: tags: - MCP Servers summary: Retrieve MCP Server description: Get a specific MCP server operationId: mcp_retrieve_mcp_server parameters: - name: mcp_server_id in: path required: true schema: type: string title: Mcp Server Id responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/StdioMCPServer' - $ref: '#/components/schemas/SSEMCPServer' - $ref: '#/components/schemas/StreamableHTTPMCPServer' title: Response Mcp Retrieve Mcp Server '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - MCP Servers summary: Delete MCP Server description: Delete an MCP server by its ID operationId: mcp_delete_mcp_server parameters: - name: mcp_server_id in: path required: true schema: type: string title: Mcp Server Id responses: '204': description: Successful Response '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - MCP Servers summary: Update MCP Server description: Update an existing MCP server configuration operationId: mcp_update_mcp_server parameters: - name: mcp_server_id in: path required: true schema: type: string title: Mcp Server Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMCPServerRequest' responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/StdioMCPServer' - $ref: '#/components/schemas/SSEMCPServer' - $ref: '#/components/schemas/StreamableHTTPMCPServer' title: Response Mcp Update Mcp Server '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/mcp-servers/{mcp_server_id}/tools: get: tags: - MCP Servers summary: List Tools for MCP Server description: Get a list of all tools for a specific MCP server operationId: mcp_list_tools_for_mcp_server parameters: - name: mcp_server_id in: path required: true schema: type: string title: Mcp Server Id responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Tool' title: Response Mcp List Tools For Mcp Server '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/mcp-servers/{mcp_server_id}/tools/{tool_id}: get: tags: - MCP Servers summary: Retrieve MCP Tool description: Get a specific MCP tool by its ID operationId: mcp_retrieve_mcp_tool parameters: - name: mcp_server_id in: path required: true schema: type: string title: Mcp Server Id - name: tool_id in: path required: true schema: type: string title: Tool Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tool' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/mcp-servers/{mcp_server_id}/tools/{tool_id}/run: post: tags: - MCP Servers summary: Run MCP Tool description: 'Execute a specific MCP tool The request body should contain the tool arguments in the ToolExecuteRequest format.' operationId: mcp_run_tool parameters: - name: mcp_server_id in: path required: true schema: type: string title: Mcp Server Id - name: tool_id in: path required: true schema: type: string title: Tool Id requestBody: content: application/json: schema: $ref: '#/components/schemas/letta__schemas__mcp_server__ToolExecuteRequest' default: args: {} responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ToolExecutionResult' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/mcp-servers/{mcp_server_id}/refresh: patch: tags: - MCP Servers summary: Refresh MCP Server Tools description: 'Refresh tools for an MCP server by: 1. Fetching current tools from the MCP server 2. Deleting tools that no longer exist on the server 3. Updating schemas for existing tools 4. Adding new tools from the server Returns a summary of changes made.' operationId: mcp_refresh_mcp_server_tools parameters: - name: mcp_server_id in: path required: true schema: type: string title: Mcp Server Id - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Agent Id responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/mcp-servers/connect/{mcp_server_id}: get: tags: - MCP Servers summary: Connect MCP Server description: 'Connect to an MCP server with support for OAuth via SSE. Returns a stream of events handling authorization state and exchange if OAuth is required.' operationId: mcp_connect_mcp_server parameters: - name: mcp_server_id in: path required: true schema: type: string title: Mcp Server Id responses: '200': description: Successful response content: application/json: schema: {} text/event-stream: description: Server-Sent Events stream '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /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-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 title: Identity Id description: The ID of the identity in the format 'identity-' - 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' - 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 title: Block Id description: The ID of the block in the format 'block-' 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/jobs/: get: tags: - Jobs summary: List Jobs description: List all jobs. operationId: list_jobs parameters: - name: source_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Deprecated: Use `folder_id` parameter instead. Only list jobs associated with the source.' deprecated: true title: Source Id description: 'Deprecated: Use `folder_id` parameter instead. Only list jobs associated with the source.' deprecated: true - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Job ID cursor for pagination. Returns jobs that come before this job ID in the specified sort order title: Before description: Job ID cursor for pagination. Returns jobs that come before this job ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Job ID cursor for pagination. Returns jobs that come after this job ID in the specified sort order title: After description: Job ID cursor for pagination. Returns jobs that come after this job ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of jobs to return default: 100 title: Limit description: Maximum number of jobs to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for jobs by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for jobs 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: active in: query required: false schema: type: boolean description: Filter for active jobs. default: false title: Active description: Filter for active jobs. - name: ascending in: query required: false schema: type: boolean description: Whether to sort jobs oldest to newest (True, default) or newest to oldest (False). Deprecated in favor of order field. deprecated: true default: true title: Ascending description: Whether to sort jobs oldest to newest (True, default) or newest to oldest (False). Deprecated in favor of order field. deprecated: true responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Job' title: Response List Jobs '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/jobs/active: get: tags: - Jobs summary: List Active Jobs description: List all active jobs. operationId: list_active_jobs deprecated: true parameters: - name: source_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Deprecated: Use `folder_id` parameter instead. Only list jobs associated with the source.' deprecated: true title: Source Id description: 'Deprecated: Use `folder_id` parameter instead. Only list jobs associated with the source.' deprecated: true - 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: ascending in: query required: false schema: type: boolean description: Whether to sort jobs oldest to newest (True, default) or newest to oldest (False) default: true title: Ascending description: Whether to sort jobs oldest to newest (True, default) or newest to oldest (False) responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Job' title: Response List Active Jobs '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/jobs/{job_id}: get: tags: - Jobs summary: Retrieve Job description: Get the status of a job. operationId: retrieve_job parameters: - name: job_id in: path required: true schema: type: string minLength: 40 maxLength: 40 pattern: ^job-[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 job in the format 'job-' examples: - job-123e4567-e89b-42d3-8456-426614174000 title: Job Id description: The ID of the job in the format 'job-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Job' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Jobs summary: Delete Job description: Delete a job by its job_id. operationId: delete_job parameters: - name: job_id in: path required: true schema: type: string minLength: 40 maxLength: 40 pattern: ^job-[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 job in the format 'job-' examples: - job-123e4567-e89b-42d3-8456-426614174000 title: Job Id description: The ID of the job in the format 'job-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Job' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/jobs/{job_id}/cancel: patch: tags: - Jobs summary: Cancel Job description: 'Cancel a job by its job_id. This endpoint marks a job as cancelled, which will cause any associated agent execution to terminate as soon as possible.' operationId: cancel_job parameters: - name: job_id in: path required: true schema: type: string minLength: 40 maxLength: 40 pattern: ^job-[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 job in the format 'job-' examples: - job-123e4567-e89b-42d3-8456-426614174000 title: Job Id description: The ID of the job in the format 'job-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Job' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/health/: get: tags: - Health summary: Check Health description: Liveness endpoint; returns 200 when process is responsive. operationId: check_health responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Health' /v1/ready/: get: tags: - Health summary: Check Readiness description: Readiness endpoint gated by internal readiness state when enforcement is enabled. operationId: check_readiness responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Health' /v1/providers/: get: tags: - Providers summary: List Providers description: Get a list of all custom providers. operationId: list_providers parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Provider ID cursor for pagination. Returns providers that come before this provider ID in the specified sort order title: Before description: Provider ID cursor for pagination. Returns providers that come before this provider ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Provider ID cursor for pagination. Returns providers that come after this provider ID in the specified sort order title: After description: Provider ID cursor for pagination. Returns providers that come after this provider ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of providers to return default: 50 title: Limit description: Maximum number of providers to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for providers by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for providers 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: name in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter providers by name title: Name description: Filter providers by name - name: provider_type in: query required: false schema: anyOf: - $ref: '#/components/schemas/ProviderType' - type: 'null' description: Filter providers by type title: Provider Type description: Filter providers by type responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Provider' title: Response List Providers '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Providers summary: Create Provider description: Create a new custom provider. operationId: create_provider parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProviderCreate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Provider' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/providers/{provider_id}: get: tags: - Providers summary: Retrieve Provider description: Get a provider by ID. operationId: retrieve_provider parameters: - name: provider_id in: path required: true schema: type: string minLength: 45 maxLength: 45 pattern: ^provider-[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 provider in the format 'provider-' examples: - provider-123e4567-e89b-42d3-8456-426614174000 title: Provider Id description: The ID of the provider in the format 'provider-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Provider' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Providers summary: Modify Provider description: Update an existing custom provider. operationId: modify_provider parameters: - name: provider_id in: path required: true schema: type: string minLength: 45 maxLength: 45 pattern: ^provider-[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 provider in the format 'provider-' examples: - provider-123e4567-e89b-42d3-8456-426614174000 title: Provider Id description: The ID of the provider in the format 'provider-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProviderUpdate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Provider' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Providers summary: Delete Provider description: Delete an existing custom provider. operationId: delete_provider parameters: - name: provider_id in: path required: true schema: type: string minLength: 45 maxLength: 45 pattern: ^provider-[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 provider in the format 'provider-' examples: - provider-123e4567-e89b-42d3-8456-426614174000 title: Provider Id description: The ID of the provider in the format 'provider-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/providers/check: post: tags: - Providers summary: Check Provider description: Verify the API key and additional parameters for a provider. operationId: check_provider requestBody: content: application/json: schema: $ref: '#/components/schemas/ProviderCheck' required: true responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/providers/{provider_id}/check: post: tags: - Providers summary: Check Existing Provider description: Verify the API key and additional parameters for an existing provider. operationId: check_existing_provider parameters: - name: provider_id in: path required: true schema: type: string minLength: 45 maxLength: 45 pattern: ^provider-[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 provider in the format 'provider-' examples: - provider-123e4567-e89b-42d3-8456-426614174000 title: Provider Id description: The ID of the provider in the format 'provider-' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/providers/{provider_id}/refresh: patch: tags: - Providers summary: Refresh Provider Models description: 'Refresh models for a BYOK provider by querying the provider''s API. Adds new models and removes ones no longer available.' operationId: refresh_provider_models parameters: - name: provider_id in: path required: true schema: type: string minLength: 45 maxLength: 45 pattern: ^provider-[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 provider in the format 'provider-' examples: - provider-123e4567-e89b-42d3-8456-426614174000 title: Provider Id description: The ID of the provider in the format 'provider-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Provider' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/: get: tags: - Runs summary: List Runs description: List all runs. operationId: list_runs parameters: - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The unique identifier of the agent associated with the run. title: Agent Id description: The unique identifier of the agent associated with the run. - name: agent_ids in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field. deprecated: true title: Agent Ids description: The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field. deprecated: true - name: statuses in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter runs by status. Can specify multiple statuses. title: Statuses description: Filter runs by status. Can specify multiple statuses. - name: background in: query required: false schema: anyOf: - type: boolean - type: 'null' description: If True, filters for runs that were created in background mode. title: Background description: If True, filters for runs that were created in background mode. - name: stop_reason in: query required: false schema: anyOf: - $ref: '#/components/schemas/StopReasonType' - type: 'null' description: Filter runs by stop reason. title: Stop Reason description: Filter runs by stop reason. - name: conversation_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter runs by conversation ID. title: Conversation Id description: Filter runs by conversation ID. - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order title: Before description: Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order title: After description: Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' description: Maximum number of runs to return default: 100 title: Limit description: Maximum number of runs to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for runs 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: active in: query required: false schema: type: boolean description: Filter for active runs. default: false title: Active description: Filter for active runs. - 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 in favor of order field. deprecated: true default: false title: Ascending description: Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field. deprecated: true responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Run' title: Response List Runs '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/active: get: tags: - Runs summary: List Active Runs description: List all active runs. operationId: list_active_runs deprecated: true parameters: - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The unique identifier of the agent associated with the run. title: Agent Id description: The unique identifier of the agent associated with the run. - name: background in: query required: false schema: anyOf: - type: boolean - type: 'null' description: If True, filters for runs that were created in background mode. title: Background description: If True, filters for runs that were created in background mode. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Run' title: Response List Active Runs '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/{run_id}: get: tags: - Runs summary: Retrieve Run description: Get the status of a run. operationId: retrieve_run parameters: - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Run' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Runs summary: Delete Run description: Delete a run by its run_id. operationId: delete_run parameters: - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/{run_id}/messages: get: tags: - Runs summary: List Messages for Run description: Get response messages associated with a run. operationId: list_messages_for_run parameters: - name: run_id in: path required: true schema: type: string title: Run Id - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: asc title: Order description: Sort order for messages 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/LettaMessageUnion' title: Response List Messages For Run '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/{run_id}/usage: get: tags: - Runs summary: Retrieve Usage for Run description: Get usage statistics for a run. operationId: retrieve_usage_for_run parameters: - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UsageStatistics' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/{run_id}/metrics: get: tags: - Runs summary: Retrieve Metrics for Run description: Get run metrics by run ID. operationId: retrieve_metrics_for_run parameters: - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RunMetrics' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/{run_id}/steps: get: tags: - Runs summary: List Steps for Run description: Get steps associated with a run with filtering options. operationId: list_steps_for_run parameters: - name: run_id in: path required: true schema: type: string title: Run Id - 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: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for steps 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/Step' title: Response List Steps For Run '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/{run_id}/trace: get: tags: - Runs summary: Retrieve Trace for Run description: 'Retrieve OTEL trace spans for a run. Returns a filtered set of spans relevant for observability: - agent_step: Individual agent reasoning steps - tool executions: Tool call spans - Root span: The top-level request span - time_to_first_token: TTFT measurement span Requires ClickHouse to be configured for trace storage.' operationId: retrieve_trace_for_run parameters: - name: run_id in: path required: true schema: type: string title: Run Id - name: limit in: query required: false schema: type: integer maximum: 5000 minimum: 1 description: Maximum number of spans to return default: 1000 title: Limit description: Maximum number of spans to return responses: '200': description: Successful Response content: application/json: schema: type: array items: type: object additionalProperties: true title: Response Retrieve Trace For Run '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/runs/{run_id}/stream: post: tags: - Runs summary: Retrieve Stream for Run operationId: retrieve_stream_for_run parameters: - name: run_id in: path required: true schema: type: string title: Run Id requestBody: content: application/json: schema: $ref: '#/components/schemas/RetrieveStreamRequest' responses: '200': description: Successful response content: application/json: schema: {} text/event-stream: description: Server-Sent Events stream schema: oneOf: - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ReasoningMessage' - $ref: '#/components/schemas/HiddenReasoningMessage' - $ref: '#/components/schemas/ToolCallMessage' - $ref: '#/components/schemas/ToolReturnMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ApprovalRequestMessage' - $ref: '#/components/schemas/ApprovalResponseMessage' - $ref: '#/components/schemas/LettaPing' - $ref: '#/components/schemas/LettaErrorMessage' - $ref: '#/components/schemas/LettaStopReason' - $ref: '#/components/schemas/LettaUsageStatistics' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/steps/: get: tags: - Steps summary: List Steps description: List steps with optional pagination and date filters. operationId: list_steps parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Return steps before this step ID title: Before description: Return steps before this step ID - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Return steps after this step ID title: After description: Return steps after this step ID - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of steps to return default: 50 title: Limit description: Maximum number of steps to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for steps 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: start_date in: query required: false schema: anyOf: - type: string - type: 'null' description: Return steps after this ISO datetime (e.g. "2025-01-29T15:01:19-08:00") title: Start Date description: Return steps after this ISO datetime (e.g. "2025-01-29T15:01:19-08:00") - name: end_date in: query required: false schema: anyOf: - type: string - type: 'null' description: Return steps before this ISO datetime (e.g. "2025-01-29T15:01:19-08:00") title: End Date description: Return steps before this ISO datetime (e.g. "2025-01-29T15:01:19-08:00") - name: model in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by the name of the model used for the step title: Model description: Filter by the name of the model used for the step - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by the ID of the agent that performed the step title: Agent Id description: Filter by the ID of the agent that performed the step - name: trace_ids in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by trace ids returned by the server title: Trace Ids description: Filter by trace ids returned by the server - name: feedback in: query required: false schema: anyOf: - enum: - positive - negative type: string - type: 'null' description: Filter by feedback title: Feedback description: Filter by feedback - name: has_feedback in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Filter by whether steps have feedback (true) or not (false) title: Has Feedback description: Filter by whether steps have feedback (true) or not (false) - name: tags in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filter by tags title: Tags description: Filter by tags - name: project_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by the project ID that is associated with the step (cloud only). title: Project Id description: Filter by the project ID that is associated with the step (cloud only). - name: X-Project in: header required: false schema: anyOf: - type: string - type: 'null' description: Filter by project slug to associate with the group (cloud only). title: X-Project description: Filter by project slug to associate with the group (cloud only). responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/Step' title: Response List Steps '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/steps/{step_id}: get: tags: - Steps summary: Retrieve Step description: Get a step by ID. operationId: retrieve_step parameters: - name: step_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^step-[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 step in the format 'step-' examples: - step-123e4567-e89b-42d3-8456-426614174000 title: Step Id description: The ID of the step in the format 'step-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Step' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/steps/{step_id}/metrics: get: tags: - Steps summary: Retrieve Metrics for Step description: Get step metrics by step ID. operationId: retrieve_metrics_for_step parameters: - name: step_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^step-[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 step in the format 'step-' examples: - step-123e4567-e89b-42d3-8456-426614174000 title: Step Id description: The ID of the step in the format 'step-' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/StepMetrics' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/steps/{step_id}/trace: get: tags: - Steps summary: Retrieve Trace for Step operationId: retrieve_trace_for_step parameters: - name: step_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^step-[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 step in the format 'step-' examples: - step-123e4567-e89b-42d3-8456-426614174000 title: Step Id description: The ID of the step in the format 'step-' responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/ProviderTrace' - type: 'null' title: Response Retrieve Trace For Step '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/steps/{step_id}/feedback: patch: tags: - Steps summary: Modify Feedback for Step description: Modify feedback for a given step. operationId: modify_feedback_for_step parameters: - name: step_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^step-[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 step in the format 'step-' examples: - step-123e4567-e89b-42d3-8456-426614174000 title: Step Id description: The ID of the step in the format 'step-' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ModifyFeedbackRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Step' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/steps/{step_id}/messages: get: tags: - Steps summary: List Messages for Step description: List messages for a given step. operationId: list_messages_for_step parameters: - name: step_id in: path required: true schema: type: string minLength: 41 maxLength: 41 pattern: ^step-[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 step in the format 'step-' examples: - step-123e4567-e89b-42d3-8456-426614174000 title: Step Id description: The ID of the step in the format 'step-' - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: asc title: Order description: Sort order for messages 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: Sort by field default: created_at title: Order By description: Sort by field responses: '200': description: Successful Response content: application/json: schema: type: array items: oneOf: - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ReasoningMessage' - $ref: '#/components/schemas/HiddenReasoningMessage' - $ref: '#/components/schemas/ToolCallMessage' - $ref: '#/components/schemas/ToolReturnMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ApprovalRequestMessage' - $ref: '#/components/schemas/ApprovalResponseMessage' - $ref: '#/components/schemas/SummaryMessage' - $ref: '#/components/schemas/EventMessage' discriminator: propertyName: message_type mapping: system_message: '#/components/schemas/SystemMessage' user_message: '#/components/schemas/UserMessage' reasoning_message: '#/components/schemas/ReasoningMessage' hidden_reasoning_message: '#/components/schemas/HiddenReasoningMessage' tool_call_message: '#/components/schemas/ToolCallMessage' tool_return_message: '#/components/schemas/ToolReturnMessage' assistant_message: '#/components/schemas/AssistantMessage' approval_request_message: '#/components/schemas/ApprovalRequestMessage' approval_response_message: '#/components/schemas/ApprovalResponseMessage' summary_message: '#/components/schemas/SummaryMessage' event_message: '#/components/schemas/EventMessage' title: Response List Messages For Step '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/tags/: get: tags: - Tag - Admin - Admin summary: List Tags description: Get the list of all tags (from agents and blocks) that have been created. operationId: list_tags parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Tag cursor for pagination. Returns tags that come before this tag in the specified sort order title: Before description: Tag cursor for pagination. Returns tags that come before this tag in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Tag cursor for pagination. Returns tags that come after this tag in the specified sort order title: After description: Tag cursor for pagination. Returns tags that come after this tag in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of tags to return default: 50 title: Limit description: Maximum number of tags to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for tags. 'asc' for alphabetical order, 'desc' for reverse alphabetical order default: asc title: Order description: Sort order for tags. 'asc' for alphabetical order, 'desc' for reverse alphabetical order - name: order_by in: query required: false schema: const: name type: string description: Field to sort by default: name title: Order By description: Field to sort by - name: query_text in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter tags by text search. Deprecated, please use name field instead deprecated: true title: Query Text description: Filter tags by text search. Deprecated, please use name field instead deprecated: true - name: name in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter tags by name title: Name description: Filter tags by name responses: '200': description: Successful Response content: application/json: schema: type: array items: type: string title: Response List Tags '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/telemetry/{step_id}: get: tags: - Telemetry summary: Retrieve Provider Trace description: '**DEPRECATED**: Use `GET /steps/{step_id}/trace` instead. Retrieve provider trace by step ID.' operationId: retrieve_provider_trace deprecated: true parameters: - name: step_id in: path required: true schema: type: string title: Step Id responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/ProviderTrace' - type: 'null' title: Response Retrieve Provider Trace '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/: get: tags: - Messages summary: List All Messages description: List messages across all agents for the current user. operationId: list_all_messages parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first - name: conversation_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Conversation ID to filter messages by title: Conversation Id description: Conversation ID to filter messages by - name: include_return_message_types in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/MessageType' - type: 'null' description: Message types to include in response. When null, all message types are returned. title: Include Return Message Types description: Message types to include in response. When null, all message types are returned. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/LettaMessageUnion' title: Response List All Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/search: post: tags: - Messages summary: Search All Messages description: 'Search messages across the organization with optional agent filtering. Returns messages with FTS/vector ranks and total RRF score. This is a cloud-only feature.' operationId: search_all_messages parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchAllMessagesRequest' responses: '200': description: Successful Response content: application/json: schema: type: array items: oneOf: - $ref: '#/components/schemas/SystemMessageListResult' - $ref: '#/components/schemas/UserMessageListResult' - $ref: '#/components/schemas/ReasoningMessageListResult' - $ref: '#/components/schemas/AssistantMessageListResult' discriminator: propertyName: message_type mapping: system_message: '#/components/schemas/SystemMessageListResult' user_message: '#/components/schemas/UserMessageListResult' reasoning_message: '#/components/schemas/ReasoningMessageListResult' assistant_message: '#/components/schemas/AssistantMessageListResult' title: Response Search All Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/batches: post: tags: - Messages summary: Create Batch description: 'Submit a batch of agent runs for asynchronous processing. Creates a job that will fan out messages to all listed agents and process them in parallel. The request will be rejected if it exceeds 256MB.' operationId: create_batch parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBatch' description: Messages and config for all agents responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchJob' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' get: tags: - Messages summary: List Batches description: List all batch runs. operationId: list_batches parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Job ID cursor for pagination. Returns jobs that come before this job ID in the specified sort order title: Before description: Job ID cursor for pagination. Returns jobs that come before this job ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Job ID cursor for pagination. Returns jobs that come after this job ID in the specified sort order title: After description: Job ID cursor for pagination. Returns jobs that come after this job ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of jobs to return default: 100 title: Limit description: Maximum number of jobs to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for jobs by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for jobs 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/BatchJob' title: Response List Batches '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/batches/{batch_id}: get: tags: - Messages summary: Retrieve Batch description: Retrieve the status and details of a batch run. operationId: retrieve_batch parameters: - name: batch_id in: path required: true schema: type: string title: Batch Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchJob' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/batches/{batch_id}/messages: get: tags: - Messages summary: List Messages for Batch description: Get response messages for a specific batch job. operationId: list_messages_for_batch parameters: - name: batch_id in: path required: true schema: type: string title: Batch Id - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for messages 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: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter messages by agent ID title: Agent Id description: Filter messages by agent ID responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LettaBatchMessages' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/batches/{batch_id}/cancel: patch: tags: - Messages summary: Cancel Batch description: Cancel a batch run. operationId: cancel_batch parameters: - name: batch_id in: path required: true schema: type: string title: Batch Id responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/{message_id}: get: tags: - Messages summary: Retrieve Message description: Retrieve a message by ID. operationId: retrieve_message parameters: - name: message_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^message-[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 message in the format 'message-' examples: - message-123e4567-e89b-42d3-8456-426614174000 title: Message Id description: The ID of the message in the format 'message-' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/LettaMessageUnion' title: Response Retrieve Message '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/passages/search: post: tags: - Passages summary: Search Passages description: 'Search passages across the organization with optional agent and archive filtering. Returns passages with relevance scores. This endpoint supports semantic search through passages: - If neither agent_id nor archive_id is provided, searches ALL passages in the organization - If agent_id is provided, searches passages across all archives attached to that agent - If archive_id is provided, searches passages within that specific archive - If both are provided, agent_id takes precedence' operationId: search_passages parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PassageSearchRequest' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/PassageSearchResult' title: Response Search Passages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/voice-beta/{agent_id}/chat/completions: post: tags: - Voice summary: Create Voice Chat Completions description: 'DEPRECATED: This voice-beta endpoint has been deprecated. The voice functionality has been integrated into the main chat completions endpoint. Please use the standard /v1/agents/{agent_id}/messages endpoint instead. This endpoint will be removed in a future version.' operationId: create_voice_chat_completions deprecated: true parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id requestBody: required: true content: application/json: schema: type: object additionalProperties: true title: Completion Request responses: '200': description: Successful response content: application/json: schema: {} text/event-stream: {} '410': description: Endpoint deprecated content: application/json: example: detail: This endpoint has been deprecated '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/embeddings/total_storage_size: get: tags: - Embeddings summary: Get Embeddings Total Storage Size description: Get the total size of all embeddings in the database for a user in the storage unit given. operationId: get_total_storage_size parameters: - name: storage-unit in: header required: false schema: anyOf: - type: string - type: 'null' default: GB title: Storage Unit responses: '200': description: Successful Response content: application/json: schema: type: number title: Response Get Total Storage Size '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/search: post: description: Search deployed agents summary: Search Deployed Agents tags: - Agents parameters: [] operationId: agents.searchDeployedAgents requestBody: description: Body content: application/json: schema: type: object properties: search: type: array items: oneOf: - type: object properties: field: type: string enum: - version value: type: string required: - field - value - type: object properties: field: type: string enum: - name operator: type: string enum: - eq - contains value: type: string required: - field - operator - value - type: object properties: field: type: string enum: - tags operator: type: string enum: - contains value: type: array items: type: string required: - field - operator - value - type: object properties: field: type: string enum: - identity operator: type: string enum: - eq value: type: string required: - field - operator - value - type: object properties: field: type: string enum: - templateName operator: type: string enum: - eq value: type: string required: - field - operator - value - type: object properties: field: type: string enum: - agentId operator: type: string enum: - eq value: type: string required: - field - operator - value project_id: type: string combinator: type: string enum: - AND limit: type: number after: type: string nullable: true sortBy: type: string enum: - created_at - last_run_completion - updated_at ascending: type: boolean responses: '200': description: '200' content: application/json: schema: type: object properties: agents: type: array items: $ref: '#/components/schemas/AgentState' nextCursor: type: string nullable: true required: - agents /v1/agents/search/count: get: description: Count deployed agents matching search criteria summary: Count Deployed Agents tags: - Agents parameters: - name: search in: query schema: type: array items: oneOf: - type: object properties: field: type: string enum: - version value: type: string required: - field - value - type: object properties: field: type: string enum: - name operator: type: string enum: - eq - contains value: type: string required: - field - operator - value - type: object properties: field: type: string enum: - tags operator: type: string enum: - contains value: type: array items: type: string required: - field - operator - value - type: object properties: field: type: string enum: - identity operator: type: string enum: - eq value: type: string required: - field - operator - value - type: object properties: field: type: string enum: - templateName operator: type: string enum: - eq value: type: string required: - field - operator - value - type: object properties: field: type: string enum: - agentId operator: type: string enum: - eq value: type: string required: - field - operator - value - name: project_id in: query schema: type: string - name: combinator in: query schema: type: string enum: - AND operationId: agents.countDeployedAgents responses: '200': description: '200' content: application/json: schema: type: object properties: count: type: number required: - count /v1/agents/{agent_id}/core-memory/variables: get: description: Get the variables associated with an agent summary: Retrieve Memory Variables tags: - Agents parameters: - name: agent_id in: path required: true schema: type: string operationId: agents.getAgentVariables responses: '200': description: '200' content: application/json: schema: type: object properties: variables: type: object additionalProperties: type: string required: - variables '404': description: '404' content: application/json: schema: type: object properties: message: type: string enum: - Agent not found required: - message /v1/models/embeddings: get: tags: - Models parameters: [] operationId: models.listEmbeddingModels responses: '200': description: '200' /v1/templates/{project_id}/{template_version}/agents: post: description: Creates an Agent or multiple Agents from a template summary: Create Agents from Template tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_version in: path required: true schema: type: string description: The template version, formatted as {template-name}:{version-number} or {template-name}:latest. This endpoint is not available for self-hosted Letta. operationId: templates.createAgentsFromTemplate requestBody: description: Body content: application/json: schema: type: object properties: tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_ ]*$ description: The tags to assign to the agent agent_name: type: string pattern: ^[a-zA-Z0-9-_ ]*$ description: The name of the agent, optional otherwise a random one will be assigned initial_message_sequence: type: array items: type: object properties: role: type: string enum: - user - system - assistant content: type: string name: type: string nullable: true otid: type: string nullable: true sender_id: type: string nullable: true batch_item_id: type: string nullable: true group_id: type: string nullable: true required: - role - content description: Set an initial sequence of messages, if not provided, the agent will start with the default message sequence, if an empty array is provided, the agent will start with no messages memory_variables: type: object additionalProperties: type: string description: The memory variables to assign to the agent tool_variables: type: object additionalProperties: type: string description: The tool variables to assign to the agent identity_ids: type: array items: type: string description: The identity ids to assign to the agent responses: '201': description: '201' '402': description: '402' content: application/json: schema: type: object properties: message: type: string limit: type: number required: - message - limit /v1/templates/{template_version}/agents: post: description: Creates an Agent or multiple Agents from a template summary: Create Agents from Template tags: - Templates parameters: - name: template_version in: path required: true schema: type: string description: The template version, formatted as {template-name}:{version-number} or {template-name}:latest. This endpoint is not available for self-hosted Letta. operationId: templates.createAgentsFromTemplateNoProject requestBody: description: Body content: application/json: schema: type: object properties: tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_ ]*$ description: The tags to assign to the agent agent_name: type: string pattern: ^[a-zA-Z0-9-_ ]*$ description: The name of the agent, optional otherwise a random one will be assigned initial_message_sequence: type: array items: type: object properties: role: type: string enum: - user - system - assistant content: type: string name: type: string nullable: true otid: type: string nullable: true sender_id: type: string nullable: true batch_item_id: type: string nullable: true group_id: type: string nullable: true required: - role - content description: Set an initial sequence of messages, if not provided, the agent will start with the default message sequence, if an empty array is provided, the agent will start with no messages memory_variables: type: object additionalProperties: type: string description: The memory variables to assign to the agent tool_variables: type: object additionalProperties: type: string description: The tool variables to assign to the agent identity_ids: type: array items: type: string description: The identity ids to assign to the agent responses: '201': description: '201' content: application/json: schema: type: object properties: agent_ids: type: array items: type: string description: Array of created agent IDs group_id: type: string nullable: true description: Optional group ID if agents were created in a group deployment_id: type: string description: The deployment ID for the created agents required: - agent_ids - group_id - deployment_id description: Response containing created agent IDs and associated metadata '402': description: '402' content: application/json: schema: type: object properties: message: type: string limit: type: number required: - message - limit /v1/templates: get: description: List all templates summary: List Templates (Cloud-only) tags: - Templates parameters: - name: offset in: query schema: oneOf: - type: string - type: number - name: exact in: query description: Whether to search for an exact name match schema: type: string - name: limit in: query schema: type: string - name: version in: query description: Specify the version you want to return, otherwise will return the latest version schema: type: string - name: template_id in: query schema: type: string - name: name in: query schema: type: string - name: search in: query schema: type: string - name: project_slug in: query schema: type: string - name: project_id in: query schema: type: string - name: sort_by in: query schema: type: string enum: - updated_at - created_at operationId: templates.listTemplates responses: '200': description: '200' content: application/json: schema: type: object properties: templates: type: array items: type: object properties: name: type: string description: The exact name of the template id: type: string project_id: type: string project_slug: type: string latest_version: type: string description: The latest version of the template description: type: string template_deployment_slug: type: string description: The full name of the template, including version and project slug updated_at: type: string description: When the template was last updated required: - name - id - project_id - project_slug - latest_version - template_deployment_slug - updated_at has_next_page: type: boolean required: - templates - has_next_page post: description: Creates a new template from an existing agent or agent file summary: Create Template (Cloud-only) tags: - Templates parameters: [] operationId: templates.createTemplateNoProject requestBody: description: Body content: application/json: schema: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - agent agent_id: type: string description: The ID of the agent to use as a template, can be from any project name: type: string pattern: ^[a-zA-Z0-9_-]+$ description: Optional custom name for the template. If not provided, a random name will be generated. required: - type - agent_id summary: From Agent description: Create a template from an existing agent - type: object properties: type: type: string enum: - agent_file agent_file: type: object additionalProperties: nullable: true description: The agent file to use as a template, this should be a JSON file exported from the platform name: type: string pattern: ^[a-zA-Z0-9_-]+$ description: Optional custom name for the template. If not provided, a random name will be generated. update_existing_tools: type: boolean description: If true, update existing custom tools source_code and json_schema (source_type cannot be changed) required: - type - agent_file summary: From Agent File description: Create a template from an uploaded agent file summary: Create template description: The type of template to create, currently only agent templates are supported responses: '201': description: '201' content: application/json: schema: type: object properties: name: type: string description: The exact name of the template id: type: string project_id: type: string project_slug: type: string latest_version: type: string description: The latest version of the template description: type: string template_deployment_slug: type: string description: The full name of the template, including version and project slug updated_at: type: string description: When the template was last updated required: - name - id - project_id - project_slug - latest_version - template_deployment_slug - updated_at '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{template_name}/save: post: description: Saves the current version of the template as a new version summary: Save Template Version (Cloud-only) tags: - Templates parameters: - name: template_name in: path required: true schema: type: string description: The template version, formatted as {template-name}, any version appended will be ignored operationId: templates.saveTemplateVersionNoProject requestBody: description: Body content: application/json: schema: type: object properties: preserve_environment_variables_on_migration: type: boolean description: If true, the environment variables will be preserved in the template version when migrating agents preserve_core_memories_on_migration: type: boolean description: If true, the core memories will be preserved in the template version when migrating agents preserve_sources_on_migration: type: boolean description: If true, existing agent folders/sources will be preserved and merged with template sources during migration. If false, agent sources will be replaced with template sources. block_reconciliation_strategy: type: string enum: - reconcile-all - preserve-deleted description: 'Strategy for reconciling memory blocks during migration: "reconcile-all" deletes blocks not in the template, "preserve-deleted" keeps them. Defaults to "preserve-deleted".' migrate_agents: type: boolean description: If true, existing agents attached to this template will be migrated to the new template version message: type: string description: A message to describe the changes made in this template version responses: '200': description: '200' content: application/json: schema: type: object properties: name: type: string description: The exact name of the template id: type: string project_id: type: string project_slug: type: string latest_version: type: string description: The latest version of the template description: type: string template_deployment_slug: type: string description: The full name of the template, including version and project slug updated_at: type: string description: When the template was last updated required: - name - id - project_id - project_slug - latest_version - template_deployment_slug - updated_at '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{template_name}: post: description: Saves the current version of the template as a new version summary: Save Template Version (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_name in: path required: true schema: type: string description: The template version, formatted as {template-name}, any version appended will be ignored operationId: templates.saveTemplateVersion requestBody: description: Body content: application/json: schema: type: object properties: preserve_environment_variables_on_migration: type: boolean description: If true, the environment variables will be preserved in the template version when migrating agents preserve_core_memories_on_migration: type: boolean description: If true, the core memories will be preserved in the template version when migrating agents preserve_sources_on_migration: type: boolean description: If true, existing agent folders/sources will be preserved and merged with template sources during migration. If false, agent sources will be replaced with template sources. block_reconciliation_strategy: type: string enum: - reconcile-all - preserve-deleted description: 'Strategy for reconciling memory blocks during migration: "reconcile-all" deletes blocks not in the template, "preserve-deleted" keeps them. Defaults to "preserve-deleted".' migrate_agents: type: boolean description: If true, existing agents attached to this template will be migrated to the new template version message: type: string description: A message to describe the changes made in this template version responses: '200': description: '200' content: application/json: schema: type: object properties: name: type: string description: The exact name of the template id: type: string project_id: type: string project_slug: type: string latest_version: type: string description: The latest version of the template description: type: string template_deployment_slug: type: string description: The full name of the template, including version and project slug updated_at: type: string description: When the template was last updated required: - name - id - project_id - project_slug - latest_version - template_deployment_slug - updated_at '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message delete: description: Deletes all versions of a template with the specified name summary: Delete Template (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_name in: path required: true schema: type: string description: The template name (without version) operationId: templates.deleteTemplate requestBody: description: Body content: application/json: schema: type: object properties: {} responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{template_version}/snapshot: get: description: Get a snapshot of the template version, this will return the template state at a specific version summary: Get Template Snapshot (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_version in: path required: true schema: type: string description: The template version, formatted as {template-name}:{version-number} or {template-name}:latest operationId: templates.getTemplateSnapshot responses: '200': description: '200' content: application/json: schema: type: object properties: agents: type: array items: type: object properties: model: type: string systemPrompt: type: string toolIds: type: array items: type: string nullable: true sourceIds: type: array items: type: string nullable: true memoryVariables: type: object properties: version: type: string data: type: array items: type: object properties: key: type: string defaultValue: type: string nullable: true type: type: string required: - key - type required: - version - data nullable: true toolVariables: type: object properties: version: type: string data: type: array items: type: object properties: key: type: string defaultValue: type: string nullable: true type: type: string required: - key - type required: - version - data nullable: true tags: type: array items: type: string nullable: true identityIds: type: array items: type: string nullable: true toolRules: type: array items: oneOf: - type: object properties: tool_name: type: string type: type: string enum: - constrain_child_tools prompt_template: type: string nullable: true children: type: array items: type: string child_arg_nodes: type: array items: type: object properties: name: type: string args: type: object additionalProperties: {} nullable: true required: - name nullable: true required: - tool_name - children - type: object properties: tool_name: type: string type: type: string enum: - run_first prompt_template: type: string nullable: true args: type: object additionalProperties: {} nullable: true required: - tool_name - type: object properties: tool_name: type: string type: type: string enum: - exit_loop prompt_template: type: string nullable: true required: - tool_name - type: object properties: tool_name: type: string type: type: string enum: - conditional prompt_template: type: string nullable: true default_child: type: string nullable: true child_output_mapping: type: object additionalProperties: type: string require_output_mapping: type: boolean required: - tool_name - child_output_mapping - type: object properties: tool_name: type: string type: type: string enum: - continue_loop prompt_template: type: string nullable: true required: - tool_name - type: object properties: tool_name: type: string type: type: string enum: - required_before_exit prompt_template: type: string nullable: true required: - tool_name - type: object properties: tool_name: type: string type: type: string enum: - max_count_per_step prompt_template: type: string nullable: true max_count_limit: type: number required: - tool_name - max_count_limit - type: object properties: tool_name: type: string type: type: string enum: - parent_last_tool prompt_template: type: string nullable: true children: type: array items: type: string required: - tool_name - children - type: object properties: tool_name: type: string type: type: string enum: - requires_approval prompt_template: type: string nullable: true required: - tool_name nullable: true agentType: type: string enum: - letta_v1_agent - memgpt_agent - memgpt_v2_agent - react_agent - workflow_agent - split_thread_agent - sleeptime_agent - voice_convo_agent - voice_sleeptime_agent properties: type: object properties: enable_reasoner: type: boolean nullable: true put_inner_thoughts_in_kwargs: type: boolean nullable: true context_window_limit: type: number nullable: true max_tokens: type: number nullable: true max_reasoning_tokens: type: number nullable: true max_files_open: type: number nullable: true message_buffer_autoclear: type: boolean nullable: true verbosity_level: type: string enum: - low - medium - high nullable: true reasoning_effort: type: string enum: - none - minimal - low - medium - high - xhigh nullable: true per_file_view_window_char_limit: type: number nullable: true parallel_tool_calls: type: boolean nullable: true temperature: type: number nullable: true required: - enable_reasoner - put_inner_thoughts_in_kwargs - context_window_limit - max_tokens - max_reasoning_tokens - max_files_open - message_buffer_autoclear - verbosity_level - reasoning_effort - per_file_view_window_char_limit - parallel_tool_calls - temperature nullable: true entityId: type: string name: type: string required: - model - systemPrompt - toolIds - sourceIds - memoryVariables - toolVariables - tags - identityIds - toolRules - agentType - properties - entityId - name blocks: type: array items: type: object properties: entityId: type: string label: type: string value: type: string limit: type: number description: type: string preserveOnMigration: type: boolean nullable: true readOnly: type: boolean required: - entityId - label - value - limit - description - preserveOnMigration - readOnly relationships: type: array items: type: object properties: agentEntityId: type: string blockEntityId: type: string required: - agentEntityId - blockEntityId configuration: type: object properties: managerAgentEntityId: type: string managerType: type: string terminationToken: type: string maxTurns: type: number sleeptimeAgentFrequency: type: number maxMessageBufferLength: type: number minMessageBufferLength: type: number type: type: string enum: - classic - cluster - sleeptime - round_robin - supervisor - dynamic - voice_sleeptime version: type: string required: - agents - blocks - relationships - configuration - type - version put: description: Updates the current working version of a template from a snapshot summary: Set Current Template from Snapshot (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_version in: path required: true schema: type: string description: The template name with :dev version (e.g., my-template:dev) operationId: templates.setCurrentTemplateFromSnapshot requestBody: description: Body content: application/json: schema: nullable: true description: The template snapshot to set as the current version responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '500': description: '500' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{template_version}/fork: post: description: Forks a template version into a new template summary: Fork Template (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_version in: path required: true schema: type: string description: The template version, formatted as {template-name}:{version-number} or {template-name}:latest operationId: templates.forkTemplate requestBody: description: Body content: application/json: schema: type: object properties: name: type: string pattern: ^[a-zA-Z0-9_-]+$ description: Optional custom name for the forked template. If not provided, a random name will be generated. responses: '200': description: '200' content: application/json: schema: type: object properties: name: type: string description: The exact name of the template id: type: string project_id: type: string project_slug: type: string latest_version: type: string description: The latest version of the template description: type: string template_deployment_slug: type: string description: The full name of the template, including version and project slug updated_at: type: string description: When the template was last updated required: - name - id - project_id - project_slug - latest_version - template_deployment_slug - updated_at '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}: post: description: Creates a new template from an existing agent or agent file summary: Create Template (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id operationId: templates.createTemplate requestBody: description: Body content: application/json: schema: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - agent agent_id: type: string description: The ID of the agent to use as a template, can be from any project name: type: string pattern: ^[a-zA-Z0-9_-]+$ description: Optional custom name for the template. If not provided, a random name will be generated. required: - type - agent_id summary: From Agent description: Create a template from an existing agent - type: object properties: type: type: string enum: - agent_file agent_file: type: object additionalProperties: nullable: true description: The agent file to use as a template, this should be a JSON file exported from the platform name: type: string pattern: ^[a-zA-Z0-9_-]+$ description: Optional custom name for the template. If not provided, a random name will be generated. update_existing_tools: type: boolean description: If true, update existing custom tools source_code and json_schema (source_type cannot be changed) required: - type - agent_file summary: From Agent File description: Create a template from an uploaded agent file summary: Create template description: The type of template to create, currently only agent templates are supported responses: '201': description: '201' content: application/json: schema: type: object properties: name: type: string description: The exact name of the template id: type: string project_id: type: string project_slug: type: string latest_version: type: string description: The latest version of the template description: type: string template_deployment_slug: type: string description: The full name of the template, including version and project slug updated_at: type: string description: When the template was last updated required: - name - id - project_id - project_slug - latest_version - template_deployment_slug - updated_at '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{template_name}: delete: description: Deletes all versions of a template with the specified name summary: Delete Template (Cloud-only) tags: - Templates parameters: - name: template_name in: path required: true schema: type: string description: The template name (without version) operationId: templates.deleteTemplateNoProject requestBody: description: Body content: application/json: schema: type: object properties: {} responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message patch: description: Updates the current working version of a template from an agent file summary: Update Current Template from Agent File (Cloud-only) tags: - Templates parameters: - name: template_name in: path required: true schema: type: string description: The template name (without version) operationId: templates.updateCurrentTemplateFromAgentFileNoProject requestBody: description: Body content: application/json: schema: type: object properties: agent_file_json: type: object additionalProperties: nullable: true description: The agent file to update the current template version from update_existing_tools: default: false type: boolean description: If true, update existing custom tools source_code and json_schema (source_type cannot be changed) save_existing_changes: default: false type: boolean description: If true, Letta will automatically save any changes as a version before updating the template required: - agent_file_json responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '500': description: '500' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{template_name}/name: patch: description: Renames all versions of a template with the specified name. Versions are automatically stripped from the current template name if accidentally included. summary: Rename Template (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_name in: path required: true schema: type: string description: The current template name (version will be automatically stripped if included) operationId: templates.renameTemplate requestBody: description: Body content: application/json: schema: type: object properties: new_name: type: string pattern: ^[a-zA-Z0-9_-]+$ description: The new name for the template required: - new_name responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '409': description: '409' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{template_name}/description: patch: description: Updates the description for all versions of a template with the specified name. Versions are automatically stripped from the current template name if accidentally included. summary: Update Template Description (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_name in: path required: true schema: type: string description: The template name (version will be automatically stripped if included) operationId: templates.updateTemplateDescription requestBody: description: Body content: application/json: schema: type: object properties: description: type: string description: The new description for the template responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{name}/versions: get: description: List all versions of a specific template summary: List Template Versions (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: name in: path required: true schema: type: string description: The template name (without version) - name: offset in: query schema: oneOf: - type: string - type: number - name: limit in: query schema: type: string operationId: templates.listTemplateVersions responses: '200': description: '200' content: application/json: schema: type: object properties: versions: type: array items: type: object properties: version: type: string description: The version number created_at: type: string description: When the version was created message: type: string description: Version description message is_latest: type: boolean description: Whether this is the latest version required: - version - created_at - is_latest has_next_page: type: boolean total_count: type: number required: - versions - has_next_page - total_count '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{template_name}/deployments/{deployment_id}/migrate: post: description: Migrates a deployment to a specific template version summary: Migrate Deployment to Template Version (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_name in: path required: true schema: type: string description: The template name (without version) - name: deployment_id in: path required: true schema: type: string description: The deployment ID to migrate operationId: templates.migrateDeployment requestBody: description: Body content: application/json: schema: type: object properties: version: type: string description: The target template version to migrate to preserve_tool_variables: type: boolean description: Whether to preserve existing tool variables during migration preserve_core_memories: type: boolean description: Whether to preserve existing core memories during migration preserve_sources: type: boolean description: If true, existing agent sources will be preserved and merged with template sources during migration. If false, agent sources will be replaced with template sources. memory_variables: type: object additionalProperties: type: string description: Additional memory variables to apply during migration required: - version responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '500': description: '500' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{template_name}/rollback: post: description: Rollback the current working version of a template to a previous saved version. If the current version has unsaved changes, they will be automatically saved as a new version before rollback. summary: Rollback Template to Previous Version (Cloud-only) tags: - Templates parameters: - name: template_name in: path required: true schema: type: string description: The template name (without version) operationId: templates.rollbackTemplateNoProject requestBody: description: Body content: application/json: schema: type: object properties: version: type: string description: The target version to rollback to (e.g., "1", "2", "latest"). Cannot be "current" or "dev". required: - version responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '500': description: '500' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{template_name}/rollback: post: description: Rollback the current working version of a template to a previous saved version. If the current version has unsaved changes, they will be automatically saved as a new version before rollback. summary: Rollback Template to Previous Version (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_name in: path required: true schema: type: string description: The template name (without version) operationId: templates.rollbackTemplate requestBody: description: Body content: application/json: schema: type: object properties: version: type: string description: The target version to rollback to (e.g., "1", "2", "latest"). Cannot be "current" or "dev". required: - version responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '500': description: '500' content: application/json: schema: type: object properties: message: type: string required: - message /v1/templates/{project_id}/{template_name}/agent-file: put: description: Updates the current working version of a template from an agent file summary: Update Current Template from Agent File (Cloud-only) tags: - Templates parameters: - name: project_id in: path required: true schema: type: string description: The project id - name: template_name in: path required: true schema: type: string description: The template name (without version) operationId: templates.updateCurrentTemplateFromAgentFile requestBody: description: Body content: application/json: schema: type: object properties: agent_file_json: type: object additionalProperties: nullable: true description: The agent file to update the current template version from update_existing_tools: default: false type: boolean description: If true, update existing custom tools source_code and json_schema (source_type cannot be changed) save_existing_changes: default: false type: boolean description: If true, Letta will automatically save any changes as a version before updating the template required: - agent_file_json responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '500': description: '500' content: application/json: schema: type: object properties: message: type: string required: - message /v1/legacy-templates/{templateId}/migrates: post: description: Migrates a template from a legacy project to the default project. Only works if the template is currently in a legacy project. summary: Migrate Template from Legacy Project (Cloud-only) tags: - Templates parameters: - name: templateId in: path required: true schema: type: string description: The template ID operationId: templates.legacyMigration requestBody: description: Body content: application/json: schema: type: object properties: {} responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message /v1/client-side-access-tokens: post: description: Create a new client side access token with the specified configuration. summary: Create Token (Cloud-only) tags: - Client-Side Access Tokens parameters: [] operationId: clientSideAccessTokens.createClientSideAccessToken requestBody: description: Body content: application/json: schema: type: object properties: policy: type: array items: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - agent id: type: string access: type: array items: type: string enum: - read_messages - write_messages - read_agent - write_agent required: - type - id - access hostname: type: string format: uri pattern: ^(http|https):\/\/ description: The hostname of the client side application. Please specify the full URL including the protocol (http or https). expires_at: type: string description: The expiration date of the token. If not provided, the token will expire in 5 minutes required: - policy - hostname responses: '201': description: '201' content: application/json: schema: type: object properties: policy: type: object properties: version: type: string enum: - '1' data: type: array items: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - agent id: type: string access: type: array items: type: string enum: - read_messages - write_messages - read_agent - write_agent required: - type - id - access required: - version - data token: type: string hostname: type: string expiresAt: type: string required: - policy - token - hostname - expiresAt '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message get: description: List all client side access tokens for the current account. This is only available for cloud users. summary: List Tokens (Cloud-only) tags: - Client-Side Access Tokens parameters: - name: agentId in: query description: The agent ID to filter tokens by. If provided, only tokens for this agent will be returned. schema: type: string - name: offset in: query description: The offset for pagination. Defaults to 0. schema: default: 0 type: number - name: limit in: query description: The number of tokens to return per page. Defaults to 10. schema: default: 10 type: number operationId: clientSideAccessTokens.listClientSideAccessTokens responses: '200': description: '200' content: application/json: schema: type: object properties: tokens: type: array items: type: object properties: policy: type: object properties: version: type: string enum: - '1' data: type: array items: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - agent id: type: string access: type: array items: type: string enum: - read_messages - write_messages - read_agent - write_agent required: - type - id - access required: - version - data token: type: string hostname: type: string expiresAt: type: string required: - policy - token - hostname - expiresAt hasNextPage: type: boolean required: - tokens - hasNextPage '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message /v1/client-side-access-tokens/{token}: delete: description: Delete a client side access token. summary: Delete Token (Cloud-only) tags: - Client-Side Access Tokens parameters: - name: token in: path required: true schema: type: string description: The access token to delete operationId: clientSideAccessTokens.deleteClientSideAccessToken requestBody: description: Body content: application/json: schema: {} responses: '204': description: '204' content: application/json: schema: {} '400': description: '400' content: application/json: schema: type: object properties: message: type: string required: - message /v1/projects: get: description: List all projects summary: List Projects (Cloud-only) tags: - Projects parameters: - name: name in: query schema: type: string - name: offset in: query schema: oneOf: - type: string - type: number - name: limit in: query schema: type: string operationId: projects.listProjects responses: '200': description: '200' content: application/json: schema: type: object properties: projects: type: array items: type: object properties: name: type: string slug: type: string id: type: string required: - name - slug - id hasNextPage: type: boolean required: - projects - hasNextPage post: description: Create a new project summary: Create Project (Cloud-only) tags: - Projects parameters: [] operationId: projects.createProject requestBody: description: Body content: application/json: schema: type: object properties: name: type: string minLength: 3 maxLength: 50 required: - name responses: '201': description: '201' content: application/json: schema: type: object properties: name: type: string slug: type: string id: type: string required: - name - slug - id /v1/projects/{projectId}: delete: description: Delete a project by ID summary: Delete Project (Cloud-only) tags: - Projects parameters: - name: projectId in: path required: true schema: type: string format: uuid operationId: projects.deleteProject requestBody: description: Body content: application/json: schema: nullable: true responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success /v1/metadata/balance: get: description: Retrieve the current usage balances for the organization. summary: Retrieve Current Organization Balance tags: - Metadata parameters: [] operationId: metadata.retrieveCurrentBalances responses: '200': description: '200' content: application/json: schema: type: object properties: total_balance: type: number monthly_credit_balance: type: number purchased_credit_balance: type: number billing_tier: type: string required: - total_balance - monthly_credit_balance - purchased_credit_balance - billing_tier /v1/metadata/feedback: post: description: Send feedback from users to improve our services. summary: Send User Feedback tags: - Metadata parameters: [] operationId: metadata.sendFeedback requestBody: description: Body content: application/json: schema: type: object properties: message: type: string minLength: 1 maxLength: 10000 feature: default: letta-code type: string enum: - letta-code - sdk agent_id: type: string session_id: type: string version: type: string platform: type: string settings: type: string local_time: type: string device_type: type: string cwd: type: string total_api_ms: type: number total_wall_ms: type: number step_count: type: number prompt_tokens: type: number completion_tokens: type: number total_tokens: type: number cached_input_tokens: type: number cache_write_tokens: type: number reasoning_tokens: type: number context_tokens: type: number agent_name: type: string agent_description: type: string model: type: string billing_tier: type: string recent_chunks: type: array items: type: object additionalProperties: {} debug_log_tail: type: string required: - message responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success /v1/metadata/telemetry: post: description: Send telemetry events for usage tracking and analysis. summary: Send Telemetry Event tags: - Metadata parameters: [] operationId: metadata.sendTelemetry requestBody: description: Body content: application/json: schema: type: object properties: service: type: string enum: - letta-code server_version: type: string events: type: array items: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - session_start timestamp: type: string data: type: object properties: session_id: type: string agent_id: type: string surface: type: string startup_command: type: string version: type: string platform: type: string node_version: type: string required: - session_id - startup_command required: - type - timestamp - data - type: object properties: type: type: string enum: - session_end timestamp: type: string data: type: object properties: session_id: type: string agent_id: type: string surface: type: string duration: type: number message_count: type: number tool_call_count: type: number exit_reason: type: string total_api_ms: type: number total_wall_ms: type: number prompt_tokens: type: number completion_tokens: type: number total_tokens: type: number cached_tokens: type: number reasoning_tokens: type: number step_count: type: number required: - session_id - duration - message_count - tool_call_count required: - type - timestamp - data - type: object properties: type: type: string enum: - tool_usage timestamp: type: string data: type: object properties: session_id: type: string agent_id: type: string surface: type: string tool_name: type: string success: type: boolean duration: type: number response_length: type: number error_type: type: string stderr: type: string required: - session_id - tool_name - success - duration required: - type - timestamp - data - type: object properties: type: type: string enum: - error timestamp: type: string data: type: object properties: session_id: type: string agent_id: type: string run_id: type: string error_type: type: string error_message: type: string context: type: string http_status: type: number model_id: type: string surface: type: string recent_chunks: type: array items: type: object additionalProperties: {} debug_log_tail: type: string required: - session_id - error_type - error_message required: - type - timestamp - data - type: object properties: type: type: string enum: - user_input timestamp: type: string data: type: object properties: session_id: type: string agent_id: type: string surface: type: string input_length: type: number is_command: type: boolean command_name: type: string message_type: type: string model_id: type: string required: - session_id - input_length - is_command - message_type - model_id required: - type - timestamp - data minItems: 1 required: - service - events responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success /v1/metadata/status: get: summary: Gets Your Letta Cloud Status tags: - Metadata parameters: [] operationId: metadata.getStatus responses: '200': description: '200' content: application/json: schema: type: object properties: current_project_id: type: string nullable: true required: - current_project_id /v1/metadata/user: get: description: Retrieve information about the current authenticated user including email, name, organization, and current project. summary: Get Current User Information tags: - Metadata parameters: [] operationId: metadata.getUser responses: '200': description: '200' content: application/json: schema: type: object properties: id: type: string email: type: string name: type: string organization_name: type: string organization_id: type: string current_project_name: type: string nullable: true current_project_id: type: string nullable: true billing_tier: type: string remaining_credits: type: number required: - id - email - name - organization_name - organization_id - current_project_name - current_project_id - billing_tier - remaining_credits '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message /v1/agents/{agent_id}/schedule: post: description: Schedule a message to be sent by the agent at a specified time or on a recurring basis. summary: Schedule Agent Message tags: - Scheduled Messages parameters: - name: agent_id in: path required: true schema: type: string operationId: scheduledMessages.scheduleAgentMessage requestBody: description: Body content: application/json: schema: type: object properties: messages: type: array items: type: object properties: content: oneOf: - type: array items: oneOf: - type: object properties: text: type: string signature: type: string nullable: true type: type: string enum: - text required: - text - type: object properties: source: type: object properties: data: type: string media_type: type: string detail: type: string type: type: string enum: - base64 required: - data - media_type type: type: string enum: - image required: - source - type - type: string role: type: string enum: - user - assistant - system name: type: string otid: type: string sender_id: type: string type: type: string enum: - message required: - content - role max_steps: type: number callback_url: type: string format: uri include_return_message_types: type: array items: type: string enum: - system_message - user_message - assistant_message - reasoning_message - hidden_reasoning_message - tool_call_message - tool_return_message - approval_request_message - approval_response_message schedule: oneOf: - type: object properties: type: type: string enum: - one-time scheduled_at: type: number required: - scheduled_at - type: object properties: type: type: string enum: - recurring cron_expression: type: string required: - type - cron_expression required: - messages - schedule responses: '201': description: '201' content: application/json: schema: type: object properties: id: type: string next_scheduled_at: type: string required: - id get: description: List all scheduled messages for a specific agent. summary: List Scheduled Agent Messages tags: - Scheduled Messages parameters: - name: agent_id in: path required: true schema: type: string - name: limit in: query schema: type: string - name: after in: query schema: type: string operationId: scheduledMessages.listScheduledMessages responses: '200': description: '200' content: application/json: schema: type: object properties: scheduled_messages: type: array items: type: object properties: id: type: string agent_id: type: string message: type: object properties: messages: type: array items: type: object properties: content: oneOf: - type: array items: oneOf: - type: object properties: text: type: string signature: type: string nullable: true type: type: string enum: - text required: - text - type: object properties: source: type: object properties: data: type: string media_type: type: string detail: type: string type: type: string enum: - base64 required: - data - media_type type: type: string enum: - image required: - source - type - type: string role: type: string enum: - user - assistant - system name: type: string otid: type: string sender_id: type: string type: type: string enum: - message required: - content - role max_steps: type: number callback_url: type: string format: uri include_return_message_types: type: array items: type: string enum: - system_message - user_message - assistant_message - reasoning_message - hidden_reasoning_message - tool_call_message - tool_return_message - approval_request_message - approval_response_message required: - messages schedule: oneOf: - type: object properties: type: type: string enum: - one-time scheduled_at: type: number required: - scheduled_at - type: object properties: type: type: string enum: - recurring cron_expression: type: string required: - type - cron_expression next_scheduled_time: type: string nullable: true required: - id - agent_id - message - schedule - next_scheduled_time has_next_page: type: boolean required: - scheduled_messages - has_next_page /v1/agents/{agent_id}/schedule/{scheduled_message_id}: delete: description: Delete a scheduled message by its ID for a specific agent. summary: Delete Scheduled Agent Message tags: - Scheduled Messages parameters: - name: agent_id in: path required: true schema: type: string - name: scheduled_message_id in: path required: true schema: type: string operationId: scheduledMessages.deleteScheduledMessage requestBody: description: Body content: application/json: schema: type: object properties: {} nullable: true responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean enum: - true required: - success get: description: Retrieve a scheduled message by its ID for a specific agent. summary: Retrieve Scheduled Agent Message tags: - Scheduled Messages parameters: - name: agent_id in: path required: true schema: type: string - name: scheduled_message_id in: path required: true schema: type: string operationId: scheduledMessages.retrieveScheduledMessage responses: '200': description: '200' content: application/json: schema: type: object properties: id: type: string agent_id: type: string message: type: object properties: messages: type: array items: type: object properties: content: oneOf: - type: array items: oneOf: - type: object properties: text: type: string signature: type: string nullable: true type: type: string enum: - text required: - text - type: object properties: source: type: object properties: data: type: string media_type: type: string detail: type: string type: type: string enum: - base64 required: - data - media_type type: type: string enum: - image required: - source - type - type: string role: type: string enum: - user - assistant - system name: type: string otid: type: string sender_id: type: string type: type: string enum: - message required: - content - role max_steps: type: number callback_url: type: string format: uri include_return_message_types: type: array items: type: string enum: - system_message - user_message - assistant_message - reasoning_message - hidden_reasoning_message - tool_call_message - tool_return_message - approval_request_message - approval_response_message required: - messages schedule: oneOf: - type: object properties: type: type: string enum: - one-time scheduled_at: type: number required: - scheduled_at - type: object properties: type: type: string enum: - recurring cron_expression: type: string required: - type - cron_expression next_scheduled_time: type: string nullable: true required: - id - agent_id - message - schedule - next_scheduled_time /v1/feeds: post: description: Create a new feed in a project summary: Create Feed tags: - Feeds parameters: [] operationId: feeds.createFeed requestBody: description: Body content: application/json: schema: type: object properties: project_id: type: string name: type: string minLength: 1 maxLength: 100 description: type: string maxLength: 500 required: - project_id - name responses: '201': description: '201' content: application/json: schema: type: object properties: id: type: string name: type: string description: type: string nullable: true project_id: type: string organization_id: type: string created_by_id: type: string nullable: true created_at: type: string updated_at: type: string required: - id - name - description - project_id - organization_id - created_by_id - created_at - updated_at get: description: List all feeds with optional filters and pagination summary: List Feeds tags: - Feeds parameters: - name: project_id in: query schema: type: string - name: name in: query schema: type: string - name: limit in: query schema: type: string - name: offset in: query schema: oneOf: - type: string - type: number operationId: feeds.listFeeds responses: '200': description: '200' content: application/json: schema: type: object properties: feeds: type: array items: type: object properties: id: type: string name: type: string description: type: string nullable: true project_id: type: string organization_id: type: string created_at: type: string updated_at: type: string subscriptions_count: type: number required: - id - name - description - project_id - organization_id - created_at - updated_at - subscriptions_count has_next_page: type: boolean required: - feeds - has_next_page /v1/feeds/{feed_id}: get: description: Retrieve feed details by ID summary: Get Feed tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string operationId: feeds.getFeed responses: '200': description: '200' content: application/json: schema: type: object properties: id: type: string name: type: string description: type: string nullable: true project_id: type: string organization_id: type: string created_by_id: type: string nullable: true created_at: type: string updated_at: type: string subscriptions_count: type: number messages_count: type: number required: - id - name - description - project_id - organization_id - created_by_id - created_at - updated_at - subscriptions_count delete: description: Soft delete a feed and clean up its sequence summary: Delete Feed tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string operationId: feeds.deleteFeed requestBody: description: Body content: application/json: schema: type: object properties: {} nullable: true responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success /v1/feeds/{feed_id}/messages: post: description: Batch insert messages into a feed (up to 10,000 per request) summary: Publish Messages tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string operationId: feeds.publishMessages requestBody: description: Body content: application/json: schema: type: object properties: messages: type: array items: type: object properties: content: type: string required: - content minItems: 1 maxItems: 10000 required: - messages responses: '201': description: '201' content: application/json: schema: type: object properties: inserted_count: type: number required: - inserted_count get: description: List messages from a feed (for debugging/inspection) summary: List Feed Messages tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string - name: after_sequence in: query schema: type: string - name: limit in: query schema: type: string operationId: feeds.listMessages responses: '200': description: '200' content: application/json: schema: type: object properties: messages: type: array items: type: object properties: id: type: string feed_id: type: string sequence: type: number content_preview: type: string is_truncated: type: boolean content_size_bytes: type: number expires_at: type: string created_at: type: string required: - id - feed_id - sequence - content_preview - is_truncated - content_size_bytes - expires_at - created_at has_next_page: type: boolean next_cursor: type: number nullable: true required: - messages - has_next_page - next_cursor /v1/feeds/{feed_id}/messages/{message_id}: get: description: Get full content of a feed message summary: Get Feed Message tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string - name: message_id in: path required: true schema: type: string operationId: feeds.getMessage responses: '200': description: '200' content: application/json: schema: type: object properties: message: type: object properties: id: type: string feed_id: type: string sequence: type: number content: type: string content_size_bytes: type: number expires_at: type: string created_at: type: string required: - id - feed_id - sequence - content - content_size_bytes - expires_at - created_at required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message /v1/feeds/{feed_id}/subscribe: post: description: Subscribe an agent to a feed with polling configuration summary: Subscribe Agent to Feed tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string operationId: feeds.subscribeAgent requestBody: description: Body content: application/json: schema: type: object properties: agent_id: type: string cron_schedule: type: string prompt_template: type: string required: - agent_id - cron_schedule responses: '201': description: '201' content: application/json: schema: type: object properties: id: type: string feed_id: type: string agent_id: type: string agent_name: type: string nullable: true cron_schedule: type: string merge_strategy: type: string enum: - unique-messages - combine-into-single-message prompt_template: type: string nullable: true next_scheduled_at: type: string last_consumed_sequence: type: number last_consumed_at: type: string nullable: true disabled_at: type: string nullable: true created_at: type: string required: - id - feed_id - agent_id - agent_name - cron_schedule - merge_strategy - prompt_template - next_scheduled_at - last_consumed_sequence - last_consumed_at - disabled_at - created_at '400': description: '400' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - agentAlreadySubscribed - agentNotInProject - invalidCronExpression required: - message - errorCode /v1/feeds/{feed_id}/subscriptions/{subscription_id}: patch: description: Update subscription configuration (cron schedule, enable/disable) summary: Update Subscription tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string - name: subscription_id in: path required: true schema: type: string operationId: feeds.updateSubscription requestBody: description: Body content: application/json: schema: type: object properties: cron_schedule: type: string prompt_template: type: string disabled: type: boolean responses: '200': description: '200' content: application/json: schema: type: object properties: id: type: string feed_id: type: string agent_id: type: string agent_name: type: string nullable: true cron_schedule: type: string merge_strategy: type: string enum: - unique-messages - combine-into-single-message prompt_template: type: string nullable: true next_scheduled_at: type: string last_consumed_sequence: type: number last_consumed_at: type: string nullable: true disabled_at: type: string nullable: true created_at: type: string updated_at: type: string required: - id - feed_id - agent_id - agent_name - cron_schedule - merge_strategy - prompt_template - next_scheduled_at - last_consumed_sequence - last_consumed_at - disabled_at - created_at - updated_at delete: description: Remove agent subscription from a feed (by subscription_id) summary: Delete Subscription tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string - name: subscription_id in: path required: true schema: type: string operationId: feeds.deleteSubscription requestBody: description: Body content: application/json: schema: type: object properties: {} nullable: true responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success /v1/feeds/{feed_id}/unsubscribe: post: description: Remove agent subscription from a feed (by agent_id) summary: Unsubscribe Agent from Feed tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string operationId: feeds.unsubscribeAgent requestBody: description: Body content: application/json: schema: type: object properties: agent_id: type: string required: - agent_id responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success /v1/feeds/{feed_id}/subscriptions/{subscription_id}/trigger: post: description: Immediately trigger a subscription to process pending messages summary: Trigger Subscription tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string - name: subscription_id in: path required: true schema: type: string operationId: feeds.triggerSubscription requestBody: description: Body content: application/json: schema: type: object properties: {} responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean messages_sent: type: number required: - success - messages_sent '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message /v1/feeds/{feed_id}/subscriptions/{subscription_id}/backfill: post: description: Start a background job to send historical messages to an agent subscription. Returns immediately with workflow ID. Does not update last_consumed_sequence. summary: Backfill Subscription tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string - name: subscription_id in: path required: true schema: type: string operationId: feeds.backfillSubscription requestBody: description: Body content: application/json: schema: type: object properties: from_sequence: type: number to_sequence: type: number responses: '200': description: '200' content: application/json: schema: type: object properties: workflow_id: type: string required: - workflow_id '404': description: '404' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - feedNotFound - subscriptionNotFound required: - message - errorCode /v1/feeds/{feed_id}/subscriptions/{subscription_id}/history: get: description: List the run history for a subscription including scheduled runs, manual triggers, and backfills. summary: List Subscription History tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string - name: subscription_id in: path required: true schema: type: string - name: page_size in: query schema: type: string - name: next_page_token in: query schema: type: string operationId: feeds.listSubscriptionHistory responses: '200': description: '200' content: application/json: schema: type: object properties: runs: type: array items: type: object properties: workflow_id: type: string type: type: string enum: - scheduled - manual - backfill status: type: string enum: - running - completed - failed - canceled - timed_out started_at: type: string completed_at: type: string nullable: true required: - workflow_id - type - status - started_at - completed_at next_page_token: type: string nullable: true required: - runs - next_page_token '404': description: '404' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - feedNotFound - subscriptionNotFound required: - message - errorCode /v1/feeds/{feed_id}/subscriptions/cron: patch: description: Update the cron schedule for all subscriptions of a feed summary: Update All Subscriptions Cron Schedule tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string operationId: feeds.updateAllSubscriptionsCron requestBody: description: Body content: application/json: schema: type: object properties: cron_schedule: type: string required: - cron_schedule responses: '200': description: '200' content: application/json: schema: type: object properties: updated_count: type: number required: - updated_count '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message /v1/feeds/{feed_id}/subscriptions: get: description: List all agent subscriptions for a feed summary: List Feed Subscriptions tags: - Feeds parameters: - name: feed_id in: path required: true schema: type: string - name: limit in: query schema: type: string - name: offset in: query schema: oneOf: - type: string - type: number - name: agent_id in: query schema: type: string operationId: feeds.listSubscriptions responses: '200': description: '200' content: application/json: schema: type: object properties: subscriptions: type: array items: type: object properties: id: type: string feed_id: type: string agent_id: type: string agent_name: type: string nullable: true cron_schedule: type: string merge_strategy: type: string enum: - unique-messages - combine-into-single-message prompt_template: type: string nullable: true next_scheduled_at: type: string last_consumed_sequence: type: number last_consumed_at: type: string nullable: true disabled_at: type: string nullable: true created_at: type: string updated_at: type: string required: - id - feed_id - agent_id - agent_name - cron_schedule - merge_strategy - prompt_template - next_scheduled_at - last_consumed_sequence - last_consumed_at - disabled_at - created_at - updated_at has_next_page: type: boolean required: - subscriptions - has_next_page /v1/agents/{agent_id}/memory-files/directory: get: description: List immediate children of a directory in the agent memory repo (single level). summary: List Directory tags: - Memory Files parameters: - name: agent_id in: path required: true schema: type: string - name: path in: query description: Directory path to list. Empty for root. schema: type: string - name: depth in: query description: 'Depth of directory listing (default: 1).' schema: type: number nullable: true - name: ref in: query description: 'Git ref (default: HEAD).' schema: type: string operationId: memoryFiles.listDirectory responses: '200': description: '200' content: application/json: schema: type: object properties: path: type: string entries: type: array items: type: object properties: name: type: string type: type: string enum: - file - directory required: - name - type depth: type: number required: - path - entries - depth '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '501': description: '501' content: application/json: schema: type: object properties: message: type: string required: - message /v1/agents/{agent_id}/memory-files/history: get: description: Get commit history for a specific file in the agent memory repo. summary: Get File History tags: - Memory Files parameters: - name: agent_id in: path required: true schema: type: string - name: file_path in: query description: Path to the file (e.g. "blocks/persona.md"). required: true schema: type: string - name: limit in: query description: 'Max commits to return (default: 50).' schema: type: number nullable: true operationId: memoryFiles.getFileHistory responses: '200': description: '200' content: application/json: schema: type: object properties: path: type: string commits: type: array items: type: object properties: sha: type: string message: type: string timestamp: type: string author_name: type: string nullable: true required: - sha - message - timestamp - author_name required: - path - commits '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '501': description: '501' content: application/json: schema: type: object properties: message: type: string required: - message /v1/agents/{agent_id}/memory-files/content: get: description: Read a single file content at a specific git ref from the agent memory repo. summary: Read File Content tags: - Memory Files parameters: - name: agent_id in: path required: true schema: type: string - name: file_path in: query description: Path to the file (e.g. "blocks/persona.md"). required: true schema: type: string - name: ref in: query description: 'Git ref (default: HEAD).' schema: type: string operationId: memoryFiles.readFileContent responses: '200': description: '200' content: application/json: schema: type: object properties: path: type: string content: type: string ref: type: string required: - path - content - ref '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '501': description: '501' content: application/json: schema: type: object properties: message: type: string required: - message /v1/pipelines: post: description: Create a new pipeline (producer + feed + optionally subscribers) summary: Create Pipeline tags: - Pipelines parameters: [] operationId: pipelines.createPipeline requestBody: description: Body content: application/json: schema: type: object properties: name: type: string project_id: type: string integration_type: type: string enum: - slack - discord - microsoftTeams - custom_webhook producer_config: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - slack_channel_reader data: type: object properties: channels: type: array items: type: object properties: channel_id: type: string channel_name: type: string last_message_ts: type: string required: - channel_id minItems: 1 maxItems: 100 max_messages_per_poll: type: number required: - channels required: - type - data - type: object properties: type: type: string enum: - custom_webhook data: type: object properties: {} required: - type - data subscriber_agent_ids: type: array items: type: string subscriber_cron_schedule: type: string prompt_template: type: string required: - name - project_id - integration_type - producer_config responses: '200': description: '200' content: application/json: schema: type: object properties: pipeline: type: object properties: id: type: string name: type: string organization_id: type: string project_id: type: string integration_id: type: string nullable: true integration_type: type: string enum: - slack - discord - microsoftTeams - custom_webhook feed_id: type: string config: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - slack_channel_reader data: type: object properties: channels: type: array items: type: object properties: channel_id: type: string channel_name: type: string last_message_ts: type: string required: - channel_id minItems: 1 maxItems: 100 max_messages_per_poll: type: number required: - channels required: - type - data - type: object properties: type: type: string enum: - custom_webhook data: type: object properties: {} required: - type - data next_scheduled_at: type: string format: date-time nullable: true last_run_at: type: string format: date-time nullable: true disabled_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time integration_display_name: type: string nullable: true feed_name: type: string subscriber_count: type: number error_count: type: number project_name: type: string project_slug: type: string required: - id - name - organization_id - project_id - integration_id - integration_type - feed_id - config - next_scheduled_at - last_run_at - disabled_at - created_at - updated_at required: - pipeline '400': description: '400' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - integrationNotFound - invalidProducerConfig - agentNotFound required: - message - errorCode get: description: List all pipelines for the organization with optional filtering summary: List Pipelines tags: - Pipelines parameters: - name: search in: query schema: type: string - name: integration_type in: query schema: type: string - name: integration_id in: query schema: type: string - name: offset in: query schema: oneOf: - type: string - type: number - name: limit in: query schema: type: string operationId: pipelines.listPipelines responses: '200': description: '200' content: application/json: schema: type: object properties: pipelines: type: array items: type: object properties: id: type: string name: type: string organization_id: type: string project_id: type: string integration_id: type: string nullable: true integration_type: type: string enum: - slack - discord - microsoftTeams - custom_webhook feed_id: type: string config: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - slack_channel_reader data: type: object properties: channels: type: array items: type: object properties: channel_id: type: string channel_name: type: string last_message_ts: type: string required: - channel_id minItems: 1 maxItems: 100 max_messages_per_poll: type: number required: - channels required: - type - data - type: object properties: type: type: string enum: - custom_webhook data: type: object properties: {} required: - type - data next_scheduled_at: type: string format: date-time nullable: true last_run_at: type: string format: date-time nullable: true disabled_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time integration_display_name: type: string nullable: true feed_name: type: string subscriber_count: type: number error_count: type: number project_name: type: string project_slug: type: string required: - id - name - organization_id - project_id - integration_id - integration_type - feed_id - config - next_scheduled_at - last_run_at - disabled_at - created_at - updated_at hasNextPage: type: boolean required: - pipelines - hasNextPage /v1/pipelines/count: get: description: Get the total count of pipelines, optionally filtered by project and search summary: Count Pipelines tags: - Pipelines parameters: - name: search in: query schema: type: string - name: integration_type in: query schema: type: string - name: integration_id in: query schema: type: string operationId: pipelines.countPipelines responses: '200': description: '200' content: application/json: schema: type: object properties: count: type: number required: - count /v1/pipelines/{pipeline_id}: get: description: Get a single pipeline with details summary: Get Pipeline tags: - Pipelines parameters: - name: pipeline_id in: path required: true schema: type: string operationId: pipelines.getPipeline responses: '200': description: '200' content: application/json: schema: type: object properties: pipeline: type: object properties: id: type: string name: type: string organization_id: type: string project_id: type: string integration_id: type: string nullable: true integration_type: type: string enum: - slack - discord - microsoftTeams - custom_webhook feed_id: type: string config: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - slack_channel_reader data: type: object properties: channels: type: array items: type: object properties: channel_id: type: string channel_name: type: string last_message_ts: type: string required: - channel_id minItems: 1 maxItems: 100 max_messages_per_poll: type: number required: - channels required: - type - data - type: object properties: type: type: string enum: - custom_webhook data: type: object properties: {} required: - type - data next_scheduled_at: type: string format: date-time nullable: true last_run_at: type: string format: date-time nullable: true disabled_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time integration_display_name: type: string nullable: true feed_name: type: string subscriber_count: type: number error_count: type: number project_name: type: string project_slug: type: string required: - id - name - organization_id - project_id - integration_id - integration_type - feed_id - config - next_scheduled_at - last_run_at - disabled_at - created_at - updated_at required: - pipeline '404': description: '404' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - pipelineNotFound required: - message - errorCode patch: description: Update pipeline name or disable/enable it summary: Update Pipeline tags: - Pipelines parameters: - name: pipeline_id in: path required: true schema: type: string operationId: pipelines.updatePipeline requestBody: description: Body content: application/json: schema: type: object properties: name: type: string disabled: type: boolean responses: '200': description: '200' content: application/json: schema: type: object properties: pipeline: type: object properties: id: type: string name: type: string organization_id: type: string project_id: type: string integration_id: type: string nullable: true integration_type: type: string enum: - slack - discord - microsoftTeams - custom_webhook feed_id: type: string config: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - slack_channel_reader data: type: object properties: channels: type: array items: type: object properties: channel_id: type: string channel_name: type: string last_message_ts: type: string required: - channel_id minItems: 1 maxItems: 100 max_messages_per_poll: type: number required: - channels required: - type - data - type: object properties: type: type: string enum: - custom_webhook data: type: object properties: {} required: - type - data next_scheduled_at: type: string format: date-time nullable: true last_run_at: type: string format: date-time nullable: true disabled_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time integration_display_name: type: string nullable: true feed_name: type: string subscriber_count: type: number error_count: type: number project_name: type: string project_slug: type: string required: - id - name - organization_id - project_id - integration_id - integration_type - feed_id - config - next_scheduled_at - last_run_at - disabled_at - created_at - updated_at required: - pipeline '404': description: '404' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - pipelineNotFound required: - message delete: description: Soft delete a pipeline and cascade to feed + subscriptions summary: Delete Pipeline tags: - Pipelines parameters: - name: pipeline_id in: path required: true schema: type: string operationId: pipelines.deletePipeline requestBody: description: Body content: application/json: schema: type: object properties: {} responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean required: - success '404': description: '404' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - pipelineNotFound required: - message /v1/pipelines/{pipeline_id}/config: patch: description: Update the producer configuration for a pipeline (e.g., Slack channels) summary: Update Pipeline Producer Config tags: - Pipelines parameters: - name: pipeline_id in: path required: true schema: type: string operationId: pipelines.updatePipelineProducerConfig requestBody: description: Body content: application/json: schema: type: object properties: producer_config: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - slack_channel_reader data: type: object properties: channels: type: array items: type: object properties: channel_id: type: string channel_name: type: string last_message_ts: type: string required: - channel_id minItems: 1 maxItems: 100 max_messages_per_poll: type: number required: - channels required: - type - data - type: object properties: type: type: string enum: - custom_webhook data: type: object properties: {} required: - type - data required: - producer_config responses: '200': description: '200' content: application/json: schema: type: object properties: pipeline: type: object properties: id: type: string name: type: string organization_id: type: string project_id: type: string integration_id: type: string nullable: true integration_type: type: string enum: - slack - discord - microsoftTeams - custom_webhook feed_id: type: string config: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - slack_channel_reader data: type: object properties: channels: type: array items: type: object properties: channel_id: type: string channel_name: type: string last_message_ts: type: string required: - channel_id minItems: 1 maxItems: 100 max_messages_per_poll: type: number required: - channels required: - type - data - type: object properties: type: type: string enum: - custom_webhook data: type: object properties: {} required: - type - data next_scheduled_at: type: string format: date-time nullable: true last_run_at: type: string format: date-time nullable: true disabled_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time integration_display_name: type: string nullable: true feed_name: type: string subscriber_count: type: number error_count: type: number project_name: type: string project_slug: type: string required: - id - name - organization_id - project_id - integration_id - integration_type - feed_id - config - next_scheduled_at - last_run_at - disabled_at - created_at - updated_at required: - pipeline '400': description: '400' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - invalidProducerConfig - configTypeMismatch required: - message - errorCode '404': description: '404' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - pipelineNotFound required: - message - errorCode /v1/pipelines/preview: post: description: Fetch sample messages from integration to preview what agents will receive summary: Preview Pipeline tags: - Pipelines parameters: [] operationId: pipelines.previewPipeline requestBody: description: Body content: application/json: schema: type: object properties: integration_type: type: string enum: - slack - discord - microsoftTeams - custom_webhook integration_id: type: string producer_config: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - slack_channel_reader data: type: object properties: channels: type: array items: type: object properties: channel_id: type: string channel_name: type: string last_message_ts: type: string required: - channel_id minItems: 1 maxItems: 100 max_messages_per_poll: type: number required: - channels required: - type - data - type: object properties: type: type: string enum: - custom_webhook data: type: object properties: {} required: - type - data required: - integration_type - integration_id - producer_config responses: '200': description: '200' content: application/json: schema: type: object properties: sampleMessages: type: array items: type: string messageCount: type: number required: - sampleMessages - messageCount '400': description: '400' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - integrationNotFound - invalidProducerConfig - tokenExpired required: - message /v1/pipelines/{pipeline_id}/sync: post: description: Manually trigger a pipeline sync to fetch new messages immediately summary: Sync Pipeline tags: - Pipelines parameters: - name: pipeline_id in: path required: true schema: type: string operationId: pipelines.syncPipeline requestBody: description: Body content: application/json: schema: type: object properties: {} responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean messages_ingested: type: number workflow_id: type: string required: - success - messages_ingested - workflow_id '400': description: '400' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - pipelineDisabled - pipelineNotSyncable - syncFailed required: - message - errorCode '404': description: '404' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - pipelineNotFound required: - message - errorCode /v1/pipelines/{pipeline_id}/sync/history: get: description: List the sync run history for a pipeline from Temporal with error details summary: List Pipeline Sync History tags: - Pipelines parameters: - name: pipeline_id in: path required: true schema: type: string operationId: pipelines.listPipelineSyncHistory responses: '200': description: '200' content: application/json: schema: type: object properties: runs: type: array items: type: object properties: workflow_id: type: string status: type: string enum: - running - completed - failed - canceled - timed_out started_at: type: string format: date-time completed_at: type: string format: date-time nullable: true error: type: object properties: error_type: type: string error_message: type: string required: - error_type - error_message nullable: true required: - workflow_id - status - started_at - completed_at - error next_page_token: type: string nullable: true required: - runs - next_page_token '404': description: '404' content: application/json: schema: type: object properties: message: type: string errorCode: type: string enum: - pipelineNotFound required: - message - errorCode /v1/environments/register: post: description: Register a new listener connection and get connectionId for WebSocket summary: Register Environment tags: - Environments parameters: [] operationId: environments.register requestBody: description: Body content: application/json: schema: type: object properties: deviceId: type: string connectionName: type: string metadata: type: object properties: os: type: string lettaCodeVersion: type: string nodeVersion: type: string workingDirectory: type: string gitBranch: type: string additionalProperties: true required: - deviceId - connectionName responses: '200': description: '200' content: application/json: schema: type: object properties: connectionId: type: string wsUrl: type: string required: - connectionId - wsUrl '400': description: '400' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message /v1/environments/{deviceId}: get: description: Get a specific environment connection by deviceId summary: Get Environment Connection tags: - Environments parameters: - name: deviceId in: path required: true schema: type: string operationId: environments.getConnection responses: '200': description: '200' content: application/json: schema: type: object properties: id: type: string connectionId: type: string nullable: true deviceId: type: string connectionName: type: string organizationId: type: string userId: type: string apiKeyOwner: type: string podId: type: string nullable: true connectedAt: type: number nullable: true lastHeartbeat: type: number nullable: true lastSeenAt: type: number firstSeenAt: type: number currentMode: type: string enum: - default - acceptEdits - plan - bypassPermissions metadata: type: object properties: os: type: string lettaCodeVersion: type: string nodeVersion: type: string workingDirectory: type: string gitBranch: type: string additionalProperties: true required: - id - connectionId - deviceId - connectionName - organizationId - podId - connectedAt - lastHeartbeat - lastSeenAt - firstSeenAt '404': description: '404' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message /v1/environments: get: description: List all active environment connections for the organization summary: List Environment Connections tags: - Environments parameters: - name: limit in: query schema: type: string - name: after in: query schema: type: string - name: userId in: query schema: type: string - name: onlineOnly in: query schema: type: string operationId: environments.listConnections responses: '200': description: '200' content: application/json: schema: type: object properties: connections: type: array items: type: object properties: id: type: string connectionId: type: string nullable: true deviceId: type: string connectionName: type: string organizationId: type: string userId: type: string apiKeyOwner: type: string podId: type: string nullable: true connectedAt: type: number nullable: true lastHeartbeat: type: number nullable: true lastSeenAt: type: number firstSeenAt: type: number currentMode: type: string enum: - default - acceptEdits - plan - bypassPermissions metadata: type: object properties: os: type: string lettaCodeVersion: type: string nodeVersion: type: string workingDirectory: type: string gitBranch: type: string additionalProperties: true required: - id - connectionId - deviceId - connectionName - organizationId - podId - connectedAt - lastHeartbeat - lastSeenAt - firstSeenAt hasNextPage: type: boolean required: - connections - hasNextPage /v1/environments/{connectionId}/messages: post: description: Send a message to a specific environment connection summary: Send Message to Environment tags: - Environments parameters: - name: connectionId in: path required: true schema: type: string operationId: environments.sendMessage requestBody: description: Body content: application/json: schema: type: object properties: messages: type: array items: oneOf: - type: object properties: role: type: string enum: - user content: oneOf: - type: string - type: array items: type: object properties: type: type: string enum: - text text: type: string required: - type - text client_message_id: type: string otid: type: string required: - role - content - client_message_id - type: object properties: type: type: string enum: - approval approvals: type: array items: oneOf: - type: object properties: type: type: string enum: - tool tool_call_id: type: string tool_return: oneOf: - type: string - type: array items: type: object properties: type: type: string enum: - text text: type: string required: - type - text status: type: string enum: - success - error stdout: type: array items: type: string nullable: true stderr: type: array items: type: string nullable: true required: - tool_call_id - tool_return - status - type: object properties: type: type: string enum: - approval approve: type: boolean tool_call_id: type: string reason: type: string nullable: true updated_input: type: object additionalProperties: {} nullable: true required: - approve - tool_call_id required: - type - approvals agentId: type: string conversationId: type: string nullable: true required: - messages responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success - message '400': description: '400' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message '404': description: '404' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message '503': description: '503' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message /v1/environments/{id}: delete: description: Removes environment from list of environments summary: Delete Environment tags: - Environments parameters: - name: id in: path required: true schema: type: string operationId: environments.deleteEnvironment requestBody: description: Body content: application/json: schema: type: object properties: {} nullable: true responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success - message '403': description: '403' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message '404': description: '404' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message /v1/sandboxes: post: description: Create a new Modal Sandbox that runs letta remote automatically summary: Create Sandbox tags: - Sandboxes parameters: [] operationId: sandboxes.createSandbox requestBody: description: Body content: application/json: schema: type: object properties: agentId: type: string connectionName: type: string required: - agentId responses: '200': description: '200' content: application/json: schema: type: object properties: sandboxId: type: string deviceId: type: string connectionName: type: string required: - sandboxId - deviceId - connectionName '400': description: '400' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message '500': description: '500' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message get: description: List all sandboxes for the organization summary: List Sandboxes tags: - Sandboxes parameters: - name: agentId in: query schema: type: string - name: limit in: query schema: type: string operationId: sandboxes.listSandboxes responses: '200': description: '200' content: application/json: schema: type: object properties: sandboxes: type: array items: type: object properties: id: type: string sandboxId: type: string agentId: type: string connectionName: type: string deviceId: type: string organizationId: type: string connectionId: type: string nullable: true podId: type: string nullable: true connectedAt: type: number nullable: true lastHeartbeat: type: number nullable: true lastSeenAt: type: number firstSeenAt: type: number currentMode: type: string enum: - default - acceptEdits - plan - bypassPermissions metadata: type: object properties: os: type: string lettaCodeVersion: type: string nodeVersion: type: string workingDirectory: type: string gitBranch: type: string additionalProperties: true required: - id - sandboxId - agentId - connectionName - deviceId - organizationId - connectionId - podId - connectedAt - lastHeartbeat - lastSeenAt - firstSeenAt required: - sandboxes /v1/sandboxes/{sandboxId}/terminate: post: description: Terminate a Modal Sandbox summary: Terminate Sandbox tags: - Sandboxes parameters: - name: sandboxId in: path required: true schema: type: string operationId: sandboxes.terminateSandbox requestBody: description: Body content: application/json: schema: type: object properties: {} nullable: true responses: '200': description: '200' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success - message '404': description: '404' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message '500': description: '500' content: application/json: schema: type: object properties: errorCode: type: string message: type: string required: - errorCode - message /v1/device-storage-key: get: description: Returns an HMAC-derived AES-256-GCM key scoped to the authenticated user and device. Used to encrypt/decrypt local IndexedDB caches on the client. summary: Get Device Storage Key tags: - Device Storage parameters: - name: deviceId in: query required: true schema: type: string operationId: deviceStorage.getDeviceStorageKey responses: '200': description: '200' content: application/json: schema: type: object properties: key: type: string required: - key components: schemas: 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 AgentFileAttachment: properties: id: type: string title: Id description: Unique identifier of the file-agent relationship file_id: type: string title: File Id description: Unique identifier of the file file_name: type: string title: File Name description: Name of the file folder_id: type: string title: Folder Id description: Unique identifier of the folder/source folder_name: type: string title: Folder Name description: Name of the folder/source is_open: type: boolean title: Is Open description: Whether the file is currently open in the agent's context last_accessed_at: anyOf: - type: string format: date-time - type: 'null' title: Last Accessed At description: Timestamp of last access by the agent visible_content: anyOf: - type: string - type: 'null' title: Visible Content description: Portion of the file visible to the agent if open start_line: anyOf: - type: integer - type: 'null' title: Start Line description: Starting line number if file was opened with line range end_line: anyOf: - type: integer - type: 'null' title: End Line description: Ending line number if file was opened with line range additionalProperties: false type: object required: - id - file_id - file_name - folder_id - folder_name - is_open title: AgentFileAttachment description: Response model for agent file attachments showing file status in agent context AgentFileSchema: properties: agents: items: $ref: '#/components/schemas/letta__schemas__agent_file__AgentSchema' type: array title: Agents description: List of agents in this agent file groups: items: $ref: '#/components/schemas/GroupSchema' type: array title: Groups description: List of groups in this agent file blocks: items: $ref: '#/components/schemas/BlockSchema' type: array title: Blocks description: List of memory blocks in this agent file files: items: $ref: '#/components/schemas/FileSchema' type: array title: Files description: List of files in this agent file sources: items: $ref: '#/components/schemas/SourceSchema' type: array title: Sources description: List of sources in this agent file tools: items: $ref: '#/components/schemas/letta__schemas__agent_file__ToolSchema' type: array title: Tools description: List of tools in this agent file mcp_servers: items: $ref: '#/components/schemas/MCPServerSchema' type: array title: Mcp Servers description: List of MCP servers in this agent file skills: items: $ref: '#/components/schemas/SkillSchema' type: array title: Skills description: List of skills in this agent file metadata: additionalProperties: type: string type: object title: Metadata description: Metadata for this agent file, including revision_id and other export information. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: The timestamp when the object was created. type: object required: - agents - groups - blocks - files - sources - tools - mcp_servers title: AgentFileSchema description: Schema for serialized agent file that can be exported to JSON and imported into agent server. AgentState: 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 title: Id description: The id of the agent. Assigned by the database. name: type: string title: Name description: The name of the agent. tool_rules: anyOf: - items: oneOf: - $ref: '#/components/schemas/ChildToolRule' - $ref: '#/components/schemas/InitToolRule' - $ref: '#/components/schemas/TerminalToolRule' - $ref: '#/components/schemas/ConditionalToolRule' - $ref: '#/components/schemas/ContinueToolRule' - $ref: '#/components/schemas/RequiredBeforeExitToolRule' - $ref: '#/components/schemas/MaxCountPerStepToolRule' - $ref: '#/components/schemas/ParentToolRule' - $ref: '#/components/schemas/RequiresApprovalToolRule' discriminator: propertyName: type mapping: conditional: '#/components/schemas/ConditionalToolRule' constrain_child_tools: '#/components/schemas/ChildToolRule' continue_loop: '#/components/schemas/ContinueToolRule' exit_loop: '#/components/schemas/TerminalToolRule' max_count_per_step: '#/components/schemas/MaxCountPerStepToolRule' parent_last_tool: '#/components/schemas/ParentToolRule' required_before_exit: '#/components/schemas/RequiredBeforeExitToolRule' requires_approval: '#/components/schemas/RequiresApprovalToolRule' run_first: '#/components/schemas/InitToolRule' type: array - type: 'null' title: Tool Rules description: The list of tool rules. message_ids: anyOf: - items: type: string type: array - type: 'null' title: Message Ids description: The ids of the messages in the agent's in-context memory. system: type: string title: System description: The system prompt used by the agent. agent_type: $ref: '#/components/schemas/AgentType' description: The type of agent. llm_config: $ref: '#/components/schemas/LLMConfig' description: 'Deprecated: Use `model` field instead. The LLM configuration used by the agent.' deprecated: true embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: 'Deprecated: Use `embedding` field instead. The embedding configuration used by the agent.' deprecated: true model: anyOf: - type: string - type: 'null' title: Model description: 'The model handle used by the agent (format: provider/model-name).' embedding: anyOf: - type: string - type: 'null' title: Embedding description: 'The embedding model handle used by the agent (format: provider/model-name).' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: The model settings used by the agent. compaction_settings: anyOf: - $ref: '#/components/schemas/CompactionSettings-Output' - type: 'null' description: The compaction settings configuration used for compaction. response_format: 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 Format description: The response format used by the agent description: anyOf: - type: string - type: 'null' title: Description description: The description of the agent. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: The metadata of the agent. memory: $ref: '#/components/schemas/Memory' description: 'Deprecated: Use `blocks` field instead. The in-context memory of the agent.' deprecated: true blocks: items: $ref: '#/components/schemas/Block' type: array title: Blocks description: The memory blocks used by the agent. tools: items: $ref: '#/components/schemas/Tool' type: array title: Tools description: The tools used by the agent. sources: items: $ref: '#/components/schemas/Source' type: array title: Sources description: 'Deprecated: Use `folders` field instead. The sources used by the agent.' deprecated: true tags: items: type: string type: array title: Tags description: The tags associated with the agent. tool_exec_environment_variables: items: $ref: '#/components/schemas/AgentEnvironmentVariable' type: array title: Tool Exec Environment Variables description: 'Deprecated: use `secrets` field instead.' deprecated: true secrets: items: $ref: '#/components/schemas/AgentEnvironmentVariable' type: array title: Secrets description: The environment variables for tool execution specific to this agent. project_id: anyOf: - type: string - type: 'null' title: Project Id description: The id of the project the agent belongs to. template_id: anyOf: - type: string - type: 'null' title: Template Id description: The id of the template the agent belongs to. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template id of the agent. deployment_id: anyOf: - type: string - type: 'null' title: Deployment Id description: The id of the deployment. entity_id: anyOf: - type: string - type: 'null' title: Entity Id description: The id of the entity within the template. identity_ids: items: type: string type: array title: Identity Ids description: 'Deprecated: Use `identities` field instead. The ids of the identities associated with this agent.' default: [] deprecated: true identities: items: $ref: '#/components/schemas/Identity' type: array title: Identities description: The identities associated with this agent. default: [] pending_approval: anyOf: - $ref: '#/components/schemas/ApprovalRequestMessage' - type: 'null' description: The latest approval request message pending for this agent, if any. message_buffer_autoclear: type: boolean title: Message Buffer Autoclear description: If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case. default: false enable_sleeptime: anyOf: - type: boolean - type: 'null' title: Enable Sleeptime description: If set to True, memory management will move to a background agent thread. multi_agent_group: anyOf: - $ref: '#/components/schemas/Group' - type: 'null' description: 'Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages.' deprecated: true managed_group: anyOf: - $ref: '#/components/schemas/Group' - type: 'null' description: The multi-agent group that this agent manages last_run_completion: anyOf: - type: string format: date-time - type: 'null' title: Last Run Completion description: The timestamp when the agent last completed a run. last_run_duration_ms: anyOf: - type: integer - type: 'null' title: Last Run Duration Ms description: The duration in milliseconds of the agent's last run. last_stop_reason: anyOf: - $ref: '#/components/schemas/StopReasonType' - type: 'null' description: The stop reason from the agent's last run. timezone: anyOf: - type: string - type: 'null' title: Timezone description: The timezone of the agent (IANA format). max_files_open: anyOf: - type: integer - type: 'null' title: Max Files Open description: Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent. per_file_view_window_char_limit: anyOf: - type: integer - type: 'null' title: Per File View Window Char Limit description: The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent. hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: If set to True, the agent will be hidden. additionalProperties: false type: object required: - id - name - system - agent_type - llm_config - memory - blocks - tools - sources - tags title: AgentState description: Representation of an agent's state. This is the state of the agent at a given time, and is persisted in the DB backend. The state has all the information needed to recreate a persisted agent. AgentType: type: string enum: - memgpt_agent - memgpt_v2_agent - letta_v1_agent - react_agent - workflow_agent - split_thread_agent - sleeptime_agent - voice_convo_agent - voice_sleeptime_agent title: AgentType description: Enum to represent the type of agent. Annotation: properties: type: type: string const: url_citation title: Type url_citation: $ref: '#/components/schemas/AnnotationURLCitation' additionalProperties: true type: object required: - type - url_citation title: Annotation description: A URL citation when using web search. AnnotationURLCitation: properties: end_index: type: integer title: End Index start_index: type: integer title: Start Index title: type: string title: Title url: type: string title: Url additionalProperties: true type: object required: - end_index - start_index - title - url title: AnnotationURLCitation description: A URL citation when using web search. AnthropicModelSettings: 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: anthropic title: Provider Type description: The type of the provider. default: anthropic temperature: type: number title: Temperature description: The temperature of the model. default: 1 thinking: $ref: '#/components/schemas/AnthropicThinking' description: The thinking configuration for the model. default: type: enabled budget_tokens: 1024 response_format: 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 Format description: The response format for the model. verbosity: anyOf: - type: string enum: - low - medium - high - type: 'null' title: Verbosity description: Soft control for how verbose model output should be, used for GPT-5 models. effort: anyOf: - type: string enum: - low - medium - high - max - type: 'null' title: Effort description: Effort level for supported Anthropic models (controls token spending). 'max' is only available on Opus 4.6. Not setting this gives similar performance to 'high'. strict: type: boolean title: Strict description: Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. default: false type: object title: AnthropicModelSettings AnthropicThinking: properties: type: type: string enum: - enabled - disabled title: Type description: The type of thinking to use. default: enabled budget_tokens: type: integer title: Budget Tokens description: The maximum number of tokens the model can use for extended thinking. default: 1024 type: object title: AnthropicThinking ApprovalCreate: properties: type: type: string const: approval title: Type description: The message type to be created. default: approval otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in approvals: anyOf: - items: oneOf: - $ref: '#/components/schemas/ApprovalReturn' - $ref: '#/components/schemas/letta__schemas__letta_message__ToolReturn' discriminator: propertyName: type mapping: approval: '#/components/schemas/ApprovalReturn' tool: '#/components/schemas/letta__schemas__letta_message__ToolReturn' type: array - type: 'null' title: Approvals description: The list of approval responses approve: anyOf: - type: boolean - type: 'null' title: Approve description: Whether the tool has been approved deprecated: true approval_request_id: anyOf: - type: string - type: 'null' title: Approval Request Id description: The message ID of the approval request deprecated: true reason: anyOf: - type: string - type: 'null' title: Reason description: An optional explanation for the provided approval status deprecated: true type: object title: ApprovalCreate description: Input to approve or deny a tool call request ApprovalRequestMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: approval_request_message title: Message Type description: The type of the message. default: approval_request_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id tool_call: anyOf: - $ref: '#/components/schemas/ToolCall' - $ref: '#/components/schemas/ToolCallDelta' title: Tool Call description: The tool call that has been requested by the llm to run deprecated: true tool_calls: anyOf: - items: $ref: '#/components/schemas/ToolCall' type: array - $ref: '#/components/schemas/ToolCallDelta' - type: 'null' title: Tool Calls description: The tool calls that have been requested by the llm to run, which are pending approval type: object required: - id - date - tool_call title: ApprovalRequestMessage description: "A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).\n\ \nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n\ \ name (Optional[str]): The name of the sender of the message\n tool_call (ToolCall): The tool call" ApprovalResponseMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: approval_response_message title: Message Type description: The type of the message. default: approval_response_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id approvals: anyOf: - items: oneOf: - $ref: '#/components/schemas/ApprovalReturn' - $ref: '#/components/schemas/letta__schemas__letta_message__ToolReturn' discriminator: propertyName: type mapping: approval: '#/components/schemas/ApprovalReturn' tool: '#/components/schemas/letta__schemas__letta_message__ToolReturn' type: array - type: 'null' title: Approvals description: The list of approval responses approve: anyOf: - type: boolean - type: 'null' title: Approve description: Whether the tool has been approved deprecated: true approval_request_id: anyOf: - type: string - type: 'null' title: Approval Request Id description: The message ID of the approval request deprecated: true reason: anyOf: - type: string - type: 'null' title: Reason description: An optional explanation for the provided approval status deprecated: true type: object required: - id - date title: ApprovalResponseMessage description: "A message representing a response form the user indicating whether a tool has been approved to run.\n\n\ Args:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n\ \ name (Optional[str]): The name of the sender of the message\n approve: (bool) Whether the tool has been approved\n\ \ approval_request_id: The ID of the approval request\n reason: (Optional[str]) An optional explanation for\ \ the provided approval status" ApprovalReturn: properties: type: type: string const: approval title: Type description: The message type to be created. default: approval tool_call_id: type: string title: Tool Call Id description: The ID of the tool call that corresponds to this approval approve: type: boolean title: Approve description: Whether the tool has been approved reason: anyOf: - type: string - type: 'null' title: Reason description: An optional explanation for the provided approval status type: object required: - tool_call_id - approve title: ApprovalReturn ArchivalMemorySearchResponse: properties: results: items: $ref: '#/components/schemas/ArchivalMemorySearchResult' type: array title: Results description: List of search results matching the query count: type: integer title: Count description: Total number of results returned type: object required: - results - count title: ArchivalMemorySearchResponse ArchivalMemorySearchResult: properties: id: type: string title: Id description: Unique identifier of the archival memory passage timestamp: type: string title: Timestamp description: Timestamp of when the memory was created, formatted in agent's timezone content: type: string title: Content description: Text content of the archival memory passage tags: items: type: string type: array title: Tags description: List of tags associated with this memory type: object required: - id - timestamp - content title: ArchivalMemorySearchResult Archive: 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: type: string format: date-time title: Created At description: The creation date of the archive updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The timestamp when the object was last updated. name: type: string title: Name description: The name of the archive description: anyOf: - type: string - type: 'null' title: Description description: A description of the archive vector_db_provider: $ref: '#/components/schemas/VectorDBProvider' description: The vector database provider used for this archive's passages default: native embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: Embedding configuration for passages in this archive metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Additional metadata id: type: string pattern: ^archive-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Archive examples: - archive-123e4567-e89b-12d3-a456-426614174000 additionalProperties: false type: object required: - created_at - name - organization_id title: Archive description: Representation of an archive - a collection of archival passages that can be shared between agents. ArchiveCreateRequest: properties: name: type: string title: Name embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: 'Deprecated: Use `embedding` field instead. Embedding configuration for the archive' deprecated: true embedding: anyOf: - type: string - type: 'null' title: Embedding description: Embedding model handle for the archive description: anyOf: - type: string - type: 'null' title: Description type: object required: - name title: ArchiveCreateRequest description: 'Request model for creating an archive. Intentionally excludes vector_db_provider. These are derived internally (vector DB provider from env).' ArchiveUpdateRequest: properties: name: anyOf: - type: string - type: 'null' title: Name description: anyOf: - type: string - type: 'null' title: Description type: object title: ArchiveUpdateRequest description: 'Request model for updating an archive (partial). Supports updating only name and description.' AssistantMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: assistant_message title: Message Type description: The type of the message. default: assistant_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id content: anyOf: - items: $ref: '#/components/schemas/LettaAssistantMessageContentUnion' type: array - type: string title: Content description: The message content sent by the agent (can be a string or an array of content parts) type: object required: - id - date - content title: AssistantMessage description: "A message sent by the LLM in response to user input. Used in the LLM context.\n\nArgs:\n id (str):\ \ The ID of the message\n date (datetime): The date the message was created in ISO format\n name (Optional[str]):\ \ The name of the sender of the message\n content (Union[str, List[LettaAssistantMessageContentUnion]]): The message\ \ content sent by the agent (can be a string or an array of content parts)" AssistantMessageListResult: properties: message_type: type: string const: assistant_message title: Message Type default: assistant_message content: anyOf: - items: $ref: '#/components/schemas/LettaAssistantMessageContentUnion' type: array - type: string title: Content description: The message content sent by the assistant (can be a string or an array of content parts) message_id: type: string title: Message Id description: The unique identifier of the message. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent that owns the message. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation that the message belongs to. created_at: type: string format: date-time title: Created At description: The time the message was created in ISO format. type: object required: - content - message_id - created_at title: AssistantMessageListResult description: 'Assistant message list result with agent context. Shape is identical to UpdateAssistantMessage but includes the owning agent_id and message id.' Audio: properties: id: type: string title: Id type: object required: - id title: Audio description: 'Data about a previous audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).' AuthRequest: properties: password: type: string title: Password description: Admin password provided when starting the Letta server type: object title: AuthRequest AuthResponse: properties: uuid: type: string format: uuid title: Uuid description: UUID of the user is_admin: anyOf: - type: boolean - type: 'null' title: Is Admin description: Whether the user is an admin type: object required: - uuid title: AuthResponse AzureModelSettings: 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: azure title: Provider Type description: The type of the provider. default: azure temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 response_format: 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 Format description: The response format for the model. type: object title: AzureModelSettings description: Azure OpenAI model configuration (OpenAI-compatible). Base64Image: properties: type: type: string const: base64 title: Type description: The source type for the image. default: base64 media_type: type: string title: Media Type description: The media type for the image. data: type: string title: Data description: The base64 encoded image data. detail: anyOf: - type: string - type: 'null' title: Detail description: What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) type: object required: - media_type - data title: Base64Image BaseToolRuleSchema: properties: tool_name: type: string title: Tool Name type: type: string title: Type type: object required: - tool_name - type title: BaseToolRuleSchema BasetenModelSettings: 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: baseten title: Provider Type description: The type of the provider. default: baseten temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 type: object title: BasetenModelSettings description: Baseten model configuration (OpenAI-compatible). BatchJob: 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: type: string format: date-time title: Created At description: The unix timestamp of when the job was created. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The timestamp when the object was last updated. status: $ref: '#/components/schemas/JobStatus' description: The status of the job. default: created completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: The unix timestamp of when the job was completed. stop_reason: anyOf: - $ref: '#/components/schemas/StopReasonType' - type: 'null' description: The reason why the job was stopped. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: The metadata of the job. job_type: $ref: '#/components/schemas/JobType' default: batch background: anyOf: - type: boolean - type: 'null' title: Background description: Whether the job was created in background mode. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The agent associated with this job/run. callback_url: anyOf: - type: string - type: 'null' title: Callback Url description: If set, POST to this URL when the job completes. callback_sent_at: anyOf: - type: string format: date-time - type: 'null' title: Callback Sent At description: Timestamp when the callback was last attempted. callback_status_code: anyOf: - type: integer - type: 'null' title: Callback Status Code description: HTTP status code returned by the callback endpoint. callback_error: anyOf: - type: string - type: 'null' title: Callback Error description: Optional error message from attempting to POST the callback endpoint. ttft_ns: anyOf: - type: integer - type: 'null' title: Ttft Ns description: Time to first token for a run in nanoseconds total_duration_ns: anyOf: - type: integer - type: 'null' title: Total Duration Ns description: Total run duration in nanoseconds id: type: string pattern: ^(job|run)-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Job examples: - job-123e4567-e89b-12d3-a456-426614174000 additionalProperties: false type: object title: BatchJob BedrockModelSettings: 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: bedrock title: Provider Type description: The type of the provider. default: bedrock temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 response_format: 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 Format description: The response format for the model. type: object title: BedrockModelSettings description: AWS Bedrock model configuration. BillingContext: properties: plan_type: anyOf: - type: string - type: 'null' title: Plan Type description: Subscription tier cost_source: anyOf: - type: string - type: 'null' title: Cost Source description: 'Cost source: ''quota'' or ''credits''' customer_id: anyOf: - type: string - type: 'null' title: Customer Id description: Customer ID for billing records type: object title: BillingContext description: Billing context for LLM request cost tracking. Block: 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: Name of the block if it is a template. 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: The id of the template. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template id of the block. deployment_id: anyOf: - type: string - type: 'null' title: Deployment Id description: The id of the deployment. entity_id: anyOf: - type: string - type: 'null' title: Entity Id description: The id of the entity within the template. preserve_on_migration: anyOf: - type: boolean - type: 'null' title: Preserve On Migration description: Preserve the block on template migration. default: false 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: Whether the agent has read-only access to the block. default: false 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: If set to True, the block will be hidden. id: type: string pattern: ^block-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Block examples: - block-123e4567-e89b-12d3-a456-426614174000 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 title: Block description: A Block represents a reserved section of the LLM's context window. 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 BlockSchema: 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: Name of the block if it is a template. is_template: type: boolean title: Is Template default: false template_id: anyOf: - type: string - type: 'null' title: Template Id description: The id of the template. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template id of the block. deployment_id: anyOf: - type: string - type: 'null' title: Deployment Id description: The id of the deployment. entity_id: anyOf: - type: string - type: 'null' title: Entity Id description: The id of the entity within the template. preserve_on_migration: anyOf: - type: boolean - type: 'null' title: Preserve On Migration description: Preserve the block on template migration. default: false label: type: string title: Label description: Label of the block. read_only: type: boolean title: Read Only description: Whether the agent has read-only access to the block. default: false 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: If set to True, the block will be hidden. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags to associate with the block. id: type: string title: Id description: Human-readable identifier for this block in the file type: object required: - value - label - id title: BlockSchema description: Block with human-readable ID for agent file BlockUpdate: properties: value: anyOf: - type: string - type: 'null' title: Value description: Value of the block. limit: anyOf: - type: integer - type: 'null' title: Limit description: Character limit of the block. 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: Name of the block if it is a template. 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: The id of the template. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template id of the block. deployment_id: anyOf: - type: string - type: 'null' title: Deployment Id description: The id of the deployment. entity_id: anyOf: - type: string - type: 'null' title: Entity Id description: The id of the entity within the template. preserve_on_migration: anyOf: - type: boolean - type: 'null' title: Preserve On Migration description: Preserve the block on template migration. default: false 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: Whether the agent has read-only access to the block. default: false 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: If set to True, the block will be hidden. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags to associate with the block. type: object title: BlockUpdate description: Update a block Body_export_agent: properties: spec: anyOf: - $ref: '#/components/schemas/AgentFileSchema' - type: 'null' legacy_spec: anyOf: - $ref: '#/components/schemas/letta__serialize_schemas__pydantic_agent_schema__AgentSchema' - type: 'null' type: object title: Body_export_agent Body_import_agent: properties: file: type: string format: binary title: File override_existing_tools: type: boolean title: Override Existing Tools description: If set to True, existing tools can get their source code overwritten by the uploaded tool definitions. Note that Letta core tools can never be updated externally. default: true strip_messages: type: boolean title: Strip Messages description: If set to True, strips all messages from the agent before importing. default: false secrets: anyOf: - type: string - type: 'null' title: Secrets description: Secrets as a JSON string to pass to the agent for tool execution. name: anyOf: - type: string - type: 'null' title: Name description: If provided, overrides the agent name with this value. embedding: anyOf: - type: string - type: 'null' title: Embedding description: Embedding handle to override with. model: anyOf: - type: string - type: 'null' title: Model description: Model handle to override the agent's default model. This allows the imported agent to use a different model while keeping other defaults (e.g., context size) from the original configuration. append_copy_suffix: type: boolean title: Append Copy Suffix description: If set to True, appends "_copy" to the end of the agent name. default: true deprecated: true override_name: anyOf: - type: string - type: 'null' title: Override Name description: If provided, overrides the agent name with this value. Use 'name' instead. deprecated: true override_embedding_handle: anyOf: - type: string - type: 'null' title: Override Embedding Handle description: Override import with specific embedding handle. Use 'embedding' instead. deprecated: true override_model_handle: anyOf: - type: string - type: 'null' title: Override Model Handle description: Model handle to override the agent's default model. Use 'model' instead. deprecated: true project_id: anyOf: - type: string - type: 'null' title: Project Id description: The project ID to associate the uploaded agent with. This is now passed via headers. deprecated: true env_vars_json: anyOf: - type: string - type: 'null' title: Env Vars Json description: Environment variables as a JSON string to pass to the agent for tool execution. Use 'secrets' instead. deprecated: true type: object required: - file title: Body_import_agent Body_upload_file_to_folder: properties: file: type: string format: binary title: File type: object required: - file title: Body_upload_file_to_folder Body_upload_file_to_source: properties: file: type: string format: binary title: File type: object required: - file title: Body_upload_file_to_source CancelAgentRunRequest: properties: run_ids: anyOf: - items: type: string type: array - type: 'null' title: Run Ids description: Optional list of run IDs to cancel type: object title: CancelAgentRunRequest ChatCompletion: properties: id: type: string title: Id choices: items: $ref: '#/components/schemas/Choice' type: array title: Choices created: type: integer title: Created model: type: string title: Model object: type: string const: chat.completion title: Object service_tier: anyOf: - type: string enum: - auto - default - flex - scale - priority - type: 'null' title: Service Tier system_fingerprint: anyOf: - type: string - type: 'null' title: System Fingerprint usage: anyOf: - $ref: '#/components/schemas/CompletionUsage' - type: 'null' additionalProperties: true type: object required: - id - choices - created - model - object title: ChatCompletion description: Represents a chat completion response returned by model, based on the provided input. ChatCompletionAssistantMessageParam: properties: role: type: string const: assistant title: Role audio: anyOf: - $ref: '#/components/schemas/Audio' - type: 'null' content: anyOf: - type: string - items: anyOf: - $ref: '#/components/schemas/ChatCompletionContentPartTextParam' - $ref: '#/components/schemas/ChatCompletionContentPartRefusalParam' type: array - type: 'null' title: Content function_call: anyOf: - $ref: '#/components/schemas/FunctionCall-Input' - type: 'null' name: type: string title: Name refusal: anyOf: - type: string - type: 'null' title: Refusal tool_calls: items: anyOf: - $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCallParam' - $ref: '#/components/schemas/ChatCompletionMessageCustomToolCallParam' type: array title: Tool Calls type: object required: - role title: ChatCompletionAssistantMessageParam description: Messages sent by the model in response to user messages. ChatCompletionAudio: properties: id: type: string title: Id data: type: string title: Data expires_at: type: integer title: Expires At transcript: type: string title: Transcript additionalProperties: true type: object required: - id - data - expires_at - transcript title: ChatCompletionAudio description: 'If the audio output modality is requested, this object contains data about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).' ChatCompletionContentPartImageParam: properties: image_url: $ref: '#/components/schemas/ImageURL' type: type: string const: image_url title: Type type: object required: - image_url - type title: ChatCompletionContentPartImageParam description: Learn about [image inputs](https://platform.openai.com/docs/guides/vision). ChatCompletionContentPartInputAudioParam: properties: input_audio: $ref: '#/components/schemas/InputAudio' type: type: string const: input_audio title: Type type: object required: - input_audio - type title: ChatCompletionContentPartInputAudioParam description: Learn about [audio inputs](https://platform.openai.com/docs/guides/audio). ChatCompletionContentPartRefusalParam: properties: refusal: type: string title: Refusal type: type: string const: refusal title: Type type: object required: - refusal - type title: ChatCompletionContentPartRefusalParam ChatCompletionContentPartTextParam: properties: text: type: string title: Text type: type: string const: text title: Type type: object required: - text - type title: ChatCompletionContentPartTextParam description: Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation). ChatCompletionDeveloperMessageParam: properties: content: anyOf: - type: string - items: $ref: '#/components/schemas/ChatCompletionContentPartTextParam' type: array title: Content role: type: string const: developer title: Role name: type: string title: Name type: object required: - content - role title: ChatCompletionDeveloperMessageParam description: 'Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, `developer` messages replace the previous `system` messages.' ChatCompletionFunctionMessageParam: properties: content: anyOf: - type: string - type: 'null' title: Content name: type: string title: Name role: type: string const: function title: Role type: object required: - content - name - role title: ChatCompletionFunctionMessageParam ChatCompletionMessage: properties: content: anyOf: - type: string - type: 'null' title: Content refusal: anyOf: - type: string - type: 'null' title: Refusal role: type: string const: assistant title: Role annotations: anyOf: - items: $ref: '#/components/schemas/Annotation' type: array - type: 'null' title: Annotations audio: anyOf: - $ref: '#/components/schemas/ChatCompletionAudio' - type: 'null' function_call: anyOf: - $ref: '#/components/schemas/FunctionCall-Output' - type: 'null' tool_calls: anyOf: - items: anyOf: - $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall-Output' - $ref: '#/components/schemas/ChatCompletionMessageCustomToolCall' type: array - type: 'null' title: Tool Calls additionalProperties: true type: object required: - role title: ChatCompletionMessage description: A chat completion message generated by the model. ChatCompletionMessageCustomToolCall: properties: id: type: string title: Id custom: $ref: '#/components/schemas/Custom-Output' type: type: string const: custom title: Type additionalProperties: true type: object required: - id - custom - type title: ChatCompletionMessageCustomToolCall description: A call to a custom tool created by the model. ChatCompletionMessageCustomToolCallParam: properties: id: type: string title: Id custom: $ref: '#/components/schemas/Custom-Input' type: type: string const: custom title: Type type: object required: - id - custom - type title: ChatCompletionMessageCustomToolCallParam description: A call to a custom tool created by the model. ChatCompletionMessageFunctionToolCall-Input: properties: id: type: string title: Id function: $ref: '#/components/schemas/openai__types__chat__chat_completion_message_function_tool_call__Function' type: type: string const: function title: Type additionalProperties: true type: object required: - id - function - type title: ChatCompletionMessageFunctionToolCall description: A call to a function tool created by the model. ChatCompletionMessageFunctionToolCall-Output: properties: id: type: string title: Id function: $ref: '#/components/schemas/Function-Output' type: type: string const: function title: Type additionalProperties: true type: object required: - id - function - type title: ChatCompletionMessageFunctionToolCall description: A call to a function tool created by the model. ChatCompletionMessageFunctionToolCallParam: properties: id: type: string title: Id function: $ref: '#/components/schemas/openai__types__chat__chat_completion_message_function_tool_call_param__Function' type: type: string const: function title: Type type: object required: - id - function - type title: ChatCompletionMessageFunctionToolCallParam description: A call to a function tool created by the model. ChatCompletionRequest: properties: model: type: string title: Model description: ID of the model to use messages: items: anyOf: - $ref: '#/components/schemas/ChatCompletionDeveloperMessageParam' - $ref: '#/components/schemas/ChatCompletionSystemMessageParam' - $ref: '#/components/schemas/ChatCompletionUserMessageParam' - $ref: '#/components/schemas/ChatCompletionAssistantMessageParam' - $ref: '#/components/schemas/ChatCompletionToolMessageParam' - $ref: '#/components/schemas/ChatCompletionFunctionMessageParam' type: array title: Messages description: Messages comprising the conversation so far temperature: anyOf: - type: number maximum: 2 minimum: 0 - type: 'null' title: Temperature description: Sampling temperature top_p: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Top P description: Nucleus sampling parameter n: anyOf: - type: integer minimum: 1 - type: 'null' title: N description: Number of chat completion choices to generate default: 1 stream: anyOf: - type: boolean - type: 'null' title: Stream description: Whether to stream back partial progress default: false stop: anyOf: - type: string - items: type: string type: array - type: 'null' title: Stop description: Sequences where the API will stop generating max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens description: Maximum number of tokens to generate presence_penalty: anyOf: - type: number maximum: 2 minimum: -2 - type: 'null' title: Presence Penalty description: Presence penalty frequency_penalty: anyOf: - type: number maximum: 2 minimum: -2 - type: 'null' title: Frequency Penalty description: Frequency penalty user: anyOf: - type: string - type: 'null' title: User description: A unique identifier representing your end-user type: object required: - model - messages title: ChatCompletionRequest description: OpenAI-compatible chat completion request - exactly matching OpenAI's schema. ChatCompletionSystemMessageParam: properties: content: anyOf: - type: string - items: $ref: '#/components/schemas/ChatCompletionContentPartTextParam' type: array title: Content role: type: string const: system title: Role name: type: string title: Name type: object required: - content - role title: ChatCompletionSystemMessageParam description: 'Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, use `developer` messages for this purpose instead.' ChatCompletionToolMessageParam: properties: content: anyOf: - type: string - items: $ref: '#/components/schemas/ChatCompletionContentPartTextParam' type: array title: Content role: type: string const: tool title: Role tool_call_id: type: string title: Tool Call Id type: object required: - content - role - tool_call_id title: ChatCompletionToolMessageParam ChatCompletionUserMessageParam: properties: content: anyOf: - type: string - items: anyOf: - $ref: '#/components/schemas/ChatCompletionContentPartTextParam' - $ref: '#/components/schemas/ChatCompletionContentPartImageParam' - $ref: '#/components/schemas/ChatCompletionContentPartInputAudioParam' - $ref: '#/components/schemas/File' type: array title: Content role: type: string const: user title: Role name: type: string title: Name type: object required: - content - role title: ChatCompletionUserMessageParam description: 'Messages sent by an end user, containing prompts or additional context information.' 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). ChatGPTOAuthReasoning: properties: reasoning_effort: type: string enum: - none - low - medium - high - xhigh title: Reasoning Effort description: The reasoning effort level for GPT-5.x and o-series models. default: medium type: object title: ChatGPTOAuthReasoning description: Reasoning configuration for ChatGPT OAuth models (GPT-5.x, o-series). ChildToolRule: 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: constrain_child_tools title: Type default: constrain_child_tools prompt_template: anyOf: - type: string - type: 'null' title: Prompt Template description: Optional template string (ignored). children: items: type: string type: array title: Children description: The children tools that can be invoked. child_arg_nodes: anyOf: - items: $ref: '#/components/schemas/ToolCallNode' type: array - type: 'null' title: Child Arg Nodes description: Optional list of typed child argument overrides. Each node must reference a child in 'children'. additionalProperties: false type: object required: - tool_name - children title: ChildToolRule description: A ToolRule represents a tool that can be invoked by the agent. ChildToolRuleSchema: properties: tool_name: type: string title: Tool Name type: type: string title: Type children: items: type: string type: array title: Children type: object required: - tool_name - type - children title: ChildToolRuleSchema Choice: properties: finish_reason: type: string enum: - stop - length - tool_calls - content_filter - function_call title: Finish Reason index: type: integer title: Index logprobs: anyOf: - $ref: '#/components/schemas/openai__types__chat__chat_completion__ChoiceLogprobs' - type: 'null' message: $ref: '#/components/schemas/ChatCompletionMessage' additionalProperties: true type: object required: - finish_reason - index - message title: Choice ClientSkillSchema: properties: name: type: string title: Name description: The name of the skill description: type: string title: Description description: Description of what the skill does location: type: string title: Location description: Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) type: object required: - name - description - location title: ClientSkillSchema description: 'Schema for a client-side skill passed in the request. Client-side skills represent environment-provided capabilities (e.g. project-scoped skills) that are not stored in the agent''s MemFS but should appear in the system prompt''s available skills section.' ClientToolSchema: properties: name: type: string title: Name description: The name of the tool function description: anyOf: - type: string - type: 'null' title: Description description: Description of what the tool does parameters: anyOf: - additionalProperties: true type: object - type: 'null' title: Parameters description: JSON Schema for the function parameters type: object required: - name title: ClientToolSchema description: 'Schema for a client-side tool passed in the request. Client-side tools are executed by the client, not the server. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result.' CodeInput: properties: code: type: string title: Code description: Source code to parse for JSON schema source_type: anyOf: - type: string - type: 'null' title: Source Type description: The source type of the code (python or typescript) default: python type: object required: - code title: CodeInput CompactionResponse: properties: summary: type: string title: Summary num_messages_before: type: integer title: Num Messages Before num_messages_after: type: integer title: Num Messages After type: object required: - summary - num_messages_before - num_messages_after title: CompactionResponse CompactionSettings-Input: properties: model: anyOf: - type: string - type: 'null' title: Model description: 'Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults.' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: Optional model settings used to override defaults for the summarizer model. prompt: anyOf: - type: string - type: 'null' title: Prompt description: The prompt to use for summarization. If None, uses mode-specific default. prompt_acknowledgement: type: boolean title: Prompt Acknowledgement description: Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). default: false clip_chars: anyOf: - type: integer - type: 'null' title: Clip Chars description: The maximum length of the summary in characters. If none, no clipping is performed. default: 50000 mode: type: string enum: - all - sliding_window - self_compact_all - self_compact_sliding_window title: Mode description: The type of summarization technique use. default: sliding_window sliding_window_percentage: type: number title: Sliding Window Percentage description: The percentage of the context window to keep post-summarization (only used in sliding window modes). type: object title: CompactionSettings description: 'Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle.' CompactionSettings-Output: properties: model: anyOf: - type: string - type: 'null' title: Model description: 'Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults.' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: Optional model settings used to override defaults for the summarizer model. prompt: anyOf: - type: string - type: 'null' title: Prompt description: The prompt to use for summarization. If None, uses mode-specific default. prompt_acknowledgement: type: boolean title: Prompt Acknowledgement description: Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). default: false clip_chars: anyOf: - type: integer - type: 'null' title: Clip Chars description: The maximum length of the summary in characters. If none, no clipping is performed. default: 50000 mode: type: string enum: - all - sliding_window - self_compact_all - self_compact_sliding_window title: Mode description: The type of summarization technique use. default: sliding_window sliding_window_percentage: type: number title: Sliding Window Percentage description: The percentage of the context window to keep post-summarization (only used in sliding window modes). type: object title: CompactionSettings description: 'Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle.' CompactionStats: properties: trigger: type: string title: Trigger description: What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') context_tokens_before: anyOf: - type: integer - type: 'null' title: Context Tokens Before description: Token count before compaction (from LLM usage stats, includes full context sent to LLM) context_tokens_after: anyOf: - type: integer - type: 'null' title: Context Tokens After description: Token count after compaction (message tokens only, does not include tool definitions) context_window: type: integer title: Context Window description: The model's context window size messages_count_before: type: integer title: Messages Count Before description: Number of messages before compaction messages_count_after: type: integer title: Messages Count After description: Number of messages after compaction type: object required: - trigger - context_window - messages_count_before - messages_count_after title: CompactionStats description: Statistics about a memory compaction operation. ComparisonOperator: type: string enum: - eq - gte - lte title: ComparisonOperator description: Comparison operators for filtering numeric values CompletionTokensDetails: properties: accepted_prediction_tokens: anyOf: - type: integer - type: 'null' title: Accepted Prediction Tokens audio_tokens: anyOf: - type: integer - type: 'null' title: Audio Tokens reasoning_tokens: anyOf: - type: integer - type: 'null' title: Reasoning Tokens rejected_prediction_tokens: anyOf: - type: integer - type: 'null' title: Rejected Prediction Tokens additionalProperties: true type: object title: CompletionTokensDetails description: Breakdown of tokens used in a completion. CompletionUsage: properties: completion_tokens: type: integer title: Completion Tokens prompt_tokens: type: integer title: Prompt Tokens total_tokens: type: integer title: Total Tokens completion_tokens_details: anyOf: - $ref: '#/components/schemas/CompletionTokensDetails' - type: 'null' prompt_tokens_details: anyOf: - $ref: '#/components/schemas/PromptTokensDetails' - type: 'null' additionalProperties: true type: object required: - completion_tokens - prompt_tokens - total_tokens title: CompletionUsage description: Usage statistics for the completion request. 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. ConditionalToolRuleSchema: properties: tool_name: type: string title: Tool Name type: type: string title: Type default_child: anyOf: - type: string - type: 'null' title: Default Child child_output_mapping: additionalProperties: type: string type: object title: Child Output Mapping require_output_mapping: type: boolean title: Require Output Mapping type: object required: - tool_name - type - default_child - child_output_mapping - require_output_mapping title: ConditionalToolRuleSchema ContextWindowOverview: properties: context_window_size_max: type: integer title: Context Window Size Max description: The maximum amount of tokens the context window can hold. context_window_size_current: type: integer title: Context Window Size Current description: The current number of tokens in the context window. num_messages: type: integer title: Num Messages description: The number of messages in the context window. num_archival_memory: type: integer title: Num Archival Memory description: The number of messages in the archival memory. num_recall_memory: type: integer title: Num Recall Memory description: The number of messages in the recall memory. num_tokens_external_memory_summary: type: integer title: Num Tokens External Memory Summary description: The number of tokens in the external memory summary (archival + recall metadata). external_memory_summary: type: string title: External Memory Summary description: The metadata summary of the external memory sources (archival + recall metadata). num_tokens_system: type: integer title: Num Tokens System description: The number of tokens in the system prompt. system_prompt: type: string title: System Prompt description: The content of the system prompt. num_tokens_core_memory: type: integer title: Num Tokens Core Memory description: The number of tokens in the core memory. core_memory: type: string title: Core Memory description: The content of the core memory. num_tokens_memory_filesystem: type: integer title: Num Tokens Memory Filesystem description: The number of tokens in the memory filesystem section (git-enabled agents only). default: 0 memory_filesystem: anyOf: - type: string - type: 'null' title: Memory Filesystem description: The content of the memory filesystem section. num_tokens_tool_usage_rules: type: integer title: Num Tokens Tool Usage Rules description: The number of tokens in the tool usage rules section. default: 0 tool_usage_rules: anyOf: - type: string - type: 'null' title: Tool Usage Rules description: The content of the tool usage rules section. num_tokens_directories: type: integer title: Num Tokens Directories description: The number of tokens in the directories section (attached sources). default: 0 directories: anyOf: - type: string - type: 'null' title: Directories description: The content of the directories section. num_tokens_summary_memory: type: integer title: Num Tokens Summary Memory description: The number of tokens in the summary memory. summary_memory: anyOf: - type: string - type: 'null' title: Summary Memory description: The content of the summary memory. num_tokens_functions_definitions: type: integer title: Num Tokens Functions Definitions description: The number of tokens in the functions definitions. functions_definitions: anyOf: - items: $ref: '#/components/schemas/FunctionTool' type: array - type: 'null' title: Functions Definitions description: The content of the functions definitions. num_tokens_messages: type: integer title: Num Tokens Messages description: The number of tokens in the messages list. messages: items: $ref: '#/components/schemas/Message' type: array title: Messages description: The messages in the context window. type: object required: - context_window_size_max - context_window_size_current - num_messages - num_archival_memory - num_recall_memory - num_tokens_external_memory_summary - external_memory_summary - num_tokens_system - system_prompt - num_tokens_core_memory - core_memory - num_tokens_summary_memory - num_tokens_functions_definitions - functions_definitions - num_tokens_messages - messages title: ContextWindowOverview description: Overview of the context window, including the number of messages and tokens. 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. Conversation: 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 title: Id description: The unique identifier of the conversation. agent_id: type: string title: Agent Id description: The ID of the agent this conversation belongs to. summary: anyOf: - type: string - type: 'null' title: Summary description: A summary of the conversation. in_context_message_ids: items: type: string type: array title: In Context Message Ids description: The IDs of in-context messages for the conversation. isolated_block_ids: items: type: string type: array title: Isolated Block Ids description: IDs of blocks that are isolated (specific to this conversation, overriding agent defaults). model: anyOf: - type: string - type: 'null' title: Model description: 'The model handle for this conversation (overrides agent''s model). Format: provider/model-name.' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: The model settings for this conversation (overrides agent's model settings). last_message_at: anyOf: - type: string format: date-time - type: 'null' title: Last Message At description: Timestamp of the most recent message request sent to this conversation. additionalProperties: false type: object required: - id - agent_id title: Conversation description: Represents a conversation on an agent for concurrent messaging. ConversationMessageRequest: properties: messages: anyOf: - items: anyOf: - $ref: '#/components/schemas/MessageCreate' - $ref: '#/components/schemas/ApprovalCreate' - $ref: '#/components/schemas/ToolReturnCreate' type: array - type: 'null' title: Messages description: The messages to be sent to the agent. input: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' - $ref: '#/components/schemas/SummarizedReasoningContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' summarized_reasoning: '#/components/schemas/SummarizedReasoningContent' text: '#/components/schemas/TextContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolReturnContent' type: array - type: 'null' title: Input description: 'Syntactic sugar for a single user message. Equivalent to messages=[{''role'': ''user'', ''content'': input}].' max_steps: type: integer title: Max Steps description: Maximum number of steps the agent should take to process the request. default: 50 use_assistant_message: type: boolean title: Use Assistant Message description: Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: true deprecated: true assistant_message_tool_name: type: string title: Assistant Message Tool Name description: The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: send_message deprecated: true assistant_message_tool_kwarg: type: string title: Assistant Message Tool Kwarg description: The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: message deprecated: true include_return_message_types: anyOf: - items: $ref: '#/components/schemas/MessageType' type: array - type: 'null' title: Include Return Message Types description: Only return specified message types in the response. If `None` (default) returns all messages. enable_thinking: type: string title: Enable Thinking description: If set to True, enables reasoning before responses or tool calls from the agent. default: true deprecated: true client_tools: anyOf: - items: $ref: '#/components/schemas/ClientToolSchema' type: array - type: 'null' title: Client Tools description: Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. client_skills: anyOf: - items: $ref: '#/components/schemas/ClientSkillSchema' type: array - type: 'null' title: Client Skills description: Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. override_model: anyOf: - type: string - type: 'null' title: Override Model description: Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. include_compaction_messages: type: boolean title: Include Compaction Messages description: If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. default: false return_logprobs: type: boolean title: Return Logprobs description: If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). default: false top_logprobs: anyOf: - type: integer - type: 'null' title: Top Logprobs description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. return_token_ids: type: boolean title: Return Token Ids description: If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. default: false override_system: anyOf: - type: string - type: 'null' title: Override System description: Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: Agent ID for agent-direct mode with 'default' conversation. Use with conversation_id='default' in the URL path. streaming: type: boolean title: Streaming description: If True (default), returns a streaming response (Server-Sent Events). If False, returns a complete JSON response. default: true stream_tokens: type: boolean title: Stream Tokens description: Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true). default: false include_pings: type: boolean title: Include Pings description: Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true). default: true background: type: boolean title: Background description: Whether to process the request in the background (only used when streaming=true). default: false type: object title: ConversationMessageRequest description: Request for sending messages to a conversation. Streams by default. CoreMemoryBlockSchema: properties: created_at: type: string title: Created At description: anyOf: - type: string - type: 'null' title: Description is_template: type: boolean title: Is Template label: type: string title: Label limit: type: integer title: Limit metadata_: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata template_name: anyOf: - type: string - type: 'null' title: Template Name updated_at: type: string title: Updated At value: type: string title: Value type: object required: - created_at - description - is_template - label - limit - template_name - updated_at - value title: CoreMemoryBlockSchema CreateAgentRequest: properties: name: type: string title: Name description: The name of the agent. memory_blocks: anyOf: - items: $ref: '#/components/schemas/CreateBlock' type: array - type: 'null' title: Memory Blocks description: The blocks to create in the agent's in-context memory. tools: anyOf: - items: type: string type: array - type: 'null' title: Tools description: The tools used by the agent. tool_ids: anyOf: - items: type: string maxLength: 41 minLength: 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-' examples: - tool-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Tool Ids description: The ids of the tools used by the agent. source_ids: anyOf: - items: type: string maxLength: 43 minLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Source Ids description: 'Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent.' deprecated: true folder_ids: anyOf: - items: type: string maxLength: 43 minLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Folder Ids description: The ids of the folders used by the agent. block_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Block Ids description: The ids of the blocks used by the agent. tool_rules: anyOf: - items: oneOf: - $ref: '#/components/schemas/ChildToolRule' - $ref: '#/components/schemas/InitToolRule' - $ref: '#/components/schemas/TerminalToolRule' - $ref: '#/components/schemas/ConditionalToolRule' - $ref: '#/components/schemas/ContinueToolRule' - $ref: '#/components/schemas/RequiredBeforeExitToolRule' - $ref: '#/components/schemas/MaxCountPerStepToolRule' - $ref: '#/components/schemas/ParentToolRule' - $ref: '#/components/schemas/RequiresApprovalToolRule' discriminator: propertyName: type mapping: conditional: '#/components/schemas/ConditionalToolRule' constrain_child_tools: '#/components/schemas/ChildToolRule' continue_loop: '#/components/schemas/ContinueToolRule' exit_loop: '#/components/schemas/TerminalToolRule' max_count_per_step: '#/components/schemas/MaxCountPerStepToolRule' parent_last_tool: '#/components/schemas/ParentToolRule' required_before_exit: '#/components/schemas/RequiredBeforeExitToolRule' requires_approval: '#/components/schemas/RequiresApprovalToolRule' run_first: '#/components/schemas/InitToolRule' type: array - type: 'null' title: Tool Rules description: The tool rules governing the agent. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags associated with the agent. system: anyOf: - type: string - type: 'null' title: System description: The system prompt used by the agent. agent_type: $ref: '#/components/schemas/AgentType' description: The type of agent. initial_message_sequence: anyOf: - items: $ref: '#/components/schemas/MessageCreate' type: array - type: 'null' title: Initial Message Sequence description: The initial set of messages to put in the agent's in-context memory. include_base_tools: type: boolean title: Include Base Tools description: If true, attaches the Letta core tools (e.g. core_memory related functions). default: true include_multi_agent_tools: type: boolean title: Include Multi Agent Tools description: If true, attaches the Letta multi-agent tools (e.g. sending a message to another agent). default: false include_base_tool_rules: anyOf: - type: boolean - type: 'null' title: Include Base Tool Rules description: If true, attaches the Letta base tool rules (e.g. deny all tools not explicitly allowed). include_default_source: type: boolean title: Include Default Source description: If true, automatically creates and attaches a default data source for this agent. default: false deprecated: true description: anyOf: - type: string - type: 'null' title: Description description: The description of the agent. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: The metadata of the agent. llm_config: anyOf: - $ref: '#/components/schemas/LLMConfig' - type: 'null' description: 'Deprecated: Use `model` field instead. The LLM configuration used by the agent.' deprecated: true embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: 'Deprecated: Use `embedding` field instead. The embedding configuration used by the agent.' deprecated: true model: anyOf: - type: string - type: 'null' title: Model description: 'The model handle for the agent to use (format: provider/model-name).' embedding: anyOf: - type: string - type: 'null' title: Embedding description: 'The embedding model handle used by the agent (format: provider/model-name).' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: The model settings for the agent. compaction_settings: anyOf: - $ref: '#/components/schemas/CompactionSettings-Input' - type: 'null' description: The compaction settings configuration used for compaction. context_window_limit: anyOf: - type: integer - type: 'null' title: Context Window Limit description: The context window limit used by the agent. embedding_chunk_size: anyOf: - type: integer - type: 'null' title: Embedding Chunk Size description: 'Deprecated: No longer used. The embedding chunk size used by the agent.' default: 300 deprecated: true max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens description: 'Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step.' deprecated: true max_reasoning_tokens: anyOf: - type: integer - type: 'null' title: Max Reasoning Tokens description: 'Deprecated: Use `model` field to configure reasoning tokens instead. The maximum number of tokens to generate for reasoning step.' deprecated: true enable_reasoner: anyOf: - type: boolean - type: 'null' title: Enable Reasoner description: 'Deprecated: Use `model` field to configure reasoning instead. Whether to enable internal extended thinking step for a reasoner model.' default: true deprecated: true reasoning: anyOf: - type: boolean - type: 'null' title: Reasoning description: 'Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent.' deprecated: true from_template: anyOf: - type: string - type: 'null' title: From Template description: 'Deprecated: please use the ''create agents from a template'' endpoint instead.' deprecated: true template: type: boolean title: Template description: 'Deprecated: No longer used.' default: false deprecated: true project: anyOf: - type: string - type: 'null' title: Project description: 'Deprecated: Project should now be passed via the X-Project header instead of in the request body. If using the SDK, this can be done via the x_project parameter.' deprecated: true tool_exec_environment_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Tool Exec Environment Variables description: 'Deprecated: Use `secrets` field instead. Environment variables for tool execution.' deprecated: true secrets: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Secrets description: The environment variables for tool execution specific to this agent. memory_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Memory Variables description: 'Deprecated: Only relevant for creating agents from a template. Use the ''create agents from a template'' endpoint instead.' deprecated: true project_id: anyOf: - type: string - type: 'null' title: Project Id description: 'Deprecated: No longer used. The id of the project the agent belongs to.' deprecated: true template_id: anyOf: - type: string - type: 'null' title: Template Id description: 'Deprecated: No longer used. The id of the template the agent belongs to.' deprecated: true base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: 'Deprecated: No longer used. The base template id of the agent.' deprecated: true identity_ids: anyOf: - items: type: string maxLength: 45 minLength: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Identity Ids description: The ids of the identities associated with this agent. message_buffer_autoclear: type: boolean title: Message Buffer Autoclear description: If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case. default: false enable_sleeptime: anyOf: - type: boolean - type: 'null' title: Enable Sleeptime description: If set to True, memory management will move to a background agent thread. response_format: 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 Format description: 'Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent.' deprecated: true timezone: anyOf: - type: string - type: 'null' title: Timezone description: The timezone of the agent (IANA format). max_files_open: anyOf: - type: integer - type: 'null' title: Max Files Open description: Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent. per_file_view_window_char_limit: anyOf: - type: integer - type: 'null' title: Per File View Window Char Limit description: The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent. hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: 'Deprecated: No longer used. If set to True, the agent will be hidden.' deprecated: true parallel_tool_calls: anyOf: - type: boolean - type: 'null' title: Parallel Tool Calls description: 'Deprecated: Use `model_settings` to configure parallel tool calls instead. If set to True, enables parallel tool calling.' deprecated: true type: object title: CreateAgentRequest description: CreateAgent model specifically for POST request body, excluding user_id which comes from headers CreateArchivalMemory: properties: text: type: string title: Text description: Text to write to archival memory. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: Optional list of tags to attach to the memory. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: Optional timestamp for the memory (defaults to current UTC time). type: object required: - text title: CreateArchivalMemory CreateBatch: properties: requests: items: $ref: '#/components/schemas/LettaBatchRequest' type: array title: Requests description: List of requests to be processed in batch. callback_url: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Callback Url description: 'Optional URL to call via POST when the batch completes. The callback payload will be a JSON object with the following fields: {''job_id'': string, ''status'': string, ''completed_at'': string}. Where ''job_id'' is the unique batch job identifier, ''status'' is the final batch status (e.g., ''completed'', ''failed''), and ''completed_at'' is an ISO 8601 timestamp indicating when the batch job completed.' type: object required: - requests title: CreateBatch CreateBlock: 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: Name of the block if it is a template. is_template: type: boolean title: Is Template default: false template_id: anyOf: - type: string - type: 'null' title: Template Id description: The id of the template. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template id of the block. deployment_id: anyOf: - type: string - type: 'null' title: Deployment Id description: The id of the deployment. entity_id: anyOf: - type: string - type: 'null' title: Entity Id description: The id of the entity within the template. preserve_on_migration: anyOf: - type: boolean - type: 'null' title: Preserve On Migration description: Preserve the block on template migration. default: false label: type: string title: Label description: Label of the block. read_only: type: boolean title: Read Only description: Whether the agent has read-only access to the block. default: false 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: If set to True, the block will be hidden. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags to associate with the block. type: object required: - value - label title: CreateBlock description: Create a block CreateConversation: properties: summary: anyOf: - type: string - type: 'null' title: Summary description: A summary of the conversation. isolated_block_labels: anyOf: - items: type: string type: array - type: 'null' title: Isolated Block Labels description: List of block labels that should be isolated (conversation-specific) rather than shared across conversations. New blocks will be created as copies of the agent's blocks with these labels. model: anyOf: - type: string - type: 'null' title: Model description: 'The model handle for this conversation (overrides agent''s model). Format: provider/model-name.' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: The model settings for this conversation (overrides agent's model settings). type: object title: CreateConversation description: Request model for creating a new conversation. CreateMCPServerRequest: properties: server_name: type: string title: Server Name description: The name of the MCP server config: oneOf: - $ref: '#/components/schemas/CreateStdioMCPServer' - $ref: '#/components/schemas/CreateSSEMCPServer' - $ref: '#/components/schemas/CreateStreamableHTTPMCPServer' title: Config description: The MCP server configuration (Stdio, SSE, or Streamable HTTP) discriminator: propertyName: mcp_server_type mapping: sse: '#/components/schemas/CreateSSEMCPServer' stdio: '#/components/schemas/CreateStdioMCPServer' streamable_http: '#/components/schemas/CreateStreamableHTTPMCPServer' additionalProperties: false type: object required: - server_name - config title: CreateMCPServerRequest description: Request to create a new MCP server with configuration. CreateSSEMCPServer: properties: mcp_server_type: type: string const: sse title: Mcp Server Type default: sse server_url: type: string title: Server Url description: The URL of the server auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom HTTP headers to include with requests additionalProperties: false type: object required: - server_url title: CreateSSEMCPServer description: Create a new SSE MCP server CreateStdioMCPServer: properties: mcp_server_type: type: string const: stdio title: Mcp Server Type default: stdio command: type: string title: Command description: The command to run (MCP 'local' client will run this command) args: items: type: string type: array title: Args description: The arguments to pass to the command env: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Env description: Environment variables to set additionalProperties: false type: object required: - command - args title: CreateStdioMCPServer description: Create a new Stdio MCP server CreateStreamableHTTPMCPServer: properties: mcp_server_type: type: string const: streamable_http title: Mcp Server Type default: streamable_http server_url: type: string title: Server Url description: The URL of the server auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom HTTP headers to include with requests additionalProperties: false type: object required: - server_url title: CreateStreamableHTTPMCPServer description: Create a new Streamable HTTP MCP server Custom-Input: properties: input: type: string title: Input name: type: string title: Name type: object required: - input - name title: Custom description: The custom tool that the model called. Custom-Output: properties: input: type: string title: Input name: type: string title: Name additionalProperties: true type: object required: - input - name title: Custom description: The custom tool that the model called. DeepseekModelSettings: 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: deepseek title: Provider Type description: The type of the provider. default: deepseek temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 response_format: 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 Format description: The response format for the model. type: object title: DeepseekModelSettings description: Deepseek model configuration (OpenAI-compatible). DeleteDeploymentResponse: properties: deleted_blocks: items: type: string type: array title: Deleted Blocks default: [] deleted_agents: items: type: string type: array title: Deleted Agents default: [] deleted_groups: items: type: string type: array title: Deleted Groups default: [] message: type: string title: Message type: object required: - message title: DeleteDeploymentResponse description: Response model for delete deployment operation. DeploymentEntity: properties: id: type: string title: Id type: type: string title: Type name: anyOf: - type: string - type: 'null' title: Name description: anyOf: - type: string - type: 'null' title: Description entity_id: anyOf: - type: string - type: 'null' title: Entity Id project_id: anyOf: - type: string - type: 'null' title: Project Id type: object required: - id - type title: DeploymentEntity description: A deployment entity. DuplicateFileHandling: type: string enum: - skip - error - suffix - replace title: DuplicateFileHandling description: How to handle duplicate filenames when uploading files DynamicManager: properties: manager_type: type: string const: dynamic title: Manager Type description: '' default: dynamic manager_agent_id: type: string maxLength: 42 minLength: 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}$ title: Manager Agent Id description: '' examples: - agent-123e4567-e89b-42d3-8456-426614174000 termination_token: anyOf: - type: string - type: 'null' title: Termination Token description: '' default: DONE! max_turns: anyOf: - type: integer - type: 'null' title: Max Turns description: '' type: object required: - manager_agent_id title: DynamicManager DynamicManagerSchema: properties: manager_type: type: string const: dynamic title: Manager Type description: '' default: dynamic manager_agent_id: type: string title: Manager Agent Id description: '' termination_token: anyOf: - type: string - type: 'null' title: Termination Token description: '' default: DONE! max_turns: anyOf: - type: integer - type: 'null' title: Max Turns description: '' type: object required: - manager_agent_id title: DynamicManagerSchema DynamicManagerUpdate: properties: manager_type: type: string const: dynamic title: Manager Type description: '' default: dynamic manager_agent_id: anyOf: - type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 - type: 'null' title: Manager Agent Id description: '' termination_token: anyOf: - type: string - type: 'null' title: Termination Token description: '' max_turns: anyOf: - type: integer - type: 'null' title: Max Turns description: '' type: object title: DynamicManagerUpdate E2BSandboxConfig: properties: timeout: type: integer title: Timeout description: Time limit for the sandbox (in seconds). default: 300 template: anyOf: - type: string - type: 'null' title: Template description: The E2B template id (docker image). pip_requirements: anyOf: - items: type: string type: array - type: 'null' title: Pip Requirements description: A list of pip packages to install on the E2B Sandbox type: object title: E2BSandboxConfig EmbeddingConfig: properties: embedding_endpoint_type: type: string enum: - openai - anthropic - bedrock - google_ai - google_vertex - azure - groq - ollama - webui - webui-legacy - lmstudio - lmstudio-legacy - llamacpp - koboldcpp - vllm - hugging-face - mistral - together - pinecone title: Embedding Endpoint Type description: The endpoint type for the model. embedding_endpoint: anyOf: - type: string - type: 'null' title: Embedding Endpoint description: The endpoint for the model (`None` if local). embedding_model: type: string title: Embedding Model description: The model for the embedding. embedding_dim: type: integer title: Embedding Dim description: The dimension of the embedding. embedding_chunk_size: anyOf: - type: integer - type: 'null' title: Embedding Chunk Size description: The chunk size of the embedding. default: 300 handle: anyOf: - type: string - type: 'null' title: Handle description: The handle for this config, in the format provider/model-name. batch_size: type: integer title: Batch Size description: The maximum batch size for processing embeddings. default: 32 azure_endpoint: anyOf: - type: string - type: 'null' title: Azure Endpoint description: The Azure endpoint for the model. azure_version: anyOf: - type: string - type: 'null' title: Azure Version description: The Azure version for the model. azure_deployment: anyOf: - type: string - type: 'null' title: Azure Deployment description: The Azure deployment for the model. type: object required: - embedding_endpoint_type - embedding_model - embedding_dim title: EmbeddingConfig description: Configuration for embedding model connection and processing parameters. EmbeddingModel: properties: handle: anyOf: - type: string - type: 'null' title: Handle description: The handle for this config, in the format provider/model-name. name: type: string title: Name description: The actual model name used by the provider display_name: type: string title: Display Name description: Display name for the model shown in UI provider_type: $ref: '#/components/schemas/ProviderType' description: The type of the provider provider_name: type: string title: Provider Name description: The name of the provider model_type: type: string const: embedding title: Model Type description: Type of model (llm or embedding) default: embedding embedding_endpoint_type: type: string enum: - openai - anthropic - bedrock - google_ai - google_vertex - azure - groq - ollama - webui - webui-legacy - lmstudio - lmstudio-legacy - llamacpp - koboldcpp - vllm - hugging-face - mistral - together - pinecone title: Embedding Endpoint Type description: 'Deprecated: Use ''provider_type'' field instead. The endpoint type for the embedding model.' deprecated: true embedding_endpoint: anyOf: - type: string - type: 'null' title: Embedding Endpoint description: 'Deprecated: The endpoint for the model.' deprecated: true embedding_model: type: string title: Embedding Model description: 'Deprecated: Use ''name'' field instead. Embedding model name.' deprecated: true embedding_dim: type: integer title: Embedding Dim description: The dimension of the embedding embedding_chunk_size: anyOf: - type: integer - type: 'null' title: Embedding Chunk Size description: 'Deprecated: The chunk size of the embedding.' default: 300 deprecated: true batch_size: type: integer title: Batch Size description: 'Deprecated: The maximum batch size for processing embeddings.' default: 32 deprecated: true azure_endpoint: anyOf: - type: string - type: 'null' title: Azure Endpoint description: 'Deprecated: The Azure endpoint for the model.' deprecated: true azure_version: anyOf: - type: string - type: 'null' title: Azure Version description: 'Deprecated: The Azure version for the model.' deprecated: true azure_deployment: anyOf: - type: string - type: 'null' title: Azure Deployment description: 'Deprecated: The Azure deployment for the model.' deprecated: true type: object required: - name - display_name - provider_type - provider_name - embedding_endpoint_type - embedding_model - embedding_dim title: EmbeddingModel EventMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: event_message title: Message Type default: event_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id event_type: type: string const: compaction title: Event Type event_data: additionalProperties: true type: object title: Event Data type: object required: - id - date - event_type - event_data title: EventMessage description: A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. ExportAgentRequest: properties: skills: items: $ref: '#/components/schemas/SkillSchema' type: array title: Skills description: Skills to include in the export. Each skill must have a name and files (including SKILL.md). conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: Conversation ID to export. If provided, uses messages from this conversation instead of the agent's global message history. scrub_messages: type: boolean title: Scrub Messages description: If True, excludes all messages from the export. Useful for sharing agent configs without conversation history. default: false type: object title: ExportAgentRequest description: Request body for POST /export endpoint. FeedbackType: type: string enum: - positive - negative title: FeedbackType File: properties: file: $ref: '#/components/schemas/FileFile' type: type: string const: file title: Type type: object required: - file - type title: File description: Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text generation. FileAgentSchema: properties: agent_id: type: string title: Agent Id description: Unique identifier of the agent. file_id: type: string title: File Id description: Unique identifier of the file. source_id: type: string title: Source Id description: 'Deprecated: Use `folder_id` field instead. Unique identifier of the source.' deprecated: true file_name: type: string title: File Name description: Name of the file. is_open: type: boolean title: Is Open description: True if the agent currently has the file open. default: true visible_content: anyOf: - type: string - type: 'null' title: Visible Content description: Portion of the file the agent is focused on (may be large). last_accessed_at: anyOf: - type: string format: date-time - type: 'null' title: Last Accessed At description: UTC timestamp of the agent's most recent access to this file. start_line: anyOf: - type: integer - type: 'null' title: Start Line description: Starting line number (1-indexed) when file was opened with line range. end_line: anyOf: - type: integer - type: 'null' title: End Line description: Ending line number (exclusive) when file was opened with line range. id: type: string title: Id description: Human-readable identifier for this file-agent relationship in the file additionalProperties: false type: object required: - agent_id - file_id - source_id - file_name - id title: FileAgentSchema description: File-Agent relationship with human-readable ID for agent file FileBlock: 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: Name of the block if it is a template. 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: The id of the template. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template id of the block. deployment_id: anyOf: - type: string - type: 'null' title: Deployment Id description: The id of the deployment. entity_id: anyOf: - type: string - type: 'null' title: Entity Id description: The id of the entity within the template. preserve_on_migration: anyOf: - type: boolean - type: 'null' title: Preserve On Migration description: Preserve the block on template migration. default: false 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: Whether the agent has read-only access to the block. default: false 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: If set to True, the block will be hidden. id: type: string pattern: ^block-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Block examples: - block-123e4567-e89b-12d3-a456-426614174000 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: [] file_id: type: string title: File Id description: Unique identifier of the file. source_id: type: string title: Source Id description: 'Deprecated: Use `folder_id` field instead. Unique identifier of the source.' deprecated: true is_open: type: boolean title: Is Open description: True if the agent currently has the file open. last_accessed_at: anyOf: - type: string format: date-time - type: 'null' title: Last Accessed At description: UTC timestamp of the agent’s most recent access to this file. Any operations from the open, close, or search tools will update this field. type: object required: - value - file_id - source_id - is_open title: FileBlock FileFile: properties: file_data: type: string title: File Data file_id: type: string title: File Id filename: type: string title: Filename type: object title: FileFile FileMetadata: properties: source_id: type: string title: Source Id description: 'Deprecated: Use `folder_id` field instead. The unique identifier of the source associated with the document.' deprecated: true file_name: anyOf: - type: string - type: 'null' title: File Name description: The name of the file. original_file_name: anyOf: - type: string - type: 'null' title: Original File Name description: The original name of the file as uploaded. file_path: anyOf: - type: string - type: 'null' title: File Path description: The path to the file. file_type: anyOf: - type: string - type: 'null' title: File Type description: The type of the file (MIME type). file_size: anyOf: - type: integer - type: 'null' title: File Size description: The size of the file in bytes. file_creation_date: anyOf: - type: string - type: 'null' title: File Creation Date description: The creation date of the file. file_last_modified_date: anyOf: - type: string - type: 'null' title: File Last Modified Date description: The last modified date of the file. processing_status: $ref: '#/components/schemas/FileProcessingStatus' description: The current processing status of the file (e.g. pending, parsing, embedding, completed, error). default: pending error_message: anyOf: - type: string - type: 'null' title: Error Message description: Optional error message if the file failed processing. total_chunks: anyOf: - type: integer - type: 'null' title: Total Chunks description: Total number of chunks for the file. chunks_embedded: anyOf: - type: integer - type: 'null' title: Chunks Embedded description: Number of chunks that have been embedded. content: anyOf: - type: string - type: 'null' title: Content description: Optional full-text content of the file; only populated on demand due to its size. id: type: string pattern: ^file-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the File examples: - file-123e4567-e89b-12d3-a456-426614174000 created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: The creation date of the file. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The update date of the file. additionalProperties: false type: object required: - source_id title: FileMetadata description: Representation of a single FileMetadata FileProcessingStatus: type: string enum: - pending - parsing - embedding - completed - error title: FileProcessingStatus FileSchema: properties: source_id: type: string title: Source Id description: 'Deprecated: Use `folder_id` field instead. The unique identifier of the source associated with the document.' deprecated: true file_name: anyOf: - type: string - type: 'null' title: File Name description: The name of the file. original_file_name: anyOf: - type: string - type: 'null' title: Original File Name description: The original name of the file as uploaded. file_path: anyOf: - type: string - type: 'null' title: File Path description: The path to the file. file_type: anyOf: - type: string - type: 'null' title: File Type description: The type of the file (MIME type). file_size: anyOf: - type: integer - type: 'null' title: File Size description: The size of the file in bytes. file_creation_date: anyOf: - type: string - type: 'null' title: File Creation Date description: The creation date of the file. file_last_modified_date: anyOf: - type: string - type: 'null' title: File Last Modified Date description: The last modified date of the file. processing_status: $ref: '#/components/schemas/FileProcessingStatus' description: The current processing status of the file (e.g. pending, parsing, embedding, completed, error). default: pending error_message: anyOf: - type: string - type: 'null' title: Error Message description: Optional error message if the file failed processing. total_chunks: anyOf: - type: integer - type: 'null' title: Total Chunks description: Total number of chunks for the file. chunks_embedded: anyOf: - type: integer - type: 'null' title: Chunks Embedded description: Number of chunks that have been embedded. content: anyOf: - type: string - type: 'null' title: Content description: Optional full-text content of the file; only populated on demand due to its size. id: type: string title: Id description: Human-readable identifier for this file in the file additionalProperties: false type: object required: - source_id - id title: FileSchema description: File with human-readable ID for agent file FileStats: properties: file_id: type: string title: File Id description: Unique identifier of the file file_name: type: string title: File Name description: Name of the file file_size: anyOf: - type: integer - type: 'null' title: File Size description: Size of the file in bytes additionalProperties: false type: object required: - file_id - file_name title: FileStats description: File statistics for metadata endpoint Folder: properties: name: type: string title: Name description: The name of the folder. description: anyOf: - type: string - type: 'null' title: Description description: The description of the folder. instructions: anyOf: - type: string - type: 'null' title: Instructions description: Instructions for how to use the folder. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Metadata associated with the folder. id: type: string pattern: ^source-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Source examples: - source-123e4567-e89b-12d3-a456-426614174000 embedding_config: $ref: '#/components/schemas/EmbeddingConfig' description: The embedding configuration used by the folder. 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. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: The timestamp when the folder was created. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The timestamp when the folder was last updated. additionalProperties: false type: object required: - name - embedding_config title: Folder description: Representation of a folder, which is a collection of files and passages. Function-Output: properties: arguments: type: string title: Arguments name: type: string title: Name additionalProperties: true type: object required: - arguments - name title: Function description: The function that the model called. FunctionCall-Input: properties: arguments: type: string title: Arguments name: type: string title: Name type: object required: - arguments - name title: FunctionCall description: 'Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.' FunctionCall-Output: properties: arguments: type: string title: Arguments name: type: string title: Name additionalProperties: true type: object required: - arguments - name title: FunctionCall description: 'Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.' FunctionDefinition: properties: name: type: string title: Name description: anyOf: - type: string - type: 'null' title: Description parameters: anyOf: - additionalProperties: true type: object - type: 'null' title: Parameters strict: anyOf: - type: boolean - type: 'null' title: Strict additionalProperties: true type: object required: - name title: FunctionDefinition FunctionTool: properties: function: $ref: '#/components/schemas/FunctionDefinition' type: type: string const: function title: Type additionalProperties: true type: object required: - function - type title: FunctionTool GeminiThinkingConfig: properties: include_thoughts: type: boolean title: Include Thoughts description: Whether to include thoughts in the model's response. default: true thinking_budget: type: integer title: Thinking Budget description: The thinking budget for the model. default: 1024 type: object title: GeminiThinkingConfig GenerateRequest: properties: prompt: type: string minLength: 1 title: Prompt description: The prompt/message to send to the LLM system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: Optional system prompt to prepend to the conversation override_model: anyOf: - type: string - type: 'null' title: Override Model description: Model handle to use instead of agent's default (e.g., 'openai/gpt-4', 'anthropic/claude-3-5-sonnet') response_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Response Schema description: JSON schema for structured output. When provided, the LLM will be forced to return a response matching this schema via tool calling. The schema should follow JSON Schema format with 'properties' and optionally 'required' fields. type: object required: - prompt title: GenerateRequest description: Request for direct LLM generation without agent processing. GenerateResponse: properties: content: type: string title: Content description: The LLM's response text model: type: string title: Model description: The model that generated this response usage: $ref: '#/components/schemas/LettaUsageStatistics' description: Token usage statistics type: object required: - content - model - usage title: GenerateResponse description: Response from direct LLM generation. GenerateToolInput: properties: tool_name: type: string title: Tool Name description: Name of the tool to generate code for prompt: type: string title: Prompt description: User prompt to generate code handle: anyOf: - type: string - type: 'null' title: Handle description: Handle of the tool to generate code for starter_code: anyOf: - type: string - type: 'null' title: Starter Code description: Python source code to parse for JSON schema validation_errors: items: type: string type: array title: Validation Errors description: List of validation errors type: object required: - tool_name - prompt - validation_errors title: GenerateToolInput GenerateToolOutput: properties: tool: $ref: '#/components/schemas/Tool' description: Generated tool sample_args: additionalProperties: true type: object title: Sample Args description: Sample arguments for the tool response: type: string title: Response description: Response from the assistant type: object required: - tool - sample_args - response title: GenerateToolOutput 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 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 GroqModelSettings: 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: groq title: Provider Type description: The type of the provider. default: groq temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 response_format: 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 Format description: The response format for the model. type: object title: GroqModelSettings description: Groq model configuration (OpenAI-compatible). Group: properties: id: type: string title: Id description: The id of the group. Assigned by the database. manager_type: $ref: '#/components/schemas/ManagerType' description: '' agent_ids: items: type: string type: array title: Agent Ids description: '' description: type: string title: Description description: '' project_id: anyOf: - type: string - type: 'null' title: Project Id description: The associated project id. template_id: anyOf: - type: string - type: 'null' title: Template Id description: The id of the template. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template id. deployment_id: anyOf: - type: string - type: 'null' title: Deployment Id description: The id of the deployment. shared_block_ids: items: type: string type: array title: Shared Block Ids description: '' default: [] deprecated: true manager_agent_id: anyOf: - type: string - type: 'null' title: Manager Agent Id description: '' termination_token: anyOf: - type: string - type: 'null' title: Termination Token description: '' max_turns: anyOf: - type: integer - type: 'null' title: Max Turns description: '' sleeptime_agent_frequency: anyOf: - type: integer - type: 'null' title: Sleeptime Agent Frequency description: '' turns_counter: anyOf: - type: integer - type: 'null' title: Turns Counter description: '' last_processed_message_id: anyOf: - type: string - type: 'null' title: Last Processed Message Id description: '' max_message_buffer_length: anyOf: - type: integer - type: 'null' title: Max Message Buffer Length description: The desired maximum length of messages in the context window of the convo agent. This is a best effort, and may be off slightly due to user/assistant interleaving. min_message_buffer_length: anyOf: - type: integer - type: 'null' title: Min Message Buffer Length description: The desired minimum length of messages in the context window of the convo agent. This is a best effort, and may be off-by-one due to user/assistant interleaving. hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: If set to True, the group will be hidden. additionalProperties: false type: object required: - id - manager_type - agent_ids - description title: Group GroupCreate: properties: agent_ids: items: type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: array title: Agent Ids description: '' description: type: string title: Description description: '' manager_config: oneOf: - $ref: '#/components/schemas/RoundRobinManager' - $ref: '#/components/schemas/SupervisorManager' - $ref: '#/components/schemas/DynamicManager' - $ref: '#/components/schemas/SleeptimeManager' - $ref: '#/components/schemas/VoiceSleeptimeManager' title: Manager Config description: '' default: manager_type: round_robin discriminator: propertyName: manager_type mapping: dynamic: '#/components/schemas/DynamicManager' round_robin: '#/components/schemas/RoundRobinManager' sleeptime: '#/components/schemas/SleeptimeManager' supervisor: '#/components/schemas/SupervisorManager' voice_sleeptime: '#/components/schemas/VoiceSleeptimeManager' project_id: anyOf: - type: string - type: 'null' title: Project Id description: The associated project id. shared_block_ids: items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array title: Shared Block Ids description: '' default: [] deprecated: true hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: If set to True, the group will be hidden. type: object required: - agent_ids - description title: GroupCreate GroupSchema: properties: agent_ids: items: type: string type: array title: Agent Ids description: List of agent IDs in this group description: type: string title: Description description: '' manager_config: oneOf: - $ref: '#/components/schemas/RoundRobinManager' - $ref: '#/components/schemas/SupervisorManagerSchema' - $ref: '#/components/schemas/DynamicManagerSchema' - $ref: '#/components/schemas/SleeptimeManagerSchema' - $ref: '#/components/schemas/VoiceSleeptimeManagerSchema' title: Manager Config description: '' default: manager_type: round_robin discriminator: propertyName: manager_type mapping: dynamic: '#/components/schemas/DynamicManagerSchema' round_robin: '#/components/schemas/RoundRobinManager' sleeptime: '#/components/schemas/SleeptimeManagerSchema' supervisor: '#/components/schemas/SupervisorManagerSchema' voice_sleeptime: '#/components/schemas/VoiceSleeptimeManagerSchema' project_id: anyOf: - type: string - type: 'null' title: Project Id description: The associated project id. shared_block_ids: items: type: string type: array title: Shared Block Ids description: List of shared block IDs default: [] hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: If set to True, the group will be hidden. id: type: string title: Id description: Human-readable identifier for this group in the file type: object required: - agent_ids - description - id title: GroupSchema description: Group with human-readable ID for agent file GroupUpdate: properties: agent_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Agent Ids description: '' description: anyOf: - type: string - type: 'null' title: Description description: '' manager_config: anyOf: - oneOf: - $ref: '#/components/schemas/RoundRobinManagerUpdate' - $ref: '#/components/schemas/SupervisorManagerUpdate' - $ref: '#/components/schemas/DynamicManagerUpdate' - $ref: '#/components/schemas/SleeptimeManagerUpdate' - $ref: '#/components/schemas/VoiceSleeptimeManagerUpdate' discriminator: propertyName: manager_type mapping: dynamic: '#/components/schemas/DynamicManagerUpdate' round_robin: '#/components/schemas/RoundRobinManagerUpdate' sleeptime: '#/components/schemas/SleeptimeManagerUpdate' supervisor: '#/components/schemas/SupervisorManagerUpdate' voice_sleeptime: '#/components/schemas/VoiceSleeptimeManagerUpdate' - type: 'null' title: Manager Config description: '' project_id: anyOf: - type: string - type: 'null' title: Project Id description: The associated project id. shared_block_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Shared Block Ids description: '' deprecated: true type: object title: GroupUpdate HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Health: properties: version: type: string title: Version status: type: string title: Status type: object required: - version - status title: Health description: Health check response body HiddenReasoningMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: hidden_reasoning_message title: Message Type description: The type of the message. default: hidden_reasoning_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id state: type: string enum: - redacted - omitted title: State hidden_reasoning: anyOf: - type: string - type: 'null' title: Hidden Reasoning type: object required: - id - date - state title: HiddenReasoningMessage description: "Representation of an agent's internal reasoning where reasoning content\nhas been hidden from the response.\n\ \nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n\ \ name (Optional[str]): The name of the sender of the message\n state (Literal[\"redacted\", \"omitted\"]):\ \ Whether the reasoning\n content was redacted by the provider or simply omitted by the API\n hidden_reasoning\ \ (Optional[str]): The internal reasoning of the agent" Identity: properties: id: type: string pattern: ^identity-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Identity examples: - identity-123e4567-e89b-12d3-a456-426614174000 identifier_key: type: string title: Identifier Key description: External, user-generated identifier key of the identity. name: type: string title: Name description: The name of the identity. identity_type: $ref: '#/components/schemas/IdentityType' description: The type of the identity. project_id: anyOf: - type: string - type: 'null' title: Project Id description: The project id of the identity, if applicable. agent_ids: items: type: string type: array title: Agent Ids description: The IDs of the agents associated with the identity. deprecated: true block_ids: items: type: string type: array title: Block Ids description: The IDs of the blocks associated with the identity. deprecated: true properties: items: $ref: '#/components/schemas/IdentityProperty' type: array title: Properties description: List of properties associated with the identity additionalProperties: false type: object required: - identifier_key - name - identity_type - agent_ids - block_ids title: Identity IdentityCreate: properties: identifier_key: type: string title: Identifier Key description: External, user-generated identifier key of the identity. name: type: string title: Name description: The name of the identity. identity_type: $ref: '#/components/schemas/IdentityType' description: The type of the identity. project_id: anyOf: - type: string - type: 'null' title: Project Id description: The project id of the identity, if applicable. agent_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Agent Ids description: The agent ids that are associated with the identity. deprecated: true block_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Block Ids description: The IDs of the blocks associated with the identity. deprecated: true properties: anyOf: - items: $ref: '#/components/schemas/IdentityProperty' type: array - type: 'null' title: Properties description: List of properties associated with the identity. additionalProperties: false type: object required: - identifier_key - name - identity_type title: IdentityCreate IdentityProperty: properties: key: type: string title: Key description: The key of the property value: anyOf: - type: string - type: integer - type: number - type: boolean - additionalProperties: true type: object title: Value description: The value of the property type: $ref: '#/components/schemas/IdentityPropertyType' description: The type of the property additionalProperties: false type: object required: - key - value - type title: IdentityProperty description: A property of an identity IdentityPropertyType: type: string enum: - string - number - boolean - json title: IdentityPropertyType description: Enum to represent the type of the identity property. IdentityType: type: string enum: - org - user - other title: IdentityType description: Enum to represent the type of the identity. IdentityUpdate: properties: identifier_key: anyOf: - type: string - type: 'null' title: Identifier Key description: External, user-generated identifier key of the identity. name: anyOf: - type: string - type: 'null' title: Name description: The name of the identity. identity_type: anyOf: - $ref: '#/components/schemas/IdentityType' - type: 'null' description: The type of the identity. agent_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Agent Ids description: The agent ids that are associated with the identity. deprecated: true block_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Block Ids description: The IDs of the blocks associated with the identity. deprecated: true properties: anyOf: - items: $ref: '#/components/schemas/IdentityProperty' type: array - type: 'null' title: Properties description: List of properties associated with the identity. additionalProperties: false type: object title: IdentityUpdate IdentityUpsert: properties: identifier_key: type: string title: Identifier Key description: External, user-generated identifier key of the identity. name: type: string title: Name description: The name of the identity. identity_type: $ref: '#/components/schemas/IdentityType' description: The type of the identity. project_id: anyOf: - type: string - type: 'null' title: Project Id description: The project id of the identity, if applicable. agent_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Agent Ids description: The agent ids that are associated with the identity. deprecated: true block_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Block Ids description: The IDs of the blocks associated with the identity. deprecated: true properties: anyOf: - items: $ref: '#/components/schemas/IdentityProperty' type: array - type: 'null' title: Properties description: List of properties associated with the identity. additionalProperties: false type: object required: - identifier_key - name - identity_type title: IdentityUpsert ImageContent: properties: type: type: string const: image title: Type description: The type of the message. default: image source: oneOf: - $ref: '#/components/schemas/UrlImage' - $ref: '#/components/schemas/Base64Image' - $ref: '#/components/schemas/LettaImage' title: Source description: The source of the image. discriminator: propertyName: type mapping: base64: '#/components/schemas/Base64Image' letta: '#/components/schemas/LettaImage' url: '#/components/schemas/UrlImage' type: object required: - source title: ImageContent ImageURL: properties: url: type: string title: Url detail: type: string enum: - auto - low - high title: Detail type: object required: - url title: ImageURL ImportedAgentsResponse: properties: agent_ids: items: type: string type: array title: Agent Ids description: List of IDs of the imported agents type: object required: - agent_ids title: ImportedAgentsResponse description: Response model for imported agents InitToolRule: 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: run_first title: Type default: run_first prompt_template: anyOf: - type: string - type: 'null' title: Prompt Template description: Optional template string (ignored). Rendering uses fast built-in formatting for performance. args: anyOf: - additionalProperties: true type: object - type: 'null' title: Args description: Optional prefilled arguments for this tool. When present, these values will override any LLM-provided arguments with the same keys during invocation. Keys must match the tool's parameter names and values must satisfy the tool's JSON schema. Supports partial prefill; non-overlapping parameters are left to the model. additionalProperties: false type: object required: - tool_name title: InitToolRule description: Represents the initial tool rule configuration. InputAudio: properties: data: type: string title: Data format: type: string enum: - wav - mp3 title: Format type: object required: - data - format title: InputAudio InternalTemplateAgentCreate: properties: name: type: string title: Name description: The name of the agent. memory_blocks: anyOf: - items: $ref: '#/components/schemas/CreateBlock' type: array - type: 'null' title: Memory Blocks description: The blocks to create in the agent's in-context memory. tools: anyOf: - items: type: string type: array - type: 'null' title: Tools description: The tools used by the agent. tool_ids: anyOf: - items: type: string maxLength: 41 minLength: 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-' examples: - tool-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Tool Ids description: The ids of the tools used by the agent. source_ids: anyOf: - items: type: string maxLength: 43 minLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Source Ids description: 'Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent.' deprecated: true folder_ids: anyOf: - items: type: string maxLength: 43 minLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Folder Ids description: The ids of the folders used by the agent. block_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Block Ids description: The ids of the blocks used by the agent. tool_rules: anyOf: - items: oneOf: - $ref: '#/components/schemas/ChildToolRule' - $ref: '#/components/schemas/InitToolRule' - $ref: '#/components/schemas/TerminalToolRule' - $ref: '#/components/schemas/ConditionalToolRule' - $ref: '#/components/schemas/ContinueToolRule' - $ref: '#/components/schemas/RequiredBeforeExitToolRule' - $ref: '#/components/schemas/MaxCountPerStepToolRule' - $ref: '#/components/schemas/ParentToolRule' - $ref: '#/components/schemas/RequiresApprovalToolRule' discriminator: propertyName: type mapping: conditional: '#/components/schemas/ConditionalToolRule' constrain_child_tools: '#/components/schemas/ChildToolRule' continue_loop: '#/components/schemas/ContinueToolRule' exit_loop: '#/components/schemas/TerminalToolRule' max_count_per_step: '#/components/schemas/MaxCountPerStepToolRule' parent_last_tool: '#/components/schemas/ParentToolRule' required_before_exit: '#/components/schemas/RequiredBeforeExitToolRule' requires_approval: '#/components/schemas/RequiresApprovalToolRule' run_first: '#/components/schemas/InitToolRule' type: array - type: 'null' title: Tool Rules description: The tool rules governing the agent. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags associated with the agent. system: anyOf: - type: string - type: 'null' title: System description: The system prompt used by the agent. agent_type: $ref: '#/components/schemas/AgentType' description: The type of agent. initial_message_sequence: anyOf: - items: $ref: '#/components/schemas/MessageCreate' type: array - type: 'null' title: Initial Message Sequence description: The initial set of messages to put in the agent's in-context memory. include_base_tools: type: boolean title: Include Base Tools description: If true, attaches the Letta core tools (e.g. core_memory related functions). default: true include_multi_agent_tools: type: boolean title: Include Multi Agent Tools description: If true, attaches the Letta multi-agent tools (e.g. sending a message to another agent). default: false include_base_tool_rules: anyOf: - type: boolean - type: 'null' title: Include Base Tool Rules description: If true, attaches the Letta base tool rules (e.g. deny all tools not explicitly allowed). include_default_source: type: boolean title: Include Default Source description: If true, automatically creates and attaches a default data source for this agent. default: false deprecated: true description: anyOf: - type: string - type: 'null' title: Description description: The description of the agent. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: The metadata of the agent. llm_config: anyOf: - $ref: '#/components/schemas/LLMConfig' - type: 'null' description: 'Deprecated: Use `model` field instead. The LLM configuration used by the agent.' deprecated: true embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: 'Deprecated: Use `embedding` field instead. The embedding configuration used by the agent.' deprecated: true model: anyOf: - type: string - type: 'null' title: Model description: 'The model handle for the agent to use (format: provider/model-name).' embedding: anyOf: - type: string - type: 'null' title: Embedding description: 'The embedding model handle used by the agent (format: provider/model-name).' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: The model settings for the agent. compaction_settings: anyOf: - $ref: '#/components/schemas/CompactionSettings-Input' - type: 'null' description: The compaction settings configuration used for compaction. context_window_limit: anyOf: - type: integer - type: 'null' title: Context Window Limit description: The context window limit used by the agent. embedding_chunk_size: anyOf: - type: integer - type: 'null' title: Embedding Chunk Size description: 'Deprecated: No longer used. The embedding chunk size used by the agent.' default: 300 deprecated: true max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens description: 'Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step.' deprecated: true max_reasoning_tokens: anyOf: - type: integer - type: 'null' title: Max Reasoning Tokens description: 'Deprecated: Use `model` field to configure reasoning tokens instead. The maximum number of tokens to generate for reasoning step.' deprecated: true enable_reasoner: anyOf: - type: boolean - type: 'null' title: Enable Reasoner description: 'Deprecated: Use `model` field to configure reasoning instead. Whether to enable internal extended thinking step for a reasoner model.' default: true deprecated: true reasoning: anyOf: - type: boolean - type: 'null' title: Reasoning description: 'Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent.' deprecated: true from_template: anyOf: - type: string - type: 'null' title: From Template description: 'Deprecated: please use the ''create agents from a template'' endpoint instead.' deprecated: true template: type: boolean title: Template description: 'Deprecated: No longer used.' default: false deprecated: true project: anyOf: - type: string - type: 'null' title: Project description: 'Deprecated: Project should now be passed via the X-Project header instead of in the request body. If using the SDK, this can be done via the x_project parameter.' deprecated: true tool_exec_environment_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Tool Exec Environment Variables description: 'Deprecated: Use `secrets` field instead. Environment variables for tool execution.' deprecated: true secrets: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Secrets description: The environment variables for tool execution specific to this agent. memory_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Memory Variables description: 'Deprecated: Only relevant for creating agents from a template. Use the ''create agents from a template'' endpoint instead.' deprecated: true project_id: anyOf: - type: string - type: 'null' title: Project Id description: 'Deprecated: No longer used. The id of the project the agent belongs to.' deprecated: true template_id: type: string title: Template Id description: The id of the template. base_template_id: type: string title: Base Template Id description: The id of the base template. identity_ids: anyOf: - items: type: string maxLength: 45 minLength: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Identity Ids description: The ids of the identities associated with this agent. message_buffer_autoclear: type: boolean title: Message Buffer Autoclear description: If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case. default: false enable_sleeptime: anyOf: - type: boolean - type: 'null' title: Enable Sleeptime description: If set to True, memory management will move to a background agent thread. response_format: 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 Format description: 'Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent.' deprecated: true timezone: anyOf: - type: string - type: 'null' title: Timezone description: The timezone of the agent (IANA format). max_files_open: anyOf: - type: integer - type: 'null' title: Max Files Open description: Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent. per_file_view_window_char_limit: anyOf: - type: integer - type: 'null' title: Per File View Window Char Limit description: The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent. hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: 'Deprecated: No longer used. If set to True, the agent will be hidden.' deprecated: true parallel_tool_calls: anyOf: - type: boolean - type: 'null' title: Parallel Tool Calls description: 'Deprecated: Use `model_settings` to configure parallel tool calls instead. If set to True, enables parallel tool calling.' deprecated: true deployment_id: type: string title: Deployment Id description: The id of the deployment. entity_id: type: string title: Entity Id description: The id of the entity within the template. type: object required: - template_id - base_template_id - deployment_id - entity_id title: InternalTemplateAgentCreate description: Used for Letta Cloud InternalTemplateBlockCreate: 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: Name of the block if it is a template. is_template: type: boolean title: Is Template default: false template_id: type: string title: Template Id description: The id of the template. base_template_id: type: string title: Base Template Id description: The id of the base template. deployment_id: type: string title: Deployment Id description: The id of the deployment. entity_id: type: string title: Entity Id description: The id of the entity within the template. preserve_on_migration: anyOf: - type: boolean - type: 'null' title: Preserve On Migration description: Preserve the block on template migration. default: false label: type: string title: Label description: Label of the block. read_only: type: boolean title: Read Only description: Whether the agent has read-only access to the block. default: false 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: If set to True, the block will be hidden. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags to associate with the block. type: object required: - value - template_id - base_template_id - deployment_id - entity_id - label title: InternalTemplateBlockCreate description: Used for Letta Cloud InternalTemplateGroupCreate: properties: agent_ids: items: type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: array title: Agent Ids description: '' description: type: string title: Description description: '' manager_config: oneOf: - $ref: '#/components/schemas/RoundRobinManager' - $ref: '#/components/schemas/SupervisorManager' - $ref: '#/components/schemas/DynamicManager' - $ref: '#/components/schemas/SleeptimeManager' - $ref: '#/components/schemas/VoiceSleeptimeManager' title: Manager Config description: '' default: manager_type: round_robin discriminator: propertyName: manager_type mapping: dynamic: '#/components/schemas/DynamicManager' round_robin: '#/components/schemas/RoundRobinManager' sleeptime: '#/components/schemas/SleeptimeManager' supervisor: '#/components/schemas/SupervisorManager' voice_sleeptime: '#/components/schemas/VoiceSleeptimeManager' project_id: anyOf: - type: string - type: 'null' title: Project Id description: The associated project id. shared_block_ids: items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array title: Shared Block Ids description: '' default: [] deprecated: true hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: If set to True, the group will be hidden. base_template_id: type: string title: Base Template Id description: The id of the base template. template_id: type: string title: Template Id description: The id of the template. deployment_id: type: string title: Deployment Id description: The id of the deployment. type: object required: - agent_ids - description - base_template_id - template_id - deployment_id title: InternalTemplateGroupCreate description: Used for Letta Cloud Job: 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: type: string format: date-time title: Created At description: The unix timestamp of when the job was created. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The timestamp when the object was last updated. status: $ref: '#/components/schemas/JobStatus' description: The status of the job. default: created completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: The unix timestamp of when the job was completed. stop_reason: anyOf: - $ref: '#/components/schemas/StopReasonType' - type: 'null' description: The reason why the job was stopped. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: The metadata of the job. job_type: $ref: '#/components/schemas/JobType' description: The type of the job. default: job background: anyOf: - type: boolean - type: 'null' title: Background description: Whether the job was created in background mode. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The agent associated with this job/run. callback_url: anyOf: - type: string - type: 'null' title: Callback Url description: If set, POST to this URL when the job completes. callback_sent_at: anyOf: - type: string format: date-time - type: 'null' title: Callback Sent At description: Timestamp when the callback was last attempted. callback_status_code: anyOf: - type: integer - type: 'null' title: Callback Status Code description: HTTP status code returned by the callback endpoint. callback_error: anyOf: - type: string - type: 'null' title: Callback Error description: Optional error message from attempting to POST the callback endpoint. ttft_ns: anyOf: - type: integer - type: 'null' title: Ttft Ns description: Time to first token for a run in nanoseconds total_duration_ns: anyOf: - type: integer - type: 'null' title: Total Duration Ns description: Total run duration in nanoseconds id: type: string pattern: ^(job|run)-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Job examples: - job-123e4567-e89b-12d3-a456-426614174000 additionalProperties: false type: object title: Job description: Representation of offline jobs, used for tracking status of data loading tasks (involving parsing and embedding files). JobStatus: type: string enum: - created - running - completed - failed - pending - cancelled - expired title: JobStatus description: Status of the job. JobType: type: string enum: - job - run - batch title: JobType 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. JsonSchemaResponseFormat: properties: type: type: string const: json_schema title: Type description: The type of the response format. default: json_schema json_schema: additionalProperties: true type: object title: Json Schema description: The JSON schema of the response. type: object required: - json_schema title: JsonSchemaResponseFormat description: Response format for JSON schema-based responses. LLMConfig: properties: model: type: string title: Model description: 'LLM model name. ' display_name: anyOf: - type: string - type: 'null' title: Display Name description: A human-friendly display name for the model. model_endpoint_type: type: string enum: - openai - anthropic - google_ai - google_vertex - azure - groq - ollama - webui - webui-legacy - lmstudio - lmstudio-legacy - lmstudio-chatcompletions - llamacpp - koboldcpp - vllm - hugging-face - minimax - mistral - together - bedrock - deepseek - xai - zai - zai_coding - baseten - fireworks - openrouter - chatgpt_oauth title: Model Endpoint Type description: The endpoint type for the model. model_endpoint: anyOf: - type: string - type: 'null' title: Model Endpoint description: The endpoint for the model. provider_name: anyOf: - type: string - type: 'null' title: Provider Name description: The provider name for the model. provider_category: anyOf: - $ref: '#/components/schemas/ProviderCategory' - type: 'null' description: The provider category for the model. model_wrapper: anyOf: - type: string - type: 'null' title: Model Wrapper description: The wrapper for the model. context_window: type: integer title: Context Window description: The context window size for the model. put_inner_thoughts_in_kwargs: anyOf: - type: boolean - type: 'null' title: Put Inner Thoughts In Kwargs description: Puts 'inner_thoughts' as a kwarg in the function call if this is set to True. This helps with function calling performance and also the generation of inner thoughts. default: false handle: anyOf: - type: string - type: 'null' title: Handle description: The handle for this config, in the format provider/model-name. temperature: type: number title: Temperature description: The temperature to use when generating text with the model. A higher temperature will result in more random text. default: 1 max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens description: The maximum number of tokens to generate. If not set, the model will use its default value. enable_reasoner: type: boolean title: Enable Reasoner description: Whether or not the model should use extended thinking if it is a 'reasoning' style model default: true reasoning_effort: anyOf: - type: string enum: - none - minimal - low - medium - high - xhigh - type: 'null' title: Reasoning Effort description: The reasoning effort to use when generating text reasoning models max_reasoning_tokens: type: integer title: Max Reasoning Tokens description: Configurable thinking budget for extended thinking. Used for enable_reasoner and also for Google Vertex models like Gemini 2.5 Flash. Minimum value is 1024 when used with enable_reasoner. default: 0 effort: anyOf: - type: string enum: - low - medium - high - max - type: 'null' title: Effort description: The effort level for Anthropic models that support it (Opus 4.5, Opus 4.6). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. frequency_penalty: anyOf: - type: number - type: 'null' title: Frequency Penalty description: 'Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model''s likelihood to repeat the same line verbatim. From OpenAI: Number between -2.0 and 2.0.' compatibility_type: anyOf: - type: string enum: - gguf - mlx - type: 'null' title: Compatibility Type description: The framework compatibility type for the model. verbosity: anyOf: - type: string enum: - low - medium - high - type: 'null' title: Verbosity description: Soft control for how verbose model output should be, used for GPT-5 models. tier: anyOf: - type: string - type: 'null' title: Tier description: The cost tier for the model (cloud only). parallel_tool_calls: anyOf: - type: boolean - type: 'null' title: Parallel Tool Calls description: 'Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False.' default: false deprecated: true response_format: 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 Format description: The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. strict: type: boolean title: Strict description: 'Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.' default: false return_logprobs: type: boolean title: Return Logprobs description: Whether to return log probabilities of the output tokens. Useful for RL training. default: false top_logprobs: anyOf: - type: integer - type: 'null' title: Top Logprobs description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. return_token_ids: type: boolean title: Return Token Ids description: Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. default: false tool_call_parser: anyOf: - type: string - type: 'null' title: Tool Call Parser description: SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. type: object required: - model - model_endpoint_type - context_window title: LLMConfig description: "Configuration for Language Model (LLM) connection and generation parameters.\n\n.. deprecated::\n LLMConfig\ \ is deprecated and should not be used as an input or return type in API calls.\n Use the schemas in letta.schemas.model\ \ (ModelSettings, OpenAIModelSettings, etc.) instead.\n For conversion, use the _to_model() method or Model._from_llm_config()\ \ method." LettaAsyncRequest: properties: messages: anyOf: - items: anyOf: - $ref: '#/components/schemas/MessageCreate' - $ref: '#/components/schemas/ApprovalCreate' - $ref: '#/components/schemas/ToolReturnCreate' type: array - type: 'null' title: Messages description: The messages to be sent to the agent. input: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' - $ref: '#/components/schemas/SummarizedReasoningContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' summarized_reasoning: '#/components/schemas/SummarizedReasoningContent' text: '#/components/schemas/TextContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolReturnContent' type: array - type: 'null' title: Input description: 'Syntactic sugar for a single user message. Equivalent to messages=[{''role'': ''user'', ''content'': input}].' max_steps: type: integer title: Max Steps description: Maximum number of steps the agent should take to process the request. default: 50 use_assistant_message: type: boolean title: Use Assistant Message description: Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: true deprecated: true assistant_message_tool_name: type: string title: Assistant Message Tool Name description: The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: send_message deprecated: true assistant_message_tool_kwarg: type: string title: Assistant Message Tool Kwarg description: The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: message deprecated: true include_return_message_types: anyOf: - items: $ref: '#/components/schemas/MessageType' type: array - type: 'null' title: Include Return Message Types description: Only return specified message types in the response. If `None` (default) returns all messages. enable_thinking: type: string title: Enable Thinking description: If set to True, enables reasoning before responses or tool calls from the agent. default: true deprecated: true client_tools: anyOf: - items: $ref: '#/components/schemas/ClientToolSchema' type: array - type: 'null' title: Client Tools description: Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. client_skills: anyOf: - items: $ref: '#/components/schemas/ClientSkillSchema' type: array - type: 'null' title: Client Skills description: Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. override_model: anyOf: - type: string - type: 'null' title: Override Model description: Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. include_compaction_messages: type: boolean title: Include Compaction Messages description: If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. default: false return_logprobs: type: boolean title: Return Logprobs description: If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). default: false top_logprobs: anyOf: - type: integer - type: 'null' title: Top Logprobs description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. return_token_ids: type: boolean title: Return Token Ids description: If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. default: false override_system: anyOf: - type: string - type: 'null' title: Override System description: Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. callback_url: anyOf: - type: string - type: 'null' title: Callback Url description: Optional callback URL to POST to when the job completes type: object title: LettaAsyncRequest LettaBatchMessages: properties: messages: items: $ref: '#/components/schemas/Message' type: array title: Messages type: object required: - messages title: LettaBatchMessages LettaBatchRequest: properties: messages: anyOf: - items: anyOf: - $ref: '#/components/schemas/MessageCreate' - $ref: '#/components/schemas/ApprovalCreate' - $ref: '#/components/schemas/ToolReturnCreate' type: array - type: 'null' title: Messages description: The messages to be sent to the agent. input: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' - $ref: '#/components/schemas/SummarizedReasoningContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' summarized_reasoning: '#/components/schemas/SummarizedReasoningContent' text: '#/components/schemas/TextContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolReturnContent' type: array - type: 'null' title: Input description: 'Syntactic sugar for a single user message. Equivalent to messages=[{''role'': ''user'', ''content'': input}].' max_steps: type: integer title: Max Steps description: Maximum number of steps the agent should take to process the request. default: 50 use_assistant_message: type: boolean title: Use Assistant Message description: Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: true deprecated: true assistant_message_tool_name: type: string title: Assistant Message Tool Name description: The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: send_message deprecated: true assistant_message_tool_kwarg: type: string title: Assistant Message Tool Kwarg description: The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: message deprecated: true include_return_message_types: anyOf: - items: $ref: '#/components/schemas/MessageType' type: array - type: 'null' title: Include Return Message Types description: Only return specified message types in the response. If `None` (default) returns all messages. enable_thinking: type: string title: Enable Thinking description: If set to True, enables reasoning before responses or tool calls from the agent. default: true deprecated: true client_tools: anyOf: - items: $ref: '#/components/schemas/ClientToolSchema' type: array - type: 'null' title: Client Tools description: Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. client_skills: anyOf: - items: $ref: '#/components/schemas/ClientSkillSchema' type: array - type: 'null' title: Client Skills description: Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. override_model: anyOf: - type: string - type: 'null' title: Override Model description: Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. include_compaction_messages: type: boolean title: Include Compaction Messages description: If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. default: false return_logprobs: type: boolean title: Return Logprobs description: If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). default: false top_logprobs: anyOf: - type: integer - type: 'null' title: Top Logprobs description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. return_token_ids: type: boolean title: Return Token Ids description: If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. default: false override_system: anyOf: - type: string - type: 'null' title: Override System description: Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. agent_id: type: string maxLength: 42 minLength: 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}$ title: Agent Id description: The ID of the agent to send this batch request for examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: object required: - agent_id title: LettaBatchRequest LettaErrorMessage: properties: message_type: type: string const: error_message title: Message Type description: The type of the message. default: error_message run_id: type: string title: Run ID description: The ID of the run. error_type: type: string title: Error Type description: The type of error. message: type: string title: Message description: The error message. detail: type: string title: Detail description: An optional error detail. seq_id: type: integer title: Seq ID description: The sequence ID for cursor-based pagination. type: object required: - message_type - run_id - error_type - message title: LettaErrorMessage description: Error messages are used to notify the client of an error that occurred during the agent's execution. LettaImage: properties: type: type: string const: letta title: Type description: The source type for the image. default: letta file_id: type: string title: File Id description: The unique identifier of the image file persisted in storage. media_type: anyOf: - type: string - type: 'null' title: Media Type description: The media type for the image. data: anyOf: - type: string - type: 'null' title: Data description: The base64 encoded image data. detail: anyOf: - type: string - type: 'null' title: Detail description: What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) type: object required: - file_id title: LettaImage LettaPing: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: ping title: Message Type description: The type of the message. Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests. default: ping otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id type: object required: - id - date title: LettaPing description: "A ping message used as a keepalive to prevent SSE streams from timing out during long running requests.\n\ \nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format" LettaRequest: properties: messages: anyOf: - items: anyOf: - $ref: '#/components/schemas/MessageCreate' - $ref: '#/components/schemas/ApprovalCreate' - $ref: '#/components/schemas/ToolReturnCreate' type: array - type: 'null' title: Messages description: The messages to be sent to the agent. input: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' - $ref: '#/components/schemas/SummarizedReasoningContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' summarized_reasoning: '#/components/schemas/SummarizedReasoningContent' text: '#/components/schemas/TextContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolReturnContent' type: array - type: 'null' title: Input description: 'Syntactic sugar for a single user message. Equivalent to messages=[{''role'': ''user'', ''content'': input}].' max_steps: type: integer title: Max Steps description: Maximum number of steps the agent should take to process the request. default: 50 use_assistant_message: type: boolean title: Use Assistant Message description: Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: true deprecated: true assistant_message_tool_name: type: string title: Assistant Message Tool Name description: The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: send_message deprecated: true assistant_message_tool_kwarg: type: string title: Assistant Message Tool Kwarg description: The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: message deprecated: true include_return_message_types: anyOf: - items: $ref: '#/components/schemas/MessageType' type: array - type: 'null' title: Include Return Message Types description: Only return specified message types in the response. If `None` (default) returns all messages. enable_thinking: type: string title: Enable Thinking description: If set to True, enables reasoning before responses or tool calls from the agent. default: true deprecated: true client_tools: anyOf: - items: $ref: '#/components/schemas/ClientToolSchema' type: array - type: 'null' title: Client Tools description: Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. client_skills: anyOf: - items: $ref: '#/components/schemas/ClientSkillSchema' type: array - type: 'null' title: Client Skills description: Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. override_model: anyOf: - type: string - type: 'null' title: Override Model description: Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. include_compaction_messages: type: boolean title: Include Compaction Messages description: If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. default: false return_logprobs: type: boolean title: Return Logprobs description: If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). default: false top_logprobs: anyOf: - type: integer - type: 'null' title: Top Logprobs description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. return_token_ids: type: boolean title: Return Token Ids description: If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. default: false override_system: anyOf: - type: string - type: 'null' title: Override System description: Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. type: object title: LettaRequest LettaRequestConfig: properties: use_assistant_message: type: boolean title: Use Assistant Message description: Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. default: true assistant_message_tool_name: type: string title: Assistant Message Tool Name description: The name of the designated message tool. default: send_message assistant_message_tool_kwarg: type: string title: Assistant Message Tool Kwarg description: The name of the message argument in the designated message tool. default: message include_return_message_types: anyOf: - items: $ref: '#/components/schemas/MessageType' type: array - type: 'null' title: Include Return Message Types description: Only return specified message types in the response. If `None` (default) returns all messages. type: object title: LettaRequestConfig LettaResponse: properties: messages: items: $ref: '#/components/schemas/LettaMessageUnion' type: array title: Messages description: The messages returned by the agent. stop_reason: $ref: '#/components/schemas/LettaStopReason' usage: $ref: '#/components/schemas/LettaUsageStatistics' description: The usage statistics of the agent. logprobs: anyOf: - $ref: '#/components/schemas/letta__schemas__openai__chat_completion_response__ChoiceLogprobs' - type: 'null' description: Log probabilities of the output tokens from the last LLM call. Only present if return_logprobs was enabled. turns: anyOf: - items: $ref: '#/components/schemas/TurnTokenData' type: array - type: 'null' title: Turns description: Token data for all LLM generations in multi-turn agent interaction. Includes token IDs and logprobs for each assistant turn, plus tool result content. Only present if return_token_ids was enabled. Used for RL training with loss masking. type: object required: - messages - stop_reason - usage title: LettaResponse description: "Response object from an agent interaction, consisting of the new messages generated by the agent and usage\ \ statistics.\nThe type of the returned messages can be either `Message` or `LettaMessage`, depending on what was\ \ specified in the request.\n\nAttributes:\n messages (List[Union[Message, LettaMessage]]): The messages returned\ \ by the agent.\n usage (LettaUsageStatistics): The usage statistics" LettaStopReason: properties: message_type: type: string const: stop_reason title: Message Type description: The type of the message. default: stop_reason stop_reason: $ref: '#/components/schemas/StopReasonType' description: The reason why execution stopped. type: object required: - stop_reason title: LettaStopReason description: The stop reason from Letta indicating why agent loop stopped execution. LettaStreamingRequest: properties: messages: anyOf: - items: anyOf: - $ref: '#/components/schemas/MessageCreate' - $ref: '#/components/schemas/ApprovalCreate' - $ref: '#/components/schemas/ToolReturnCreate' type: array - type: 'null' title: Messages description: The messages to be sent to the agent. input: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' - $ref: '#/components/schemas/SummarizedReasoningContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' summarized_reasoning: '#/components/schemas/SummarizedReasoningContent' text: '#/components/schemas/TextContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolReturnContent' type: array - type: 'null' title: Input description: 'Syntactic sugar for a single user message. Equivalent to messages=[{''role'': ''user'', ''content'': input}].' max_steps: type: integer title: Max Steps description: Maximum number of steps the agent should take to process the request. default: 50 use_assistant_message: type: boolean title: Use Assistant Message description: Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: true deprecated: true assistant_message_tool_name: type: string title: Assistant Message Tool Name description: The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: send_message deprecated: true assistant_message_tool_kwarg: type: string title: Assistant Message Tool Kwarg description: The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: message deprecated: true include_return_message_types: anyOf: - items: $ref: '#/components/schemas/MessageType' type: array - type: 'null' title: Include Return Message Types description: Only return specified message types in the response. If `None` (default) returns all messages. enable_thinking: type: string title: Enable Thinking description: If set to True, enables reasoning before responses or tool calls from the agent. default: true deprecated: true client_tools: anyOf: - items: $ref: '#/components/schemas/ClientToolSchema' type: array - type: 'null' title: Client Tools description: Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. client_skills: anyOf: - items: $ref: '#/components/schemas/ClientSkillSchema' type: array - type: 'null' title: Client Skills description: Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. override_model: anyOf: - type: string - type: 'null' title: Override Model description: Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. include_compaction_messages: type: boolean title: Include Compaction Messages description: If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. default: false return_logprobs: type: boolean title: Return Logprobs description: If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). default: false top_logprobs: anyOf: - type: integer - type: 'null' title: Top Logprobs description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. return_token_ids: type: boolean title: Return Token Ids description: If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. default: false override_system: anyOf: - type: string - type: 'null' title: Override System description: Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. streaming: type: boolean title: Streaming description: If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response. default: false stream_tokens: type: boolean title: Stream Tokens description: Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true). default: false include_pings: type: boolean title: Include Pings description: Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true). default: true background: type: boolean title: Background description: Whether to process the request in the background (only used when streaming=true). default: false type: object title: LettaStreamingRequest LettaStreamingResponse: oneOf: - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ReasoningMessage' - $ref: '#/components/schemas/HiddenReasoningMessage' - $ref: '#/components/schemas/ToolCallMessage' - $ref: '#/components/schemas/ToolReturnMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ApprovalRequestMessage' - $ref: '#/components/schemas/ApprovalResponseMessage' - $ref: '#/components/schemas/LettaPing' - $ref: '#/components/schemas/LettaErrorMessage' - $ref: '#/components/schemas/LettaStopReason' - $ref: '#/components/schemas/LettaUsageStatistics' title: LettaStreamingResponse description: 'Streaming response type for Server-Sent Events (SSE) endpoints. Each event in the stream will be one of these types.' discriminator: propertyName: message_type mapping: approval_request_message: '#/components/schemas/ApprovalRequestMessage' approval_response_message: '#/components/schemas/ApprovalResponseMessage' assistant_message: '#/components/schemas/AssistantMessage' error_message: '#/components/schemas/LettaErrorMessage' hidden_reasoning_message: '#/components/schemas/HiddenReasoningMessage' ping: '#/components/schemas/LettaPing' reasoning_message: '#/components/schemas/ReasoningMessage' stop_reason: '#/components/schemas/LettaStopReason' system_message: '#/components/schemas/SystemMessage' tool_call_message: '#/components/schemas/ToolCallMessage' tool_return_message: '#/components/schemas/ToolReturnMessage' usage_statistics: '#/components/schemas/LettaUsageStatistics' user_message: '#/components/schemas/UserMessage' LettaUsageStatistics: properties: message_type: type: string const: usage_statistics title: Message Type default: usage_statistics completion_tokens: type: integer title: Completion Tokens description: The number of tokens generated by the agent. default: 0 prompt_tokens: type: integer title: Prompt Tokens description: The number of tokens in the prompt. default: 0 total_tokens: type: integer title: Total Tokens description: The total number of tokens processed by the agent. default: 0 step_count: type: integer title: Step Count description: The number of steps taken by the agent. default: 0 run_ids: anyOf: - items: type: string type: array - type: 'null' title: Run Ids description: The background task run IDs associated with the agent interaction cached_input_tokens: anyOf: - type: integer - type: 'null' title: Cached Input Tokens description: The number of input tokens served from cache. None if not reported by provider. cache_write_tokens: anyOf: - type: integer - type: 'null' title: Cache Write Tokens description: The number of input tokens written to cache (Anthropic only). None if not reported by provider. reasoning_tokens: anyOf: - type: integer - type: 'null' title: Reasoning Tokens description: The number of reasoning/thinking tokens generated. None if not reported by provider. context_tokens: anyOf: - type: integer - type: 'null' title: Context Tokens description: Estimate of tokens currently in the context window. type: object title: LettaUsageStatistics description: "Usage statistics for the agent interaction.\n\nAttributes:\n completion_tokens (int): The number of\ \ tokens generated by the agent.\n prompt_tokens (int): The number of tokens in the prompt.\n total_tokens (int):\ \ The total number of tokens processed by the agent.\n step_count (int): The number of steps taken by the agent.\n\ \ cached_input_tokens (Optional[int]): The number of input tokens served from cache. None if not reported.\n \ \ cache_write_tokens (Optional[int]): The number of input tokens written to cache. None if not reported.\n reasoning_tokens\ \ (Optional[int]): The number of reasoning/thinking tokens generated. None if not reported." ListDeploymentEntitiesResponse: properties: entities: items: $ref: '#/components/schemas/DeploymentEntity' type: array title: Entities default: [] total_count: type: integer title: Total Count deployment_id: type: string title: Deployment Id message: type: string title: Message type: object required: - total_count - deployment_id - message title: ListDeploymentEntitiesResponse description: Response model for listing deployment entities. LocalSandboxConfig: properties: sandbox_dir: anyOf: - type: string - type: 'null' title: Sandbox Dir description: Directory for the sandbox environment. use_venv: type: boolean title: Use Venv description: Whether or not to use the venv, or run directly in the same run loop. default: false venv_name: type: string title: Venv Name description: The name for the venv in the sandbox directory. We first search for an existing venv with this name, otherwise, we make it from the requirements.txt. default: venv pip_requirements: items: $ref: '#/components/schemas/PipRequirement' type: array title: Pip Requirements description: List of pip packages to install with mandatory name and optional version following semantic versioning. This only is considered when use_venv is True. type: object title: LocalSandboxConfig MCPServerSchema: properties: id: type: string title: Id description: Human-readable MCP server ID server_type: type: string title: Server Type server_name: type: string title: Server Name server_url: anyOf: - type: string - type: 'null' title: Server Url stdio_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Stdio Config metadata_: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata type: object required: - id - server_type - server_name title: MCPServerSchema description: MCP server schema for agent files with remapped ID. MCPServerType: type: string enum: - sse - stdio - streamable_http title: MCPServerType MCPTool: properties: name: type: string title: Name title: anyOf: - type: string - type: 'null' title: Title description: anyOf: - type: string - type: 'null' title: Description inputSchema: additionalProperties: true type: object title: Inputschema outputSchema: anyOf: - additionalProperties: true type: object - type: 'null' title: Outputschema annotations: anyOf: - $ref: '#/components/schemas/ToolAnnotations' - type: 'null' _meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta health: anyOf: - $ref: '#/components/schemas/MCPToolHealth' - type: 'null' description: Schema health status for OpenAI strict mode additionalProperties: true type: object required: - name - inputSchema title: MCPTool description: A simple wrapper around MCP's tool definition (to avoid conflict with our own) MCPToolHealth: properties: status: type: string title: Status description: 'Schema health status: STRICT_COMPLIANT, NON_STRICT_ONLY, or INVALID' reasons: items: type: string type: array title: Reasons description: List of reasons for the health status type: object required: - status title: MCPToolHealth description: Health status for an MCP tool's schema. ManagerType: type: string enum: - round_robin - supervisor - dynamic - sleeptime - voice_sleeptime - swarm title: ManagerType 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. MaxCountPerStepToolRuleSchema: properties: tool_name: type: string title: Tool Name type: type: string title: Type max_count_limit: type: integer title: Max Count Limit type: object required: - tool_name - type - max_count_limit title: MaxCountPerStepToolRuleSchema Memory: properties: agent_type: anyOf: - $ref: '#/components/schemas/AgentType' - type: string - type: 'null' title: Agent Type description: Agent type controlling prompt rendering. git_enabled: type: boolean title: Git Enabled description: Whether this agent uses git-backed memory with structured labels. default: false blocks: items: $ref: '#/components/schemas/Block' type: array title: Blocks description: Memory blocks contained in the agent's in-context memory file_blocks: items: $ref: '#/components/schemas/FileBlock' type: array title: File Blocks description: Special blocks representing the agent's in-context memory of an attached file prompt_template: type: string title: Prompt Template description: Deprecated. Ignored for performance. default: '' type: object required: - blocks title: Memory description: Represents the in-context memory (i.e. Core memory) of the agent. This includes both the `Block` objects (labelled by sections), as well as tools to edit the blocks. Message: 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: type: string format: date-time 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: ^message-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Message examples: - message-123e4567-e89b-12d3-a456-426614174000 agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent. model: anyOf: - type: string - type: 'null' title: Model description: The model used to make the function call. role: $ref: '#/components/schemas/MessageRole' description: The role of the participant. content: anyOf: - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' - $ref: '#/components/schemas/SummarizedReasoningContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' summarized_reasoning: '#/components/schemas/SummarizedReasoningContent' text: '#/components/schemas/TextContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolReturnContent' type: array - type: 'null' title: Content description: The content of the message. name: anyOf: - type: string - type: 'null' title: Name description: 'For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.' tool_calls: anyOf: - items: $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall-Output' type: array - type: 'null' title: Tool Calls description: The list of tool calls requested. Only applicable for role assistant. tool_call_id: anyOf: - type: string - type: 'null' title: Tool Call Id description: The ID of the tool call. Only applicable for role tool. step_id: anyOf: - type: string - type: 'null' title: Step Id description: The id of the step that this message was created in. run_id: anyOf: - type: string - type: 'null' title: Run Id description: The id of the run that this message was created in. otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id associated with this message tool_returns: anyOf: - items: $ref: '#/components/schemas/letta__schemas__message__ToolReturn-Output' type: array - type: 'null' title: Tool Returns description: Tool execution return information for prior tool calls group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in sender_id: anyOf: - type: string - type: 'null' title: Sender Id description: The id of the sender of the message, can be an identity id or agent id batch_item_id: anyOf: - type: string - type: 'null' title: Batch Item Id description: The id of the LLMBatchItem that this message is associated with conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The conversation this message belongs to is_err: anyOf: - type: boolean - type: 'null' title: Is Err description: Whether this message is part of an error step. Used only for debugging purposes. approval_request_id: anyOf: - type: string - type: 'null' title: Approval Request Id description: The id of the approval request if this message is associated with a tool call request. approve: anyOf: - type: boolean - type: 'null' title: Approve description: Whether tool call is approved. denial_reason: anyOf: - type: string - type: 'null' title: Denial Reason description: The reason the tool call request was denied. approvals: anyOf: - items: anyOf: - $ref: '#/components/schemas/ApprovalReturn' - $ref: '#/components/schemas/letta__schemas__message__ToolReturn-Output' type: array - type: 'null' title: Approvals description: The list of approvals for this message. additionalProperties: false type: object required: - role title: Message description: " Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats.\n\ \n Attributes:\n id (str): The unique identifier of the message.\n role (MessageRole): The role of\ \ the participant.\n text (str): The text of the message.\n user_id (str): The unique identifier of\ \ the user.\n agent_id (str): The unique identifier of the agent.\n model (str): The model used to make\ \ the function call.\n name (str): The name of the participant.\n created_at (datetime): The time the\ \ message was created.\n tool_calls (List[OpenAIToolCall,]): The list of tool calls requested.\n tool_call_id\ \ (str): The id of the tool call.\n step_id (str): The id of the step that this message was created in.\n \ \ otid (str): The offline threading id associated with this message.\n tool_returns (List[ToolReturn]):\ \ The list of tool returns requested.\n group_id (str): The multi-agent group that the message was sent in.\n\ \ sender_id (str): The id of the sender of the message, can be an identity id or agent id.\n conversation_id\ \ (str): The conversation this message belongs to.\nt" MessageCreate: properties: type: anyOf: - type: string const: message - type: 'null' title: Type description: The message type to be created. default: message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in role: type: string enum: - user - system - assistant title: Role description: The role of the participant. content: anyOf: - items: $ref: '#/components/schemas/LettaMessageContentUnion' type: array - type: string title: Content description: The content of the message. name: anyOf: - type: string - type: 'null' title: Name description: The name of the participant. sender_id: anyOf: - type: string - type: 'null' title: Sender Id description: The id of the sender of the message, can be an identity id or agent id batch_item_id: anyOf: - type: string - type: 'null' title: Batch Item Id description: The id of the LLMBatchItem that this message is associated with type: object required: - role - content title: MessageCreate description: Request to create a message MessageRole: type: string enum: - assistant - user - tool - function - system - approval - summary title: MessageRole MessageSearchCacheWarmScope: properties: {} additionalProperties: false type: object title: MessageSearchCacheWarmScope description: Messages currently infer scope from the authenticated actor. MessageSearchRequest: properties: query: anyOf: - type: string - type: 'null' title: Query description: Text query for full-text search search_mode: type: string enum: - vector - fts - hybrid title: Search Mode description: Search mode to use default: hybrid roles: anyOf: - items: $ref: '#/components/schemas/MessageRole' type: array - type: 'null' title: Roles description: Filter messages by role agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: Filter messages by agent ID project_id: anyOf: - type: string - type: 'null' title: Project Id description: Filter messages by project ID template_id: anyOf: - type: string - type: 'null' title: Template Id description: Filter messages by template ID conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: Filter messages by conversation ID limit: type: integer maximum: 100 minimum: 1 title: Limit description: Maximum number of results to return default: 50 start_date: anyOf: - type: string format: date-time - type: 'null' title: Start Date description: Filter messages created after this date end_date: anyOf: - type: string format: date-time - type: 'null' title: End Date description: Filter messages created on or before this date type: object title: MessageSearchRequest description: Request model for searching messages across the organization MessageSearchResult: properties: embedded_text: type: string title: Embedded Text description: The embedded content (LLM-friendly) message: $ref: '#/components/schemas/Message' description: The raw message object fts_rank: anyOf: - type: integer - type: 'null' title: Fts Rank description: Full-text search rank position if FTS was used vector_rank: anyOf: - type: integer - type: 'null' title: Vector Rank description: Vector search rank position if vector search was used rrf_score: type: number title: Rrf Score description: Reciprocal Rank Fusion combined score type: object required: - embedded_text - message - rrf_score title: MessageSearchResult description: Result from a message search operation with scoring details. MessageType: type: string enum: - system_message - user_message - assistant_message - reasoning_message - hidden_reasoning_message - tool_call_message - tool_return_message - approval_request_message - approval_response_message - summary_message - event_message title: MessageType ModalSandboxConfig: properties: timeout: type: integer title: Timeout description: Time limit for the sandbox (in seconds). default: 60 pip_requirements: anyOf: - items: type: string type: array - type: 'null' title: Pip Requirements description: A list of pip packages to install in the Modal sandbox npm_requirements: anyOf: - items: type: string type: array - type: 'null' title: Npm Requirements description: A list of npm packages to install in the Modal sandbox language: type: string enum: - python - typescript title: Language default: python type: object title: ModalSandboxConfig Model: properties: handle: anyOf: - type: string - type: 'null' title: Handle description: The handle for this config, in the format provider/model-name. name: type: string title: Name description: The actual model name used by the provider display_name: anyOf: - type: string - type: 'null' title: Display Name description: A human-friendly display name for the model. provider_type: $ref: '#/components/schemas/ProviderType' description: The type of the provider provider_name: anyOf: - type: string - type: 'null' title: Provider Name description: The provider name for the model. model_type: type: string const: llm title: Model Type description: Type of model (llm or embedding) default: llm model: type: string title: Model description: 'Deprecated: Use ''name'' field instead. LLM model name.' deprecated: true model_endpoint_type: type: string enum: - openai - anthropic - google_ai - google_vertex - azure - groq - ollama - webui - webui-legacy - lmstudio - lmstudio-legacy - lmstudio-chatcompletions - llamacpp - koboldcpp - vllm - hugging-face - baseten - minimax - mistral - together - bedrock - deepseek - xai - zai - zai_coding - openrouter - chatgpt_oauth title: Model Endpoint Type description: 'Deprecated: Use ''provider_type'' field instead. The endpoint type for the model.' deprecated: true model_endpoint: anyOf: - type: string - type: 'null' title: Model Endpoint description: 'Deprecated: The endpoint for the model.' deprecated: true provider_category: anyOf: - $ref: '#/components/schemas/ProviderCategory' - type: 'null' description: 'Deprecated: The provider category for the model.' deprecated: true model_wrapper: anyOf: - type: string - type: 'null' title: Model Wrapper description: 'Deprecated: The wrapper for the model.' deprecated: true context_window: type: integer title: Context Window description: 'Deprecated: Use ''max_context_window'' field instead. The context window size for the model.' deprecated: true put_inner_thoughts_in_kwargs: anyOf: - type: boolean - type: 'null' title: Put Inner Thoughts In Kwargs description: 'Deprecated: Puts ''inner_thoughts'' as a kwarg in the function call.' default: true deprecated: true temperature: type: number title: Temperature description: 'Deprecated: The temperature to use when generating text with the model.' default: 0.7 deprecated: true max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens description: 'Deprecated: The maximum number of tokens to generate.' deprecated: true enable_reasoner: type: boolean title: Enable Reasoner description: 'Deprecated: Whether or not the model should use extended thinking if it is a ''reasoning'' style model.' default: true deprecated: true reasoning_effort: anyOf: - type: string enum: - none - minimal - low - medium - high - xhigh - type: 'null' title: Reasoning Effort description: 'Deprecated: The reasoning effort to use when generating text reasoning models.' deprecated: true max_reasoning_tokens: type: integer title: Max Reasoning Tokens description: 'Deprecated: Configurable thinking budget for extended thinking.' default: 0 deprecated: true effort: anyOf: - type: string enum: - low - medium - high - max - type: 'null' title: Effort description: The effort level for Anthropic models that support it (Opus 4.5, Opus 4.6). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. frequency_penalty: anyOf: - type: number - type: 'null' title: Frequency Penalty description: 'Deprecated: Positive values penalize new tokens based on their existing frequency in the text so far.' deprecated: true compatibility_type: anyOf: - type: string enum: - gguf - mlx - type: 'null' title: Compatibility Type description: 'Deprecated: The framework compatibility type for the model.' deprecated: true verbosity: anyOf: - type: string enum: - low - medium - high - type: 'null' title: Verbosity description: 'Deprecated: Soft control for how verbose model output should be.' deprecated: true tier: anyOf: - type: string - type: 'null' title: Tier description: 'Deprecated: The cost tier for the model (cloud only).' deprecated: true parallel_tool_calls: anyOf: - type: boolean - type: 'null' title: Parallel Tool Calls description: 'Deprecated: If set to True, enables parallel tool calling.' default: false deprecated: true response_format: 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 Format description: The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. strict: type: boolean title: Strict description: 'Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.' default: false return_logprobs: type: boolean title: Return Logprobs description: Whether to return log probabilities of the output tokens. Useful for RL training. default: false top_logprobs: anyOf: - type: integer - type: 'null' title: Top Logprobs description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. return_token_ids: type: boolean title: Return Token Ids description: Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. default: false tool_call_parser: anyOf: - type: string - type: 'null' title: Tool Call Parser description: SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. max_context_window: type: integer title: Max Context Window description: The maximum context window for the model type: object required: - name - provider_type - model - model_endpoint_type - context_window - max_context_window title: Model ModifyApprovalRequest: properties: requires_approval: type: boolean title: Requires Approval description: Whether the tool requires approval before execution additionalProperties: false type: object required: - requires_approval title: ModifyApprovalRequest description: Request body for modifying tool approval requirements. ModifyFeedbackRequest: properties: feedback: anyOf: - $ref: '#/components/schemas/FeedbackType' - type: 'null' description: Whether this feedback is positive or negative tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: Feedback tags to add to the step type: object title: ModifyFeedbackRequest 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 OmittedReasoningContent: properties: type: type: string const: omitted_reasoning title: Type description: Indicates this is an omitted reasoning step. default: omitted_reasoning signature: anyOf: - type: string - type: 'null' title: Signature description: A unique identifier for this reasoning step. type: object title: OmittedReasoningContent description: A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) OpenAIModelSettings: 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: openai title: Provider Type description: The type of the provider. default: openai temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 reasoning: $ref: '#/components/schemas/OpenAIReasoning' description: The reasoning configuration for the model. default: reasoning_effort: high response_format: 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 Format description: The response format for the model. strict: type: boolean title: Strict description: Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. default: true type: object title: OpenAIModelSettings OpenAIReasoning: properties: reasoning_effort: type: string enum: - none - minimal - low - medium - high - xhigh title: Reasoning Effort description: The reasoning effort to use when generating text reasoning models default: minimal type: object title: OpenAIReasoning OpenRouterModelSettings: 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: openrouter title: Provider Type description: The type of the provider. default: openrouter temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 response_format: 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 Format description: The response format for the model. type: object title: OpenRouterModelSettings description: OpenRouter model configuration (OpenAI-compatible). Organization: properties: id: type: string pattern: ^org-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Org examples: - org-123e4567-e89b-12d3-a456-426614174000 name: type: string title: Name description: The name of the organization. default: SincereYogurt created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: The creation date of the organization. privileged_tools: type: boolean title: Privileged Tools description: Whether the organization has access to privileged tools. default: false additionalProperties: false type: object title: Organization OrganizationCreate: properties: name: anyOf: - type: string - type: 'null' title: Name description: The name of the organization. privileged_tools: anyOf: - type: boolean - type: 'null' title: Privileged Tools description: Whether the organization has access to privileged tools. default: false additionalProperties: false type: object title: OrganizationCreate OrganizationSourcesStats: properties: total_sources: type: integer title: Total Sources description: Total number of sources default: 0 total_files: type: integer title: Total Files description: Total number of files across all sources default: 0 total_size: type: integer title: Total Size description: Total size of all files in bytes default: 0 sources: items: $ref: '#/components/schemas/SourceStats' type: array title: Sources description: List of source metadata additionalProperties: false type: object title: OrganizationSourcesStats description: Complete metadata response for organization sources OrganizationUpdate: properties: name: anyOf: - type: string - type: 'null' title: Name description: The name of the organization. privileged_tools: anyOf: - type: boolean - type: 'null' title: Privileged Tools description: Whether the organization has access to privileged tools. default: false additionalProperties: false type: object title: OrganizationUpdate PaginatedAgentFiles: properties: files: items: $ref: '#/components/schemas/AgentFileAttachment' type: array title: Files description: List of file attachments for the agent next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Cursor for fetching the next page (file-agent relationship ID) has_more: type: boolean title: Has More description: Whether more results exist after this page additionalProperties: false type: object required: - files - has_more title: PaginatedAgentFiles description: Paginated response for agent files ParameterProperties: properties: type: type: string title: Type description: anyOf: - type: string - type: 'null' title: Description type: object required: - type title: ParameterProperties ParametersSchema: properties: type: anyOf: - type: string - type: 'null' title: Type default: object properties: additionalProperties: $ref: '#/components/schemas/ParameterProperties' type: object title: Properties required: items: type: string type: array title: Required type: object required: - properties title: ParametersSchema ParentToolRule: 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: parent_last_tool title: Type default: parent_last_tool prompt_template: anyOf: - type: string - type: 'null' title: Prompt Template description: Optional template string (ignored). children: items: type: string type: array title: Children description: The children tools that can be invoked. additionalProperties: false type: object required: - tool_name - children title: ParentToolRule description: A ToolRule that only allows a child tool to be called if the parent has been called. Passage: 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 creation date of the passage. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The timestamp when the object was last updated. is_deleted: type: boolean title: Is Deleted description: Whether this passage is deleted or not. default: false archive_id: anyOf: - type: string - type: 'null' title: Archive Id description: The unique identifier of the archive containing this passage. source_id: anyOf: - type: string - type: 'null' title: Source Id description: 'Deprecated: Use `folder_id` field instead. The data source of the passage.' deprecated: true file_id: anyOf: - type: string - type: 'null' title: File Id description: The unique identifier of the file associated with the passage. file_name: anyOf: - type: string - type: 'null' title: File Name description: The name of the file (only for source passages). metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: The metadata of the passage. default: {} tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: Tags associated with this passage. id: type: string pattern: ^passage-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Passage examples: - passage-123e4567-e89b-12d3-a456-426614174000 text: type: string title: Text description: The text of the passage. embedding: anyOf: - items: type: number type: array - type: 'null' title: Embedding description: The embedding of the passage. embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: The embedding configuration used by the passage. additionalProperties: false type: object required: - text - embedding - embedding_config title: Passage description: Representation of a passage, which is stored in archival memory. PassageBatchCreateRequest: properties: passages: items: $ref: '#/components/schemas/PassageCreateRequest' type: array title: Passages description: Passages to create in the archive type: object required: - passages title: PassageBatchCreateRequest description: Request model for creating multiple passages in an archive. PassageCreateRequest: properties: text: type: string title: Text description: The text content of the passage metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Optional metadata for the passage tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: Optional tags for categorizing the passage created_at: anyOf: - type: string - type: 'null' title: Created At description: Optional creation datetime for the passage (ISO 8601 format) type: object required: - text title: PassageCreateRequest description: Request model for creating a passage in an archive. PassageSearchRequest: properties: query: anyOf: - type: string - type: 'null' title: Query description: Text query for semantic search agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: Filter passages by agent ID archive_id: anyOf: - type: string - type: 'null' title: Archive Id description: Filter passages by archive ID tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: Optional list of tags to filter search results tag_match_mode: type: string enum: - any - all title: Tag Match Mode description: How to match tags - 'any' to match passages with any of the tags, 'all' to match only passages with all tags default: any limit: type: integer maximum: 100 minimum: 1 title: Limit description: Maximum number of results to return default: 50 start_date: anyOf: - type: string format: date-time - type: 'null' title: Start Date description: Filter results to passages created after this datetime end_date: anyOf: - type: string format: date-time - type: 'null' title: End Date description: Filter results to passages created before this datetime type: object title: PassageSearchRequest description: Request model for searching passages across archives. PassageSearchResult: properties: passage: $ref: '#/components/schemas/Passage' description: The passage object score: type: number title: Score description: Relevance score metadata: additionalProperties: true type: object title: Metadata description: Additional metadata about the search result type: object required: - passage - score title: PassageSearchResult description: Result from a passage search operation with scoring details. PipRequirement: properties: name: type: string minLength: 1 title: Name description: Name of the pip package. version: anyOf: - type: string - type: 'null' title: Version description: Optional version of the package, following semantic versioning. type: object required: - name title: PipRequirement PromptTokensDetails: properties: audio_tokens: anyOf: - type: integer - type: 'null' title: Audio Tokens cached_tokens: anyOf: - type: integer - type: 'null' title: Cached Tokens additionalProperties: true type: object title: PromptTokensDetails description: Breakdown of tokens used in the prompt. Provider: properties: id: anyOf: - type: string - type: 'null' title: Id description: The id of the provider, lazily created by the database manager. name: type: string title: Name description: The name of the provider provider_type: $ref: '#/components/schemas/ProviderType' description: The type of the provider provider_category: $ref: '#/components/schemas/ProviderCategory' description: The category of the provider (base or byok) api_key: anyOf: - type: string - type: 'null' title: Api Key description: API key or secret key used for requests to the provider. deprecated: true base_url: anyOf: - type: string - type: 'null' title: Base Url description: Base URL for the provider. access_key: anyOf: - type: string - type: 'null' title: Access Key description: Access key used for requests to the provider. deprecated: true region: anyOf: - type: string - type: 'null' title: Region description: Region used for requests to the provider. api_version: anyOf: - type: string - type: 'null' title: Api Version description: API version used for requests to the provider. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The last update timestamp of the provider. last_synced: anyOf: - type: string format: date-time - type: 'null' title: Last Synced description: The last time models were synced for this provider. api_key_enc: anyOf: - type: string description: Encrypted secret value (stored as encrypted string) nullable: true - type: 'null' title: Api Key Enc description: Encrypted API key as Secret object access_key_enc: anyOf: - type: string description: Encrypted secret value (stored as encrypted string) nullable: true - type: 'null' title: Access Key Enc description: Encrypted access key as Secret object additionalProperties: false type: object required: - name - provider_type - provider_category title: Provider ProviderCategory: type: string enum: - base - byok title: ProviderCategory ProviderCheck: properties: provider_type: $ref: '#/components/schemas/ProviderType' description: The type of the provider. api_key: type: string title: Api Key description: API key or secret key used for requests to the provider. access_key: anyOf: - type: string - type: 'null' title: Access Key description: Access key used for requests to the provider. region: anyOf: - type: string - type: 'null' title: Region description: Region used for requests to the provider. base_url: anyOf: - type: string - type: 'null' title: Base Url description: Base URL used for requests to the provider. api_version: anyOf: - type: string - type: 'null' title: Api Version description: API version used for requests to the provider. type: object required: - provider_type - api_key title: ProviderCheck ProviderCreate: properties: name: type: string title: Name description: The name of the provider. provider_type: $ref: '#/components/schemas/ProviderType' description: The type of the provider. api_key: type: string title: Api Key description: API key or secret key used for requests to the provider. access_key: anyOf: - type: string - type: 'null' title: Access Key description: Access key used for requests to the provider. region: anyOf: - type: string - type: 'null' title: Region description: Region used for requests to the provider. base_url: anyOf: - type: string - type: 'null' title: Base Url description: Base URL used for requests to the provider. api_version: anyOf: - type: string - type: 'null' title: Api Version description: API version used for requests to the provider. additionalProperties: false type: object required: - name - provider_type - api_key title: ProviderCreate ProviderTrace: 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: type: string format: date-time 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: ^provider_trace-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Provider_trace examples: - provider_trace-123e4567-e89b-12d3-a456-426614174000 request_json: additionalProperties: true type: object title: Request Json description: JSON content of the provider request response_json: additionalProperties: true type: object title: Response Json description: JSON content of the provider response step_id: anyOf: - type: string - type: 'null' title: Step Id description: ID of the step that this trace is associated with agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: ID of the agent that generated this trace agent_tags: anyOf: - items: type: string type: array - type: 'null' title: Agent Tags description: Tags associated with the agent for filtering call_type: anyOf: - type: string - type: 'null' title: Call Type description: Type of call (agent_step, summarization, etc.) run_id: anyOf: - type: string - type: 'null' title: Run Id description: ID of the run this trace is associated with source: anyOf: - type: string - type: 'null' title: Source description: Source service that generated this trace (memgpt-server, lettuce-py) org_id: anyOf: - type: string - type: 'null' title: Org Id description: ID of the organization compaction_settings: anyOf: - additionalProperties: true type: object - type: 'null' title: Compaction Settings description: Compaction/summarization settings (summarization calls only) llm_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Llm Config description: LLM configuration used for this call (non-summarization calls only) billing_context: anyOf: - $ref: '#/components/schemas/BillingContext' - type: 'null' description: Billing context from request headers additionalProperties: false type: object required: - request_json - response_json title: ProviderTrace description: "Letta's internal representation of a provider trace.\n\nAttributes:\n id (str): The unique identifier\ \ of the provider trace.\n request_json (Dict[str, Any]): JSON content of the provider request.\n response_json\ \ (Dict[str, Any]): JSON content of the provider response.\n step_id (str): ID of the step that this trace is associated\ \ with.\n agent_id (str): ID of the agent that generated this trace.\n agent_tags (list[str]): Tags associated\ \ with the agent for filtering.\n call_type (str): Type of call (agent_step, summarization, etc.).\n run_id\ \ (str): ID of the run this trace is associated with.\n source (str): Source service that generated this trace\ \ (memgpt-server, lettuce-py).\n organization_id (str): The unique identifier of the organization.\n user_id\ \ (str): The unique identifier of the user who initiated the request.\n compaction_settings (Dict[str, Any]): Compaction/summarization\ \ settings (only for summarization calls).\n llm_config (Dict[str, Any]): LLM configuration used for this call\ \ (only for non-summarization calls).\n created_at (datetime): The timestamp when the object was created." ProviderType: type: string enum: - anthropic - azure - baseten - bedrock - cerebras - chatgpt_oauth - deepseek - fireworks - google_ai - google_vertex - groq - hugging-face - letta - lmstudio_openai - minimax - mistral - ollama - openai - together - vllm - sglang - openrouter - xai - zai - zai_coding title: ProviderType ProviderUpdate: properties: api_key: type: string title: Api Key description: API key or secret key used for requests to the provider. access_key: anyOf: - type: string - type: 'null' title: Access Key description: Access key used for requests to the provider. region: anyOf: - type: string - type: 'null' title: Region description: Region used for requests to the provider. base_url: anyOf: - type: string - type: 'null' title: Base Url description: Base URL used for requests to the provider. api_version: anyOf: - type: string - type: 'null' title: Api Version description: API version used for requests to the provider. additionalProperties: false type: object required: - api_key title: ProviderUpdate ReasoningContent: properties: type: type: string const: reasoning title: Type description: Indicates this is a reasoning/intermediate step. default: reasoning is_native: type: boolean title: Is Native description: Whether the reasoning content was generated by a reasoner model that processed this step. reasoning: type: string title: Reasoning description: The intermediate reasoning or thought process content. signature: anyOf: - type: string - type: 'null' title: Signature description: A unique identifier for this reasoning step. type: object required: - is_native - reasoning title: ReasoningContent description: Sent via the Anthropic Messages API ReasoningMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: reasoning_message title: Message Type description: The type of the message. default: reasoning_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id source: type: string enum: - reasoner_model - non_reasoner_model title: Source default: non_reasoner_model reasoning: type: string title: Reasoning signature: anyOf: - type: string - type: 'null' title: Signature type: object required: - id - date - reasoning title: ReasoningMessage description: "Representation of an agent's internal reasoning.\n\nArgs:\n id (str): The ID of the message\n date\ \ (datetime): The date the message was created in ISO format\n name (Optional[str]): The name of the sender of\ \ the message\n source (Literal[\"reasoner_model\", \"non_reasoner_model\"]): Whether the reasoning\n content\ \ was generated natively by a reasoner model or derived via prompting\n reasoning (str): The internal reasoning\ \ of the agent\n signature (Optional[str]): The model-generated signature of the reasoning step" ReasoningMessageListResult: properties: reasoning: type: string title: Reasoning message_type: type: string const: reasoning_message title: Message Type default: reasoning_message message_id: type: string title: Message Id description: The unique identifier of the message. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent that owns the message. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation that the message belongs to. created_at: type: string format: date-time title: Created At description: The time the message was created in ISO format. type: object required: - reasoning - message_id - created_at title: ReasoningMessageListResult description: 'Reasoning message list result with agent context. Shape is identical to UpdateReasoningMessage but includes the owning agent_id and message id.' RedactedReasoningContent: properties: type: type: string const: redacted_reasoning title: Type description: Indicates this is a redacted thinking step. default: redacted_reasoning data: type: string title: Data description: The redacted or filtered intermediate reasoning content. type: object required: - data title: RedactedReasoningContent description: Sent via the Anthropic Messages API RequiredBeforeExitToolRule: 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: required_before_exit title: Type default: required_before_exit prompt_template: anyOf: - type: string - type: 'null' title: Prompt Template description: Optional template string (ignored). additionalProperties: false type: object required: - tool_name title: RequiredBeforeExitToolRule description: Represents a tool rule configuration where this tool must be called before the agent loop can exit. 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 title: Type default: requires_approval prompt_template: anyOf: - type: string - type: 'null' title: Prompt Template description: Optional template string (ignored). Rendering uses fast built-in formatting for performance. additionalProperties: false type: object required: - tool_name title: RequiresApprovalToolRule description: Represents a tool rule configuration which requires approval before the tool can be invoked. ResetMessagesRequest: properties: add_default_initial_messages: type: boolean title: Add Default Initial Messages description: If true, adds the default initial messages after resetting. default: false type: object title: ResetMessagesRequest description: Request body for resetting messages on an agent. RetrieveStreamRequest: properties: agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: Agent ID for agent-direct mode with 'default' conversation. Use with conversation_id='default' in the URL path. run_id: anyOf: - type: string - type: 'null' title: Run Id description: Run ID to stream directly, bypassing run lookup. Use for recovery from duplicate requests. otid: anyOf: - type: string - type: 'null' title: Otid description: Offline threading ID to look up the run_id. Bypasses active run lookup if run_id not provided. starting_after: type: integer title: Starting After description: Sequence id to use as a cursor for pagination. Response will start streaming after this chunk sequence id default: 0 include_pings: anyOf: - type: boolean - type: 'null' title: Include Pings description: Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts. default: true poll_interval: anyOf: - type: number - type: 'null' title: Poll Interval description: Seconds to wait between polls when no new data. default: 0.1 batch_size: anyOf: - type: integer - type: 'null' title: Batch Size description: Number of entries to read per batch. default: 100 type: object title: RetrieveStreamRequest RoundRobinManager: properties: manager_type: type: string const: round_robin title: Manager Type description: '' default: round_robin max_turns: anyOf: - type: integer - type: 'null' title: Max Turns description: '' type: object title: RoundRobinManager RoundRobinManagerUpdate: properties: manager_type: type: string const: round_robin title: Manager Type description: '' default: round_robin max_turns: anyOf: - type: integer - type: 'null' title: Max Turns description: '' type: object title: RoundRobinManagerUpdate Run: properties: id: type: string pattern: ^(job|run)-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Run examples: - run-123e4567-e89b-12d3-a456-426614174000 status: $ref: '#/components/schemas/RunStatus' description: The current status of the run. default: created created_at: type: string format: date-time title: Created At description: The timestamp when the run was created. completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: The timestamp when the run was completed. agent_id: type: string title: Agent Id description: The unique identifier of the agent associated with the run. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation associated with the run. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template ID that the run belongs to. background: anyOf: - type: boolean - type: 'null' title: Background description: Whether the run was created in background mode. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Additional metadata for the run. request_config: anyOf: - $ref: '#/components/schemas/LettaRequestConfig' - type: 'null' description: The request configuration for the run. stop_reason: anyOf: - $ref: '#/components/schemas/StopReasonType' - type: 'null' description: The reason why the run was stopped. callback_url: anyOf: - type: string - type: 'null' title: Callback Url description: If set, POST to this URL when the run completes. callback_sent_at: anyOf: - type: string format: date-time - type: 'null' title: Callback Sent At description: Timestamp when the callback was last attempted. callback_status_code: anyOf: - type: integer - type: 'null' title: Callback Status Code description: HTTP status code returned by the callback endpoint. callback_error: anyOf: - type: string - type: 'null' title: Callback Error description: Optional error message from attempting to POST the callback endpoint. ttft_ns: anyOf: - type: integer - type: 'null' title: Ttft Ns description: Time to first token for a run in nanoseconds total_duration_ns: anyOf: - type: integer - type: 'null' title: Total Duration Ns description: Total run duration in nanoseconds additionalProperties: false type: object required: - agent_id title: Run description: Representation of a run - a conversation or processing session for an agent. Runs track when agents process messages and maintain the relationship between agents, steps, and messages. RunMetrics: properties: id: type: string title: Id description: The id of the run this metric belongs to (matches runs.id). agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent. project_id: anyOf: - type: string - type: 'null' title: Project Id description: The project that the run belongs to (cloud only). run_start_ns: anyOf: - type: integer - type: 'null' title: Run Start Ns description: The timestamp of the start of the run in nanoseconds. run_ns: anyOf: - type: integer - type: 'null' title: Run Ns description: Total time for the run in nanoseconds. num_steps: anyOf: - type: integer - type: 'null' title: Num Steps description: The number of steps in the run. tools_used: anyOf: - items: type: string type: array - type: 'null' title: Tools Used description: List of tool IDs that were used in this run. template_id: anyOf: - type: string - type: 'null' title: Template Id description: The template ID that the run belongs to (cloud only). base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template ID that the run belongs to (cloud only). additionalProperties: false type: object required: - id title: RunMetrics RunStatus: type: string enum: - created - running - completed - failed - cancelled title: RunStatus description: Status of the run. SGLangModelSettings: 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: sglang title: Provider Type description: The type of the provider. default: sglang temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 reasoning: $ref: '#/components/schemas/OpenAIReasoning' description: The reasoning configuration for the model. default: reasoning_effort: high response_format: 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 Format description: The response format for the model. strict: type: boolean title: Strict description: Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. default: true tool_call_parser: anyOf: - type: string - type: 'null' title: Tool Call Parser description: SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). type: object title: SGLangModelSettings description: SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). SSEMCPServer: properties: mcp_server_type: type: string const: sse title: Mcp Server Type default: sse server_url: type: string title: Server Url description: The URL of the server auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom HTTP headers to include with requests id: type: string pattern: ^mcp_server-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Mcp_server examples: - mcp_server-123e4567-e89b-12d3-a456-426614174000 server_name: type: string title: Server Name description: The name of the MCP server additionalProperties: false type: object required: - server_url - server_name title: SSEMCPServer description: An SSE MCP server SSEServerConfig: properties: server_name: type: string title: Server Name description: The name of the server type: $ref: '#/components/schemas/MCPServerType' default: sse server_url: type: string title: Server Url description: The URL of the server auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom HTTP headers to include with requests type: object required: - server_name - server_url title: SSEServerConfig description: Configuration for an MCP server using SSE SandboxConfig: 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: ^sandbox-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Sandbox examples: - sandbox-123e4567-e89b-12d3-a456-426614174000 type: $ref: '#/components/schemas/SandboxType' description: The type of sandbox. config: additionalProperties: true type: object title: Config description: The JSON sandbox settings data. additionalProperties: false type: object title: SandboxConfig SandboxConfigCreate: properties: config: anyOf: - $ref: '#/components/schemas/LocalSandboxConfig' - $ref: '#/components/schemas/E2BSandboxConfig' - $ref: '#/components/schemas/ModalSandboxConfig' title: Config description: The configuration for the sandbox. additionalProperties: false type: object required: - config title: SandboxConfigCreate SandboxConfigUpdate: properties: config: anyOf: - $ref: '#/components/schemas/LocalSandboxConfig' - $ref: '#/components/schemas/E2BSandboxConfig' - $ref: '#/components/schemas/ModalSandboxConfig' title: Config description: The JSON configuration data for the sandbox. additionalProperties: false type: object title: SandboxConfigUpdate description: Pydantic model for updating SandboxConfig fields. SandboxEnvironmentVariable: 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: ^sandbox-env-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Sandbox-env examples: - sandbox-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 sandbox_config_id: type: string title: Sandbox Config Id description: The ID of the sandbox config this environment variable belongs to. additionalProperties: false type: object required: - key - value - sandbox_config_id title: SandboxEnvironmentVariable SandboxEnvironmentVariableCreate: properties: 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. additionalProperties: false type: object required: - key - value title: SandboxEnvironmentVariableCreate SandboxEnvironmentVariableUpdate: properties: key: anyOf: - type: string - type: 'null' title: Key description: The name of the environment variable. value: anyOf: - type: string - type: 'null' 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. additionalProperties: false type: object title: SandboxEnvironmentVariableUpdate SandboxType: type: string enum: - e2b - modal - local title: SandboxType SearchAllMessagesRequest: properties: query: type: string title: Query description: Text query for full-text search search_mode: type: string enum: - vector - fts - hybrid title: Search Mode description: Search mode to use default: hybrid agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: Filter messages by agent ID conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: Filter messages by conversation ID limit: type: integer maximum: 100 minimum: 1 title: Limit description: Maximum number of results to return default: 50 start_date: anyOf: - type: string format: date-time - type: 'null' title: Start Date description: Filter messages created after this date end_date: anyOf: - type: string format: date-time - type: 'null' title: End Date description: Filter messages created on or before this date type: object required: - query title: SearchAllMessagesRequest SearchCacheWarmRequest: properties: collection: type: string const: messages title: Collection description: Embedded collection whose cache should be warmed. scope: $ref: '#/components/schemas/MessageSearchCacheWarmScope' description: Collection-specific scope. Messages currently infer organization from the authenticated actor. additionalProperties: false type: object required: - collection - scope title: SearchCacheWarmRequest description: Request for warming an internal search cache. SearchCacheWarmResponse: properties: collection: type: string const: messages title: Collection status: type: string title: Status warmed: type: boolean title: Warmed type: object required: - collection - status - warmed title: SearchCacheWarmResponse description: Response for internal search cache warming. SkillSchema: properties: name: type: string title: Name description: Skill name, also serves as unique identifier (e.g., 'slack', 'pdf') files: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Files description: Skill files as path -> content mapping. Must include 'SKILL.md' key if provided. source_url: anyOf: - type: string - type: 'null' title: Source Url description: Source URL for skill resolution (e.g., 'letta:slack', 'anthropic:pdf', 'owner/repo/path') type: object required: - name title: SkillSchema description: 'Skill schema for agent files. Skills are folders of instructions, scripts, and resources that agents can load. Either files (with SKILL.md) or source_url must be provided: - files with SKILL.md: inline skill content - source_url: reference to resolve later (e.g., ''letta:slack'') - both: inline content with provenance tracking' SleeptimeManager: properties: manager_type: type: string const: sleeptime title: Manager Type description: '' default: sleeptime manager_agent_id: type: string maxLength: 42 minLength: 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}$ title: Manager Agent Id description: '' examples: - agent-123e4567-e89b-42d3-8456-426614174000 sleeptime_agent_frequency: anyOf: - type: integer - type: 'null' title: Sleeptime Agent Frequency description: '' type: object required: - manager_agent_id title: SleeptimeManager SleeptimeManagerSchema: properties: manager_type: type: string const: sleeptime title: Manager Type description: '' default: sleeptime manager_agent_id: type: string title: Manager Agent Id description: '' sleeptime_agent_frequency: anyOf: - type: integer - type: 'null' title: Sleeptime Agent Frequency description: '' type: object required: - manager_agent_id title: SleeptimeManagerSchema SleeptimeManagerUpdate: properties: manager_type: type: string const: sleeptime title: Manager Type description: '' default: sleeptime manager_agent_id: anyOf: - type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 - type: 'null' title: Manager Agent Id description: '' sleeptime_agent_frequency: anyOf: - type: integer - type: 'null' title: Sleeptime Agent Frequency description: '' type: object title: SleeptimeManagerUpdate Source: properties: name: type: string title: Name description: The name of the source. description: anyOf: - type: string - type: 'null' title: Description description: The description of the source. instructions: anyOf: - type: string - type: 'null' title: Instructions description: Instructions for how to use the source. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Metadata associated with the source. id: type: string pattern: ^source-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Source examples: - source-123e4567-e89b-12d3-a456-426614174000 embedding_config: $ref: '#/components/schemas/EmbeddingConfig' description: The embedding configuration used by the source. vector_db_provider: $ref: '#/components/schemas/VectorDBProvider' description: The vector database provider used for this source's passages default: native 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. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: The timestamp when the source was created. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The timestamp when the source was last updated. additionalProperties: false type: object required: - name - embedding_config title: Source description: '(Deprecated: Use Folder) Representation of a source, which is a collection of files and passages.' SourceCreate: properties: name: type: string title: Name description: The name of the source. description: anyOf: - type: string - type: 'null' title: Description description: The description of the source. instructions: anyOf: - type: string - type: 'null' title: Instructions description: Instructions for how to use the source. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Metadata associated with the source. embedding: anyOf: - type: string - type: 'null' title: Embedding description: The handle for the embedding config used by the source. embedding_chunk_size: anyOf: - type: integer - type: 'null' title: Embedding Chunk Size description: The chunk size of the embedding. embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: (Legacy) The embedding configuration used by the source. additionalProperties: false type: object required: - name title: SourceCreate description: Schema for creating a new Source. SourceSchema: properties: name: type: string title: Name description: The name of the source. description: anyOf: - type: string - type: 'null' title: Description description: The description of the source. instructions: anyOf: - type: string - type: 'null' title: Instructions description: Instructions for how to use the source. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Metadata associated with the source. embedding: anyOf: - type: string - type: 'null' title: Embedding description: The handle for the embedding config used by the source. embedding_chunk_size: anyOf: - type: integer - type: 'null' title: Embedding Chunk Size description: The chunk size of the embedding. embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: (Legacy) The embedding configuration used by the source. id: type: string title: Id description: Human-readable identifier for this source in the file additionalProperties: false type: object required: - name - id title: SourceSchema description: Source with human-readable ID for agent file SourceStats: properties: source_id: type: string title: Source Id description: 'Deprecated: Use `folder_id` field instead. Unique identifier of the source' deprecated: true source_name: type: string title: Source Name description: 'Deprecated: Use `folder_name` field instead. Name of the source' deprecated: true file_count: type: integer title: File Count description: Number of files in the source default: 0 total_size: type: integer title: Total Size description: Total size of all files in bytes default: 0 files: items: $ref: '#/components/schemas/FileStats' type: array title: Files description: List of file statistics additionalProperties: false type: object required: - source_id - source_name title: SourceStats description: Aggregated metadata for a source SourceUpdate: properties: name: anyOf: - type: string - type: 'null' title: Name description: The name of the source. description: anyOf: - type: string - type: 'null' title: Description description: The description of the source. instructions: anyOf: - type: string - type: 'null' title: Instructions description: Instructions for how to use the source. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Metadata associated with the source. embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: The embedding configuration used by the source. additionalProperties: false type: object title: SourceUpdate description: Schema for updating an existing Source. StdioMCPServer: properties: mcp_server_type: type: string const: stdio title: Mcp Server Type default: stdio command: type: string title: Command description: The command to run (MCP 'local' client will run this command) args: items: type: string type: array title: Args description: The arguments to pass to the command env: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Env description: Environment variables to set id: type: string pattern: ^mcp_server-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Mcp_server examples: - mcp_server-123e4567-e89b-12d3-a456-426614174000 server_name: type: string title: Server Name description: The name of the MCP server additionalProperties: false type: object required: - command - args - server_name title: StdioMCPServer description: A Stdio MCP server StdioServerConfig: properties: server_name: type: string title: Server Name description: The name of the server type: $ref: '#/components/schemas/MCPServerType' default: stdio command: type: string title: Command description: The command to run (MCP 'local' client will run this command) args: items: type: string type: array title: Args description: The arguments to pass to the command env: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Env description: Environment variables to set type: object required: - server_name - command - args title: StdioServerConfig Step: properties: id: type: string title: Id description: The id of the step. Assigned by the database. origin: anyOf: - type: string - type: 'null' title: Origin description: The surface that this agent step was initiated from. provider_id: anyOf: - type: string - type: 'null' title: Provider Id description: The unique identifier of the provider that was configured for this step run_id: anyOf: - type: string - type: 'null' title: Run Id description: The unique identifier of the run that this step belongs to. Only included for async calls. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The ID of the agent that performed the step. provider_name: anyOf: - type: string - type: 'null' title: Provider Name description: The name of the provider used for this step. provider_category: anyOf: - type: string - type: 'null' title: Provider Category description: The category of the provider used for this step. model: anyOf: - type: string - type: 'null' title: Model description: The name of the model used for this step. model_handle: anyOf: - type: string - type: 'null' title: Model Handle description: The model handle (e.g., 'openai/gpt-4o-mini') used for this step. model_endpoint: anyOf: - type: string - type: 'null' title: Model Endpoint description: The model endpoint url used for this step. context_window_limit: anyOf: - type: integer - type: 'null' title: Context Window Limit description: The context window limit configured for this step. completion_tokens: anyOf: - type: integer - type: 'null' title: Completion Tokens description: The number of tokens generated by the agent during this step. prompt_tokens: anyOf: - type: integer - type: 'null' title: Prompt Tokens description: The number of tokens in the prompt during this step. total_tokens: anyOf: - type: integer - type: 'null' title: Total Tokens description: The total number of tokens processed by the agent during this step. cached_input_tokens: anyOf: - type: integer - type: 'null' title: Cached Input Tokens description: The number of input tokens served from cache. None if not reported by provider. cache_write_tokens: anyOf: - type: integer - type: 'null' title: Cache Write Tokens description: The number of input tokens written to cache (Anthropic only). None if not reported by provider. reasoning_tokens: anyOf: - type: integer - type: 'null' title: Reasoning Tokens description: The number of reasoning/thinking tokens generated. None if not reported by provider. completion_tokens_details: anyOf: - additionalProperties: true type: object - type: 'null' title: Completion Tokens Details description: Detailed completion token breakdown (e.g., reasoning_tokens). prompt_tokens_details: anyOf: - additionalProperties: true type: object - type: 'null' title: Prompt Tokens Details description: Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens, cache_creation_tokens). stop_reason: anyOf: - $ref: '#/components/schemas/StopReasonType' - type: 'null' description: The stop reason associated with the step. tags: items: type: string type: array title: Tags description: Metadata tags. default: [] tid: anyOf: - type: string - type: 'null' title: Tid description: The unique identifier of the transaction that processed this step. trace_id: anyOf: - type: string - type: 'null' title: Trace Id description: The trace id of the agent step. request_id: anyOf: - type: string - type: 'null' title: Request Id description: The API request log ID from cloud-api for correlating steps with API requests. messages: items: $ref: '#/components/schemas/Message' type: array title: Messages description: 'The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead' default: [] deprecated: true feedback: anyOf: - type: string enum: - positive - negative - type: 'null' title: Feedback description: The feedback for this step. Must be either 'positive' or 'negative'. project_id: anyOf: - type: string - type: 'null' title: Project Id description: The project that the agent that executed this step belongs to (cloud only). error_type: anyOf: - type: string - type: 'null' title: Error Type description: The type/class of the error that occurred error_data: anyOf: - additionalProperties: true type: object - type: 'null' title: Error Data description: Error details including message, traceback, and additional context status: anyOf: - $ref: '#/components/schemas/StepStatus' - type: 'null' description: 'Step status: pending, success, or failed' default: pending additionalProperties: false type: object required: - id title: Step StepMetrics: properties: id: type: string title: Id description: The id of the step this metric belongs to (matches steps.id). provider_id: anyOf: - type: string - type: 'null' title: Provider Id description: The unique identifier of the provider. run_id: anyOf: - type: string - type: 'null' title: Run Id description: The unique identifier of the run. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent. step_start_ns: anyOf: - type: integer - type: 'null' title: Step Start Ns description: The timestamp of the start of the step in nanoseconds. llm_request_start_ns: anyOf: - type: integer - type: 'null' title: Llm Request Start Ns description: The timestamp of the start of the llm request in nanoseconds. llm_request_ns: anyOf: - type: integer - type: 'null' title: Llm Request Ns description: Time spent on LLM requests in nanoseconds. tool_execution_ns: anyOf: - type: integer - type: 'null' title: Tool Execution Ns description: Time spent on tool execution in nanoseconds. step_ns: anyOf: - type: integer - type: 'null' title: Step Ns description: Total time for the step in nanoseconds. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template ID that the step belongs to (cloud only). template_id: anyOf: - type: string - type: 'null' title: Template Id description: The template ID that the step belongs to (cloud only). project_id: anyOf: - type: string - type: 'null' title: Project Id description: The project that the step belongs to (cloud only). additionalProperties: false type: object required: - id title: StepMetrics StepStatus: type: string enum: - pending - success - failed - cancelled title: StepStatus description: Status of a step execution 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 StreamableHTTPMCPServer: properties: mcp_server_type: type: string const: streamable_http title: Mcp Server Type default: streamable_http server_url: type: string title: Server Url description: The URL of the server auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom HTTP headers to include with requests id: type: string pattern: ^mcp_server-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Mcp_server examples: - mcp_server-123e4567-e89b-12d3-a456-426614174000 server_name: type: string title: Server Name description: The name of the MCP server additionalProperties: false type: object required: - server_url - server_name title: StreamableHTTPMCPServer description: A Streamable HTTP MCP server StreamableHTTPServerConfig: properties: server_name: type: string title: Server Name description: The name of the server type: $ref: '#/components/schemas/MCPServerType' default: streamable_http server_url: type: string title: Server Url description: The URL of the server auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom HTTP headers to include with requests type: object required: - server_name - server_url title: StreamableHTTPServerConfig description: Configuration for an MCP server using Streamable HTTP SummarizedReasoningContent: properties: type: type: string const: summarized_reasoning title: Type description: Indicates this is a summarized reasoning step. default: summarized_reasoning id: type: string title: Id description: The unique identifier for this reasoning step. summary: items: $ref: '#/components/schemas/SummarizedReasoningContentPart' type: array title: Summary description: Summaries of the reasoning content. encrypted_content: type: string title: Encrypted Content description: The encrypted reasoning content. type: object required: - id - summary title: SummarizedReasoningContent description: The style of reasoning content returned by the OpenAI Responses API SummarizedReasoningContentPart: properties: index: type: integer title: Index description: The index of the summary part. text: type: string title: Text description: The text of the summary part. type: object required: - index - text title: SummarizedReasoningContentPart SummaryMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: summary_message title: Message Type default: summary_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id summary: type: string title: Summary compaction_stats: anyOf: - $ref: '#/components/schemas/CompactionStats' - type: 'null' type: object required: - id - date - summary title: SummaryMessage description: A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. SupervisorManager: properties: manager_type: type: string const: supervisor title: Manager Type description: '' default: supervisor manager_agent_id: type: string maxLength: 42 minLength: 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}$ title: Manager Agent Id description: '' examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: object required: - manager_agent_id title: SupervisorManager SupervisorManagerSchema: properties: manager_type: type: string const: supervisor title: Manager Type description: '' default: supervisor manager_agent_id: type: string title: Manager Agent Id description: '' type: object required: - manager_agent_id title: SupervisorManagerSchema SupervisorManagerUpdate: properties: manager_type: type: string const: supervisor title: Manager Type description: '' default: supervisor manager_agent_id: anyOf: - type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 - type: 'null' title: Manager Agent Id description: '' type: object required: - manager_agent_id title: SupervisorManagerUpdate SystemMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: system_message title: Message Type description: The type of the message. default: system_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id content: type: string title: Content description: The message content sent by the system type: object required: - id - date - content title: SystemMessage description: "A message generated by the system. Never streamed back on a response, only used for cursor pagination.\n\ \nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n\ \ name (Optional[str]): The name of the sender of the message\n content (str): The message content sent by the\ \ system" SystemMessageListResult: properties: message_type: type: string const: system_message title: Message Type default: system_message content: type: string title: Content description: The message content sent by the system (can be a string or an array of multi-modal content parts) message_id: type: string title: Message Id description: The unique identifier of the message. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent that owns the message. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation that the message belongs to. created_at: type: string format: date-time title: Created At description: The time the message was created in ISO format. type: object required: - content - message_id - created_at title: SystemMessageListResult description: 'System message list result with agent context. Shape is identical to UpdateSystemMessage but includes the owning agent_id and message id.' TagSchema: properties: tag: type: string title: Tag type: object required: - tag title: TagSchema TerminalToolRule: 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: exit_loop title: Type default: exit_loop prompt_template: anyOf: - type: string - type: 'null' title: Prompt Template description: Optional template string (ignored). additionalProperties: false type: object required: - tool_name title: TerminalToolRule description: Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. TextContent: properties: type: type: string const: text title: Type description: The type of the message. default: text text: type: string title: Text description: The text content of the message. signature: anyOf: - type: string - type: 'null' title: Signature description: Stores a unique identifier for any reasoning associated with this text content. type: object required: - text title: TextContent 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. TogetherModelSettings: 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: together title: Provider Type description: The type of the provider. default: together temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 response_format: 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 Format description: The response format for the model. type: object title: TogetherModelSettings description: Together AI model configuration (OpenAI-compatible). 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. ToolAnnotations: properties: title: anyOf: - type: string - type: 'null' title: Title readOnlyHint: anyOf: - type: boolean - type: 'null' title: Readonlyhint destructiveHint: anyOf: - type: boolean - type: 'null' title: Destructivehint idempotentHint: anyOf: - type: boolean - type: 'null' title: Idempotenthint openWorldHint: anyOf: - type: boolean - type: 'null' title: Openworldhint additionalProperties: true type: object title: ToolAnnotations description: 'Additional properties describing a Tool to clients. NOTE: all properties in ToolAnnotations are **hints**. They are not guaranteed to provide a faithful description of tool behavior (including descriptive properties like `title`). Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers.' ToolCall: properties: name: type: string title: Name arguments: type: string title: Arguments tool_call_id: type: string title: Tool Call Id type: object required: - name - arguments - tool_call_id title: ToolCall ToolCallContent: properties: type: type: string const: tool_call title: Type description: Indicates this content represents a tool call event. default: tool_call id: type: string title: Id description: A unique identifier for this specific tool call instance. name: type: string title: Name description: The name of the tool being called. input: additionalProperties: true type: object title: Input description: The parameters being passed to the tool, structured as a dictionary of parameter names to values. signature: anyOf: - type: string - type: 'null' title: Signature description: Stores a unique identifier for any reasoning associated with this tool call. type: object required: - id - name - input title: ToolCallContent 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 ToolCallMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: tool_call_message title: Message Type description: The type of the message. default: tool_call_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id tool_call: anyOf: - $ref: '#/components/schemas/ToolCall' - $ref: '#/components/schemas/ToolCallDelta' title: Tool Call deprecated: true tool_calls: anyOf: - items: $ref: '#/components/schemas/ToolCall' type: array - $ref: '#/components/schemas/ToolCallDelta' - type: 'null' title: Tool Calls type: object required: - id - date - tool_call title: ToolCallMessage description: "A message representing a request to call a tool (generated by the LLM to trigger tool execution).\n\n\ Args:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n\ \ name (Optional[str]): The name of the sender of the message\n tool_call (Union[ToolCall, ToolCallDelta]):\ \ The tool call" ToolCallNode: properties: name: type: string title: Name description: The name of the child tool to invoke next. args: anyOf: - additionalProperties: true type: object - type: 'null' title: Args description: Optional prefilled arguments for this child tool. Keys must match the tool's parameter names and values must satisfy the tool's JSON schema. Supports partial prefill; non-overlapping parameters are left to the model. type: object required: - name title: ToolCallNode description: 'Typed child override for prefilled arguments. When used in a ChildToolRule, if this child is selected next, its `args` will be applied as prefilled arguments (overriding overlapping LLM-provided values).' ToolCreate: properties: description: anyOf: - type: string - type: 'null' title: Description description: The description of the tool. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: Metadata tags. source_code: type: string title: Source Code description: The source code of the function. source_type: type: string title: Source Type description: The source type of the function. default: python json_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Json Schema description: The JSON schema of the function (auto-generated from source_code if not provided) 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: Whether or not to require approval before executing this tool. 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 additionalProperties: false type: object required: - source_code title: ToolCreate ToolEnvVarSchema: properties: created_at: type: string title: Created At description: anyOf: - type: string - type: 'null' title: Description key: type: string title: Key updated_at: type: string title: Updated At value: type: string title: Value type: object required: - created_at - description - key - updated_at - value title: ToolEnvVarSchema ToolExecutionResult: properties: status: type: string enum: - success - error title: Status description: The status of the tool execution and return object func_return: anyOf: - {} - type: 'null' title: Func Return description: The function return object agent_state: anyOf: - $ref: '#/components/schemas/AgentState' - type: 'null' description: The agent state deprecated: true stdout: anyOf: - items: type: string type: array - type: 'null' title: Stdout description: Captured stdout (prints, logs) from function invocation stderr: anyOf: - items: type: string type: array - type: 'null' title: Stderr description: Captured stderr from the function invocation sandbox_config_fingerprint: anyOf: - type: string - type: 'null' title: Sandbox Config Fingerprint description: The fingerprint of the config for the sandbox type: object required: - status title: ToolExecutionResult ToolJSONSchema: properties: name: type: string title: Name description: type: string title: Description parameters: $ref: '#/components/schemas/ParametersSchema' type: anyOf: - type: string - type: 'null' title: Type required: anyOf: - items: type: string type: array - type: 'null' title: Required type: object required: - name - description - parameters title: ToolJSONSchema ToolReturnContent: properties: type: type: string const: tool_return title: Type description: Indicates this content represents a tool return event. default: tool_return tool_call_id: type: string title: Tool Call Id description: References the ID of the ToolCallContent that initiated this tool call. content: type: string title: Content description: The content returned by the tool execution. is_error: type: boolean title: Is Error description: Indicates whether the tool execution resulted in an error. type: object required: - tool_call_id - content - is_error title: ToolReturnContent ToolReturnCreate: properties: type: type: string const: tool_return title: Type description: The message type to be created. default: tool_return otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in tool_returns: items: $ref: '#/components/schemas/letta__schemas__letta_message__ToolReturn' type: array title: Tool Returns description: List of tool returns from client-side execution type: object required: - tool_returns title: ToolReturnCreate description: 'Submit tool return(s) from client-side tool execution. This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case.' ToolReturnMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: tool_return_message title: Message Type description: The type of the message. default: tool_return_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id tool_return: type: string title: Tool Return deprecated: true status: type: string enum: - success - error title: Status deprecated: true tool_call_id: type: string title: Tool Call Id deprecated: true stdout: anyOf: - items: type: string type: array - type: 'null' title: Stdout deprecated: true stderr: anyOf: - items: type: string type: array - type: 'null' title: Stderr deprecated: true tool_returns: anyOf: - items: $ref: '#/components/schemas/letta__schemas__letta_message__ToolReturn' type: array - type: 'null' title: Tool Returns type: object required: - id - date - tool_return - status - tool_call_id title: ToolReturnMessage description: "A message representing the return value of a tool call (generated by Letta executing the requested tool).\n\ \nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n\ \ name (Optional[str]): The name of the sender of the message\n tool_return (str): The return value of the tool\ \ (deprecated, use tool_returns)\n status (Literal[\"success\", \"error\"]): The status of the tool call (deprecated,\ \ use tool_returns)\n tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated,\ \ use tool_returns)\n stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation\ \ (deprecated, use tool_returns)\n stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated,\ \ use tool_returns)\n tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support" ToolRunFromSource: properties: source_code: type: string title: Source Code description: The source code of the function. args: additionalProperties: true type: object title: Args description: The arguments to pass to the tool. env_vars: additionalProperties: type: string type: object title: Env Vars description: The environment variables to pass to the tool. name: anyOf: - type: string - type: 'null' title: Name description: The name of the tool to run. source_type: anyOf: - type: string - type: 'null' title: Source Type description: The type of the source code. args_json_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Args Json Schema description: The args JSON schema of the function. json_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Json Schema description: The JSON schema of the function (auto-generated from source_code if not provided) 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. additionalProperties: false type: object required: - source_code - args title: ToolRunFromSource ToolSearchRequest: properties: query: anyOf: - type: string - type: 'null' title: Query description: Text query for semantic search. search_mode: type: string enum: - vector - fts - hybrid title: Search Mode description: 'Search mode: vector, fts, or hybrid.' default: hybrid tool_types: anyOf: - items: type: string type: array - type: 'null' title: Tool Types description: Filter by tool types (e.g., 'custom', 'letta_core'). tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: Filter by tags (match any). limit: type: integer maximum: 100 minimum: 1 title: Limit description: Maximum number of results to return. default: 50 additionalProperties: false type: object title: ToolSearchRequest description: Request model for searching tools using semantic search. ToolSearchResult: properties: tool: $ref: '#/components/schemas/Tool' description: The matched tool. embedded_text: anyOf: - type: string - type: 'null' title: Embedded Text description: The embedded text content used for matching. fts_rank: anyOf: - type: integer - type: 'null' title: Fts Rank description: Full-text search rank position. vector_rank: anyOf: - type: integer - type: 'null' title: Vector Rank description: Vector search rank position. combined_score: type: number title: Combined Score description: Combined relevance score (RRF for hybrid mode). additionalProperties: false type: object required: - tool - combined_score title: ToolSearchResult description: Result from a tool search operation. 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 ToolUpdate: properties: description: anyOf: - type: string - type: 'null' title: Description description: The description of the tool. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: Metadata tags. source_code: anyOf: - type: string - type: 'null' title: Source Code description: The source code of the function. source_type: anyOf: - type: string - type: 'null' title: Source Type description: The type of the source code. json_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Json Schema description: The JSON schema of the function (auto-generated from source_code if not provided) 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: anyOf: - type: integer maximum: 1000000 minimum: 1 - type: 'null' title: Return Char Limit description: The maximum number of characters in the response. 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. metadata_: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: A dictionary of additional metadata for the tool. default_requires_approval: anyOf: - type: boolean - type: 'null' title: Default Requires Approval description: Whether or not to require approval before executing this tool. 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 type: object title: ToolUpdate TurnTokenData: properties: role: type: string enum: - assistant - tool title: Role description: 'Role of this turn: ''assistant'' for LLM generations (trainable), ''tool'' for tool results (non-trainable).' output_ids: anyOf: - items: type: integer type: array - type: 'null' title: Output Ids description: Token IDs from SGLang native endpoint. Only present for assistant turns. output_token_logprobs: anyOf: - items: items: {} type: array type: array - type: 'null' title: Output Token Logprobs description: 'Logprobs from SGLang: [[logprob, token_id, top_logprob_or_null], ...]. Only present for assistant turns.' content: anyOf: - type: string - type: 'null' title: Content description: Text content. For tool turns, client tokenizes this with loss_mask=0. tool_name: anyOf: - type: string - type: 'null' title: Tool Name description: Name of the tool called. Only present for tool turns. type: object required: - role title: TurnTokenData description: 'Token data for a single LLM generation turn in a multi-turn agent interaction. Used for RL training to track token IDs and logprobs across all LLM calls, not just the final one. Tool results are included so the client can tokenize them with loss_mask=0 (non-trainable).' UpdateAgent: properties: name: anyOf: - type: string - type: 'null' title: Name description: The name of the agent. tool_ids: anyOf: - items: type: string maxLength: 41 minLength: 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-' examples: - tool-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Tool Ids description: The ids of the tools used by the agent. source_ids: anyOf: - items: type: string maxLength: 43 minLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Source Ids description: 'Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent.' deprecated: true folder_ids: anyOf: - items: type: string maxLength: 43 minLength: 43 pattern: ^source-[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 source in the format 'source-' examples: - source-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Folder Ids description: The ids of the folders used by the agent. block_ids: anyOf: - items: type: string maxLength: 42 minLength: 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-' examples: - block-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Block Ids description: The ids of the blocks used by the agent. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags associated with the agent. system: anyOf: - type: string - type: 'null' title: System description: The system prompt used by the agent. tool_rules: anyOf: - items: oneOf: - $ref: '#/components/schemas/ChildToolRule' - $ref: '#/components/schemas/InitToolRule' - $ref: '#/components/schemas/TerminalToolRule' - $ref: '#/components/schemas/ConditionalToolRule' - $ref: '#/components/schemas/ContinueToolRule' - $ref: '#/components/schemas/RequiredBeforeExitToolRule' - $ref: '#/components/schemas/MaxCountPerStepToolRule' - $ref: '#/components/schemas/ParentToolRule' - $ref: '#/components/schemas/RequiresApprovalToolRule' discriminator: propertyName: type mapping: conditional: '#/components/schemas/ConditionalToolRule' constrain_child_tools: '#/components/schemas/ChildToolRule' continue_loop: '#/components/schemas/ContinueToolRule' exit_loop: '#/components/schemas/TerminalToolRule' max_count_per_step: '#/components/schemas/MaxCountPerStepToolRule' parent_last_tool: '#/components/schemas/ParentToolRule' required_before_exit: '#/components/schemas/RequiredBeforeExitToolRule' requires_approval: '#/components/schemas/RequiresApprovalToolRule' run_first: '#/components/schemas/InitToolRule' type: array - type: 'null' title: Tool Rules description: The tool rules governing the agent. message_ids: anyOf: - items: type: string maxLength: 44 minLength: 44 pattern: ^message-[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 message in the format 'message-' examples: - message-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Message Ids description: The ids of the messages in the agent's in-context memory. description: anyOf: - type: string - type: 'null' title: Description description: The description of the agent. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: The metadata of the agent. tool_exec_environment_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Tool Exec Environment Variables description: 'Deprecated: use `secrets` field instead' secrets: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Secrets description: The environment variables for tool execution specific to this agent. project_id: anyOf: - type: string - type: 'null' title: Project Id description: The id of the project the agent belongs to. template_id: anyOf: - type: string - type: 'null' title: Template Id description: The id of the template the agent belongs to. base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: The base template id of the agent. identity_ids: anyOf: - items: type: string maxLength: 45 minLength: 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}$ description: The ID of the identity in the format 'identity-' examples: - identity-123e4567-e89b-42d3-8456-426614174000 type: array - type: 'null' title: Identity Ids description: The ids of the identities associated with this agent. message_buffer_autoclear: anyOf: - type: boolean - type: 'null' title: Message Buffer Autoclear description: If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case. model: anyOf: - type: string - type: 'null' title: Model description: 'The model handle used by the agent (format: provider/model-name).' embedding: anyOf: - type: string - type: 'null' title: Embedding description: 'The embedding model handle used by the agent (format: provider/model-name).' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: The model settings for the agent. compaction_settings: anyOf: - $ref: '#/components/schemas/CompactionSettings-Input' - type: 'null' description: The compaction settings configuration used for compaction. context_window_limit: anyOf: - type: integer - type: 'null' title: Context Window Limit description: The context window limit used by the agent. reasoning: anyOf: - type: boolean - type: 'null' title: Reasoning description: 'Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent.' deprecated: true llm_config: anyOf: - $ref: '#/components/schemas/LLMConfig' - type: 'null' description: 'Deprecated: Use `model` field instead. The LLM configuration used by the agent.' deprecated: true embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: The embedding configuration used by the agent. parallel_tool_calls: anyOf: - type: boolean - type: 'null' title: Parallel Tool Calls description: 'Deprecated: Use `model_settings` to configure parallel tool calls instead. If set to True, enables parallel tool calling.' deprecated: true response_format: 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 Format description: 'Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent.' deprecated: true max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens description: 'Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step.' deprecated: true enable_sleeptime: anyOf: - type: boolean - type: 'null' title: Enable Sleeptime description: If set to True, memory management will move to a background agent thread. last_run_completion: anyOf: - type: string format: date-time - type: 'null' title: Last Run Completion description: The timestamp when the agent last completed a run. last_run_duration_ms: anyOf: - type: integer - type: 'null' title: Last Run Duration Ms description: The duration in milliseconds of the agent's last run. last_stop_reason: anyOf: - $ref: '#/components/schemas/StopReasonType' - type: 'null' description: The stop reason from the agent's last run. timezone: anyOf: - type: string - type: 'null' title: Timezone description: The timezone of the agent (IANA format). max_files_open: anyOf: - type: integer - type: 'null' title: Max Files Open description: Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent. per_file_view_window_char_limit: anyOf: - type: integer - type: 'null' title: Per File View Window Char Limit description: The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent. hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: If set to True, the agent will be hidden. type: object title: UpdateAgent UpdateAssistantMessage: properties: message_type: type: string const: assistant_message title: Message Type default: assistant_message content: anyOf: - items: $ref: '#/components/schemas/LettaAssistantMessageContentUnion' type: array - type: string title: Content description: The message content sent by the assistant (can be a string or an array of content parts) type: object required: - content title: UpdateAssistantMessage UpdateConversation: properties: summary: anyOf: - type: string - type: 'null' title: Summary description: A summary of the conversation. model: anyOf: - type: string - type: 'null' title: Model description: 'The model handle for this conversation (overrides agent''s model). Format: provider/model-name.' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: The model settings for this conversation (overrides agent's model settings). last_message_at: anyOf: - type: string format: date-time - type: 'null' title: Last Message At description: Timestamp of the most recent message request sent to this conversation. type: object title: UpdateConversation description: Request model for updating a conversation. UpdateMCPServerRequest: properties: server_name: anyOf: - type: string - type: 'null' title: Server Name description: The name of the MCP server config: oneOf: - $ref: '#/components/schemas/letta__schemas__mcp_server__UpdateStdioMCPServer' - $ref: '#/components/schemas/letta__schemas__mcp_server__UpdateSSEMCPServer' - $ref: '#/components/schemas/letta__schemas__mcp_server__UpdateStreamableHTTPMCPServer' title: Config description: The MCP server configuration updates (Stdio, SSE, or Streamable HTTP) discriminator: propertyName: mcp_server_type mapping: sse: '#/components/schemas/letta__schemas__mcp_server__UpdateSSEMCPServer' stdio: '#/components/schemas/letta__schemas__mcp_server__UpdateStdioMCPServer' streamable_http: '#/components/schemas/letta__schemas__mcp_server__UpdateStreamableHTTPMCPServer' additionalProperties: false type: object required: - config title: UpdateMCPServerRequest description: Request to update an existing MCP server configuration. UpdateReasoningMessage: properties: reasoning: type: string title: Reasoning message_type: type: string const: reasoning_message title: Message Type default: reasoning_message type: object required: - reasoning title: UpdateReasoningMessage UpdateSystemMessage: properties: message_type: type: string const: system_message title: Message Type default: system_message content: type: string title: Content description: The message content sent by the system (can be a string or an array of multi-modal content parts) type: object required: - content title: UpdateSystemMessage UpdateUserMessage: properties: message_type: type: string const: user_message title: Message Type default: user_message content: anyOf: - items: $ref: '#/components/schemas/LettaUserMessageContentUnion' type: array - type: string title: Content description: The message content sent by the user (can be a string or an array of multi-modal content parts) type: object required: - content title: UpdateUserMessage UrlImage: properties: type: type: string const: url title: Type description: The source type for the image. default: url url: type: string title: Url description: The URL of the image. type: object required: - url title: UrlImage UsageStatistics: properties: completion_tokens: type: integer title: Completion Tokens default: 0 prompt_tokens: type: integer title: Prompt Tokens default: 0 total_tokens: type: integer title: Total Tokens default: 0 prompt_tokens_details: anyOf: - $ref: '#/components/schemas/UsageStatisticsPromptTokenDetails' - type: 'null' completion_tokens_details: anyOf: - $ref: '#/components/schemas/UsageStatisticsCompletionTokenDetails' - type: 'null' type: object title: UsageStatistics UsageStatisticsCompletionTokenDetails: properties: reasoning_tokens: anyOf: - type: integer - type: 'null' title: Reasoning Tokens type: object title: UsageStatisticsCompletionTokenDetails UsageStatisticsPromptTokenDetails: properties: cached_tokens: anyOf: - type: integer - type: 'null' title: Cached Tokens cache_read_tokens: anyOf: - type: integer - type: 'null' title: Cache Read Tokens cache_creation_tokens: anyOf: - type: integer - type: 'null' title: Cache Creation Tokens type: object title: UsageStatisticsPromptTokenDetails User: properties: id: type: string pattern: ^user-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the User examples: - user-123e4567-e89b-12d3-a456-426614174000 name: type: string title: Name description: The name of the user. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: The creation date of the user. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The update date of the user. is_deleted: type: boolean title: Is Deleted description: Whether this user is deleted or not. default: false additionalProperties: false type: object required: - name title: User description: Representation of a user. UserCreate: properties: name: type: string title: Name description: The name of the user. additionalProperties: false type: object required: - name - organization_id title: UserCreate UserMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: user_message title: Message Type description: The type of the message. default: user_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id content: anyOf: - items: $ref: '#/components/schemas/LettaUserMessageContentUnion' type: array - type: string title: Content description: The message content sent by the user (can be a string or an array of multi-modal content parts) type: object required: - id - date - content title: UserMessage description: "A message sent by the user. Never streamed back on a response, only used for cursor pagination.\n\nArgs:\n\ \ id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n name\ \ (Optional[str]): The name of the sender of the message\n content (Union[str, List[LettaUserMessageContentUnion]]):\ \ The message content sent by the user (can be a string or an array of multi-modal content parts)" UserMessageListResult: properties: message_type: type: string const: user_message title: Message Type default: user_message content: anyOf: - items: $ref: '#/components/schemas/LettaUserMessageContentUnion' type: array - type: string title: Content description: The message content sent by the user (can be a string or an array of multi-modal content parts) message_id: type: string title: Message Id description: The unique identifier of the message. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent that owns the message. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation that the message belongs to. created_at: type: string format: date-time title: Created At description: The time the message was created in ISO format. type: object required: - content - message_id - created_at title: UserMessageListResult description: 'User message list result with agent context. Shape is identical to UpdateUserMessage but includes the owning agent_id and message id.' UserUpdate: properties: id: type: string maxLength: 41 minLength: 41 pattern: ^user-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ title: Id description: The id of the user to update. examples: - user-123e4567-e89b-42d3-8456-426614174000 name: anyOf: - type: string - type: 'null' title: Name description: The new name of the user. additionalProperties: false type: object required: - id title: UserUpdate ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError VectorDBProvider: type: string enum: - native - tpuf - pinecone title: VectorDBProvider description: Supported vector database providers for archival memory VoiceSleeptimeManager: properties: manager_type: type: string const: voice_sleeptime title: Manager Type description: '' default: voice_sleeptime manager_agent_id: type: string maxLength: 42 minLength: 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}$ title: Manager Agent Id description: '' examples: - agent-123e4567-e89b-42d3-8456-426614174000 max_message_buffer_length: anyOf: - type: integer - type: 'null' title: Max Message Buffer Length description: The desired maximum length of messages in the context window of the convo agent. This is a best effort, and may be off slightly due to user/assistant interleaving. min_message_buffer_length: anyOf: - type: integer - type: 'null' title: Min Message Buffer Length description: The desired minimum length of messages in the context window of the convo agent. This is a best effort, and may be off-by-one due to user/assistant interleaving. type: object required: - manager_agent_id title: VoiceSleeptimeManager VoiceSleeptimeManagerSchema: properties: manager_type: type: string const: voice_sleeptime title: Manager Type description: '' default: voice_sleeptime manager_agent_id: type: string title: Manager Agent Id description: '' max_message_buffer_length: anyOf: - type: integer - type: 'null' title: Max Message Buffer Length description: '' min_message_buffer_length: anyOf: - type: integer - type: 'null' title: Min Message Buffer Length description: '' type: object required: - manager_agent_id title: VoiceSleeptimeManagerSchema VoiceSleeptimeManagerUpdate: properties: manager_type: type: string const: voice_sleeptime title: Manager Type description: '' default: voice_sleeptime manager_agent_id: anyOf: - type: string maxLength: 42 minLength: 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-' examples: - agent-123e4567-e89b-42d3-8456-426614174000 - type: 'null' title: Manager Agent Id description: '' max_message_buffer_length: anyOf: - type: integer - type: 'null' title: Max Message Buffer Length description: The desired maximum length of messages in the context window of the convo agent. This is a best effort, and may be off slightly due to user/assistant interleaving. min_message_buffer_length: anyOf: - type: integer - type: 'null' title: Min Message Buffer Length description: The desired minimum length of messages in the context window of the convo agent. This is a best effort, and may be off-by-one due to user/assistant interleaving. type: object title: VoiceSleeptimeManagerUpdate XAIModelSettings: 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: xai title: Provider Type description: The type of the provider. default: xai temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 response_format: 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 Format description: The response format for the model. type: object title: XAIModelSettings description: xAI model configuration (OpenAI-compatible). ZAIModelSettings: 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: zai title: Provider Type description: The type of the provider. default: zai temperature: type: number title: Temperature description: The temperature of the model. default: 0.7 response_format: 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 Format description: The response format for the model. thinking: $ref: '#/components/schemas/ZAIThinking' description: The thinking configuration for GLM-4.5+ models. default: type: enabled clear_thinking: false type: object title: ZAIModelSettings description: Z.ai (ZhipuAI) model configuration (OpenAI-compatible). 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. letta__schemas__agent_file__AgentSchema: properties: name: type: string title: Name description: The name of the agent. memory_blocks: anyOf: - items: $ref: '#/components/schemas/CreateBlock' type: array - type: 'null' title: Memory Blocks description: The blocks to create in the agent's in-context memory. tools: anyOf: - items: type: string type: array - type: 'null' title: Tools description: The tools used by the agent. tool_ids: anyOf: - items: type: string type: array - type: 'null' title: Tool Ids description: The ids of the tools used by the agent. source_ids: anyOf: - items: type: string type: array - type: 'null' title: Source Ids description: The ids of the sources used by the agent. folder_ids: anyOf: - items: type: string type: array - type: 'null' title: Folder Ids description: The ids of the folders used by the agent. block_ids: anyOf: - items: type: string type: array - type: 'null' title: Block Ids description: The ids of the blocks used by the agent. tool_rules: anyOf: - items: oneOf: - $ref: '#/components/schemas/ChildToolRule' - $ref: '#/components/schemas/InitToolRule' - $ref: '#/components/schemas/TerminalToolRule' - $ref: '#/components/schemas/ConditionalToolRule' - $ref: '#/components/schemas/ContinueToolRule' - $ref: '#/components/schemas/RequiredBeforeExitToolRule' - $ref: '#/components/schemas/MaxCountPerStepToolRule' - $ref: '#/components/schemas/ParentToolRule' - $ref: '#/components/schemas/RequiresApprovalToolRule' discriminator: propertyName: type mapping: conditional: '#/components/schemas/ConditionalToolRule' constrain_child_tools: '#/components/schemas/ChildToolRule' continue_loop: '#/components/schemas/ContinueToolRule' exit_loop: '#/components/schemas/TerminalToolRule' max_count_per_step: '#/components/schemas/MaxCountPerStepToolRule' parent_last_tool: '#/components/schemas/ParentToolRule' required_before_exit: '#/components/schemas/RequiredBeforeExitToolRule' requires_approval: '#/components/schemas/RequiresApprovalToolRule' run_first: '#/components/schemas/InitToolRule' type: array - type: 'null' title: Tool Rules description: The tool rules governing the agent. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags associated with the agent. system: anyOf: - type: string - type: 'null' title: System description: The system prompt used by the agent. agent_type: $ref: '#/components/schemas/AgentType' description: The type of agent. initial_message_sequence: anyOf: - items: $ref: '#/components/schemas/MessageCreate' type: array - type: 'null' title: Initial Message Sequence description: The initial set of messages to put in the agent's in-context memory. include_base_tools: type: boolean title: Include Base Tools description: If true, attaches the Letta core tools (e.g. core_memory related functions). default: true include_multi_agent_tools: type: boolean title: Include Multi Agent Tools description: If true, attaches the Letta multi-agent tools (e.g. sending a message to another agent). default: false include_base_tool_rules: anyOf: - type: boolean - type: 'null' title: Include Base Tool Rules description: If true, attaches the Letta base tool rules (e.g. deny all tools not explicitly allowed). include_default_source: type: boolean title: Include Default Source description: If true, automatically creates and attaches a default data source for this agent. default: false deprecated: true description: anyOf: - type: string - type: 'null' title: Description description: The description of the agent. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: The metadata of the agent. llm_config: anyOf: - $ref: '#/components/schemas/LLMConfig' - type: 'null' description: 'Deprecated: Use `model` field instead. The LLM configuration used by the agent.' deprecated: true embedding_config: anyOf: - $ref: '#/components/schemas/EmbeddingConfig' - type: 'null' description: 'Deprecated: Use `embedding` field instead. The embedding configuration used by the agent.' deprecated: true model: anyOf: - type: string - type: 'null' title: Model description: 'The model handle for the agent to use (format: provider/model-name).' embedding: anyOf: - type: string - type: 'null' title: Embedding description: 'The embedding model handle used by the agent (format: provider/model-name).' model_settings: anyOf: - oneOf: - $ref: '#/components/schemas/OpenAIModelSettings' - $ref: '#/components/schemas/SGLangModelSettings' - $ref: '#/components/schemas/AnthropicModelSettings' - $ref: '#/components/schemas/GoogleAIModelSettings' - $ref: '#/components/schemas/GoogleVertexModelSettings' - $ref: '#/components/schemas/AzureModelSettings' - $ref: '#/components/schemas/XAIModelSettings' - $ref: '#/components/schemas/ZAIModelSettings' - $ref: '#/components/schemas/GroqModelSettings' - $ref: '#/components/schemas/DeepseekModelSettings' - $ref: '#/components/schemas/TogetherModelSettings' - $ref: '#/components/schemas/BedrockModelSettings' - $ref: '#/components/schemas/BasetenModelSettings' - $ref: '#/components/schemas/OpenRouterModelSettings' - $ref: '#/components/schemas/ChatGPTOAuthModelSettings' discriminator: propertyName: provider_type mapping: anthropic: '#/components/schemas/AnthropicModelSettings' azure: '#/components/schemas/AzureModelSettings' baseten: '#/components/schemas/BasetenModelSettings' bedrock: '#/components/schemas/BedrockModelSettings' chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings' deepseek: '#/components/schemas/DeepseekModelSettings' google_ai: '#/components/schemas/GoogleAIModelSettings' google_vertex: '#/components/schemas/GoogleVertexModelSettings' groq: '#/components/schemas/GroqModelSettings' openai: '#/components/schemas/OpenAIModelSettings' openrouter: '#/components/schemas/OpenRouterModelSettings' sglang: '#/components/schemas/SGLangModelSettings' together: '#/components/schemas/TogetherModelSettings' xai: '#/components/schemas/XAIModelSettings' zai: '#/components/schemas/ZAIModelSettings' - type: 'null' title: Model Settings description: The model settings for the agent. compaction_settings: anyOf: - $ref: '#/components/schemas/CompactionSettings-Input' - type: 'null' description: The compaction settings configuration used for compaction. context_window_limit: anyOf: - type: integer - type: 'null' title: Context Window Limit description: The context window limit used by the agent. embedding_chunk_size: anyOf: - type: integer - type: 'null' title: Embedding Chunk Size description: 'Deprecated: No longer used. The embedding chunk size used by the agent.' default: 300 deprecated: true max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens description: 'Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step.' deprecated: true max_reasoning_tokens: anyOf: - type: integer - type: 'null' title: Max Reasoning Tokens description: 'Deprecated: Use `model` field to configure reasoning tokens instead. The maximum number of tokens to generate for reasoning step.' deprecated: true enable_reasoner: anyOf: - type: boolean - type: 'null' title: Enable Reasoner description: 'Deprecated: Use `model` field to configure reasoning instead. Whether to enable internal extended thinking step for a reasoner model.' default: true deprecated: true reasoning: anyOf: - type: boolean - type: 'null' title: Reasoning description: 'Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent.' deprecated: true from_template: anyOf: - type: string - type: 'null' title: From Template description: 'Deprecated: please use the ''create agents from a template'' endpoint instead.' deprecated: true template: type: boolean title: Template description: 'Deprecated: No longer used.' default: false deprecated: true project: anyOf: - type: string - type: 'null' title: Project description: 'Deprecated: Project should now be passed via the X-Project header instead of in the request body. If using the SDK, this can be done via the x_project parameter.' deprecated: true tool_exec_environment_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Tool Exec Environment Variables description: 'Deprecated: Use `secrets` field instead. Environment variables for tool execution.' deprecated: true secrets: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Secrets description: The environment variables for tool execution specific to this agent. memory_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Memory Variables description: 'Deprecated: Only relevant for creating agents from a template. Use the ''create agents from a template'' endpoint instead.' deprecated: true project_id: anyOf: - type: string - type: 'null' title: Project Id description: 'Deprecated: No longer used. The id of the project the agent belongs to.' deprecated: true template_id: anyOf: - type: string - type: 'null' title: Template Id description: 'Deprecated: No longer used. The id of the template the agent belongs to.' deprecated: true base_template_id: anyOf: - type: string - type: 'null' title: Base Template Id description: 'Deprecated: No longer used. The base template id of the agent.' deprecated: true identity_ids: anyOf: - items: type: string type: array - type: 'null' title: Identity Ids description: The ids of the identities associated with this agent. message_buffer_autoclear: type: boolean title: Message Buffer Autoclear description: If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case. default: false enable_sleeptime: anyOf: - type: boolean - type: 'null' title: Enable Sleeptime description: If set to True, memory management will move to a background agent thread. response_format: 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 Format description: 'Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent.' deprecated: true timezone: anyOf: - type: string - type: 'null' title: Timezone description: The timezone of the agent (IANA format). max_files_open: anyOf: - type: integer - type: 'null' title: Max Files Open description: Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent. per_file_view_window_char_limit: anyOf: - type: integer - type: 'null' title: Per File View Window Char Limit description: The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent. hidden: anyOf: - type: boolean - type: 'null' title: Hidden description: 'Deprecated: No longer used. If set to True, the agent will be hidden.' deprecated: true parallel_tool_calls: anyOf: - type: boolean - type: 'null' title: Parallel Tool Calls description: 'Deprecated: Use `model_settings` to configure parallel tool calls instead. If set to True, enables parallel tool calling.' deprecated: true id: type: string title: Id description: Human-readable identifier for this agent in the file in_context_message_ids: items: type: string type: array title: In Context Message Ids description: List of message IDs that are currently in the agent's context messages: items: $ref: '#/components/schemas/letta__schemas__agent_file__MessageSchema' type: array title: Messages description: List of messages in the agent's conversation history files_agents: items: $ref: '#/components/schemas/FileAgentSchema' type: array title: Files Agents description: List of file-agent relationships for this agent group_ids: items: type: string type: array title: Group Ids description: List of groups that the agent manages type: object required: - id title: AgentSchema description: Agent with human-readable ID for agent file letta__schemas__agent_file__MessageSchema: properties: type: anyOf: - type: string const: message - type: 'null' title: Type description: The message type to be created. default: message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in role: $ref: '#/components/schemas/MessageRole' description: The role of the participant. content: anyOf: - items: $ref: '#/components/schemas/LettaMessageContentUnion' type: array - type: string title: Content description: The content of the message. name: anyOf: - type: string - type: 'null' title: Name description: The name of the participant. sender_id: anyOf: - type: string - type: 'null' title: Sender Id description: The id of the sender of the message, can be an identity id or agent id batch_item_id: anyOf: - type: string - type: 'null' title: Batch Item Id description: The id of the LLMBatchItem that this message is associated with id: type: string title: Id description: Human-readable identifier for this message in the file model: anyOf: - type: string - type: 'null' title: Model description: The model used to make the function call agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent tool_calls: anyOf: - items: $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall-Input' type: array - type: 'null' title: Tool Calls description: The list of tool calls requested. Only applicable for role assistant. tool_call_id: anyOf: - type: string - type: 'null' title: Tool Call Id description: The ID of the tool call. Only applicable for role tool. tool_returns: anyOf: - items: $ref: '#/components/schemas/letta__schemas__message__ToolReturn-Input' type: array - type: 'null' title: Tool Returns description: Tool execution return information for prior tool calls created_at: type: string format: date-time title: Created At description: The timestamp when the object was created. approve: anyOf: - type: boolean - type: 'null' title: Approve description: Whether the tool has been approved approval_request_id: anyOf: - type: string - type: 'null' title: Approval Request Id description: The message ID of the approval request denial_reason: anyOf: - type: string - type: 'null' title: Denial Reason description: An optional explanation for the provided approval status approvals: anyOf: - items: anyOf: - $ref: '#/components/schemas/ApprovalReturn' - $ref: '#/components/schemas/letta__schemas__message__ToolReturn-Input' type: array - type: 'null' title: Approvals description: Approval returns for the message type: object required: - role - content - id title: MessageSchema description: Message with human-readable ID for agent file letta__schemas__agent_file__ToolSchema: properties: id: type: string title: Id description: Human-readable identifier for this tool in the file 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 required: - id title: ToolSchema description: Tool with human-readable ID for agent file letta__schemas__letta_message__ToolReturn: properties: type: type: string const: tool title: Type description: The message type to be created. default: tool tool_return: anyOf: - items: $ref: '#/components/schemas/LettaToolReturnContentUnion' type: array - type: string title: Tool Return description: The tool return value - either a string or list of content parts (text/image) status: type: string enum: - success - error title: Status tool_call_id: type: string title: Tool Call Id stdout: anyOf: - items: type: string type: array - type: 'null' title: Stdout stderr: anyOf: - items: type: string type: array - type: 'null' title: Stderr type: object required: - tool_return - status - tool_call_id title: ToolReturn letta__schemas__mcp__UpdateSSEMCPServer: properties: server_name: anyOf: - type: string - type: 'null' title: Server Name description: The name of the MCP server server_url: anyOf: - type: string - type: 'null' title: Server Url description: The URL of the server (MCP SSE client will connect to this URL) token: anyOf: - type: string - type: 'null' title: Token description: The access token or API key for the MCP server (used for SSE authentication) custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom authentication headers as key-value pairs additionalProperties: false type: object title: UpdateSSEMCPServer description: Update an SSE MCP server letta__schemas__mcp__UpdateStdioMCPServer: properties: server_name: anyOf: - type: string - type: 'null' title: Server Name description: The name of the MCP server stdio_config: anyOf: - $ref: '#/components/schemas/StdioServerConfig' - type: 'null' description: The configuration for the server (MCP 'local' client will run this command) additionalProperties: false type: object title: UpdateStdioMCPServer description: Update a Stdio MCP server letta__schemas__mcp__UpdateStreamableHTTPMCPServer: properties: server_name: anyOf: - type: string - type: 'null' title: Server Name description: The name of the MCP server server_url: anyOf: - type: string - type: 'null' title: Server Url description: The URL path for the streamable HTTP server (e.g., 'example/mcp') auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom authentication headers as key-value pairs additionalProperties: false type: object title: UpdateStreamableHTTPMCPServer description: Update a Streamable HTTP MCP server letta__schemas__mcp_server__ToolExecuteRequest: properties: args: additionalProperties: true type: object title: Args description: Arguments to pass to the tool additionalProperties: false type: object title: ToolExecuteRequest description: Request to execute a tool. letta__schemas__mcp_server__UpdateSSEMCPServer: properties: mcp_server_type: type: string const: sse title: Mcp Server Type default: sse server_url: anyOf: - type: string - type: 'null' title: Server Url description: The URL of the server auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom HTTP headers to include with requests additionalProperties: false type: object required: - server_url title: UpdateSSEMCPServer description: Update schema for SSE MCP server - all fields optional letta__schemas__mcp_server__UpdateStdioMCPServer: properties: mcp_server_type: type: string const: stdio title: Mcp Server Type default: stdio command: anyOf: - type: string - type: 'null' title: Command description: The command to run (MCP 'local' client will run this command) args: anyOf: - items: type: string type: array - type: 'null' title: Args description: The arguments to pass to the command env: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Env description: Environment variables to set additionalProperties: false type: object required: - command - args title: UpdateStdioMCPServer description: Update schema for Stdio MCP server - all fields optional letta__schemas__mcp_server__UpdateStreamableHTTPMCPServer: properties: mcp_server_type: type: string const: streamable_http title: Mcp Server Type default: streamable_http server_url: anyOf: - type: string - type: 'null' title: Server Url description: The URL of the server auth_header: anyOf: - type: string - type: 'null' title: Auth Header description: The name of the authentication header (e.g., 'Authorization') auth_token: anyOf: - type: string - type: 'null' title: Auth Token description: The authentication token or API key value custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom HTTP headers to include with requests additionalProperties: false type: object required: - server_url title: UpdateStreamableHTTPMCPServer description: Update schema for Streamable HTTP MCP server - all fields optional letta__schemas__message__ToolReturn-Input: properties: tool_call_id: anyOf: - {} - type: 'null' title: Tool Call Id description: The ID for the tool call status: type: string enum: - success - error title: Status description: The status of the tool call stdout: anyOf: - items: type: string type: array - type: 'null' title: Stdout description: Captured stdout (e.g. prints, logs) from the tool invocation stderr: anyOf: - items: type: string type: array - type: 'null' title: Stderr description: Captured stderr from the tool invocation func_response: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' text: '#/components/schemas/TextContent' type: array - type: 'null' title: Func Response description: The function response - either a string or list of content parts (text/image) type: object required: - status title: ToolReturn letta__schemas__message__ToolReturn-Output: properties: tool_call_id: anyOf: - {} - type: 'null' title: Tool Call Id description: The ID for the tool call status: type: string enum: - success - error title: Status description: The status of the tool call stdout: anyOf: - items: type: string type: array - type: 'null' title: Stdout description: Captured stdout (e.g. prints, logs) from the tool invocation stderr: anyOf: - items: type: string type: array - type: 'null' title: Stderr description: Captured stderr from the tool invocation func_response: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' text: '#/components/schemas/TextContent' type: array - type: 'null' title: Func Response description: The function response - either a string or list of content parts (text/image) type: object required: - status title: ToolReturn letta__schemas__openai__chat_completion_response__ChatCompletionTokenLogprob: properties: token: type: string title: Token bytes: anyOf: - items: type: integer type: array - type: 'null' title: Bytes logprob: type: number title: Logprob top_logprobs: items: $ref: '#/components/schemas/letta__schemas__openai__chat_completion_response__TopLogprob' type: array title: Top Logprobs type: object required: - token - logprob - top_logprobs title: ChatCompletionTokenLogprob letta__schemas__openai__chat_completion_response__ChoiceLogprobs: properties: content: anyOf: - items: $ref: '#/components/schemas/letta__schemas__openai__chat_completion_response__ChatCompletionTokenLogprob' type: array - type: 'null' title: Content refusal: anyOf: - items: $ref: '#/components/schemas/letta__schemas__openai__chat_completion_response__ChatCompletionTokenLogprob' type: array - type: 'null' title: Refusal type: object title: ChoiceLogprobs letta__schemas__openai__chat_completion_response__TopLogprob: properties: token: type: string title: Token bytes: anyOf: - items: type: integer type: array - type: 'null' title: Bytes logprob: type: number title: Logprob type: object required: - token - logprob title: TopLogprob letta__serialize_schemas__pydantic_agent_schema__AgentSchema: properties: agent_type: type: string title: Agent Type core_memory: items: $ref: '#/components/schemas/CoreMemoryBlockSchema' type: array title: Core Memory created_at: type: string title: Created At description: anyOf: - type: string - type: 'null' title: Description embedding_config: $ref: '#/components/schemas/EmbeddingConfig' llm_config: $ref: '#/components/schemas/LLMConfig' message_buffer_autoclear: type: boolean title: Message Buffer Autoclear in_context_message_indices: items: type: integer type: array title: In Context Message Indices messages: items: $ref: '#/components/schemas/letta__serialize_schemas__pydantic_agent_schema__MessageSchema' type: array title: Messages metadata_: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata multi_agent_group: anyOf: - {} - type: 'null' title: Multi Agent Group name: type: string title: Name system: type: string title: System tags: items: $ref: '#/components/schemas/TagSchema' type: array title: Tags tool_exec_environment_variables: items: $ref: '#/components/schemas/ToolEnvVarSchema' type: array title: Tool Exec Environment Variables tool_rules: items: anyOf: - $ref: '#/components/schemas/BaseToolRuleSchema' - $ref: '#/components/schemas/ChildToolRuleSchema' - $ref: '#/components/schemas/MaxCountPerStepToolRuleSchema' - $ref: '#/components/schemas/ConditionalToolRuleSchema' type: array title: Tool Rules tools: items: $ref: '#/components/schemas/letta__serialize_schemas__pydantic_agent_schema__ToolSchema' type: array title: Tools updated_at: type: string title: Updated At version: type: string title: Version type: object required: - agent_type - core_memory - created_at - description - embedding_config - llm_config - message_buffer_autoclear - in_context_message_indices - messages - multi_agent_group - name - system - tags - tool_exec_environment_variables - tool_rules - tools - updated_at - version title: AgentSchema letta__serialize_schemas__pydantic_agent_schema__MessageSchema: properties: created_at: type: string title: Created At group_id: anyOf: - type: string - type: 'null' title: Group Id model: anyOf: - type: string - type: 'null' title: Model name: anyOf: - type: string - type: 'null' title: Name role: type: string title: Role content: items: $ref: '#/components/schemas/LettaMessageContentUnion' type: array title: Content tool_call_id: anyOf: - type: string - type: 'null' title: Tool Call Id tool_calls: items: {} type: array title: Tool Calls tool_returns: items: {} type: array title: Tool Returns updated_at: type: string title: Updated At type: object required: - created_at - group_id - model - name - role - content - tool_call_id - tool_calls - tool_returns - updated_at title: MessageSchema letta__serialize_schemas__pydantic_agent_schema__ToolSchema: properties: args_json_schema: anyOf: - {} - type: 'null' title: Args Json Schema created_at: type: string title: Created At description: type: string title: Description json_schema: $ref: '#/components/schemas/ToolJSONSchema' name: type: string title: Name return_char_limit: type: integer title: Return Char Limit source_code: anyOf: - type: string - type: 'null' title: Source Code source_type: type: string title: Source Type tags: items: type: string type: array title: Tags tool_type: type: string title: Tool Type updated_at: type: string title: Updated At metadata_: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata type: object required: - args_json_schema - created_at - description - json_schema - name - return_char_limit - source_code - source_type - tags - tool_type - updated_at title: ToolSchema letta__server__rest_api__routers__v1__agents__CompactionRequest: properties: compaction_settings: anyOf: - $ref: '#/components/schemas/CompactionSettings-Input' - type: 'null' description: Optional compaction settings to use for this summarization request. If not provided, the agent's default settings will be used. type: object title: CompactionRequest letta__server__rest_api__routers__v1__conversations__CompactionRequest: properties: agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: Agent ID for agent-direct mode with 'default' conversation. Use with conversation_id='default' in the URL path. compaction_settings: anyOf: - $ref: '#/components/schemas/CompactionSettings-Input' - type: 'null' description: Optional compaction settings to use for this summarization request. If not provided, the agent's default settings will be used. type: object title: CompactionRequest letta__server__rest_api__routers__v1__tools__ToolExecuteRequest: properties: args: additionalProperties: true type: object title: Args description: Arguments to pass to the tool type: object title: ToolExecuteRequest openai__types__chat__chat_completion__ChoiceLogprobs: properties: content: anyOf: - items: $ref: '#/components/schemas/openai__types__chat__chat_completion_token_logprob__ChatCompletionTokenLogprob' type: array - type: 'null' title: Content refusal: anyOf: - items: $ref: '#/components/schemas/openai__types__chat__chat_completion_token_logprob__ChatCompletionTokenLogprob' type: array - type: 'null' title: Refusal additionalProperties: true type: object title: ChoiceLogprobs description: Log probability information for the choice. openai__types__chat__chat_completion_message_function_tool_call__Function: properties: arguments: type: string title: Arguments name: type: string title: Name additionalProperties: true type: object required: - arguments - name title: Function description: The function that the model called. openai__types__chat__chat_completion_message_function_tool_call_param__Function: properties: arguments: type: string title: Arguments name: type: string title: Name type: object required: - arguments - name title: Function description: The function that the model called. openai__types__chat__chat_completion_token_logprob__ChatCompletionTokenLogprob: properties: token: type: string title: Token bytes: anyOf: - items: type: integer type: array - type: 'null' title: Bytes logprob: type: number title: Logprob top_logprobs: items: $ref: '#/components/schemas/openai__types__chat__chat_completion_token_logprob__TopLogprob' type: array title: Top Logprobs additionalProperties: true type: object required: - token - logprob - top_logprobs title: ChatCompletionTokenLogprob openai__types__chat__chat_completion_token_logprob__TopLogprob: properties: token: type: string title: Token bytes: anyOf: - items: type: integer type: array - type: 'null' title: Bytes logprob: type: number title: Logprob additionalProperties: true type: object required: - token - logprob title: TopLogprob LettaMessageUnion: oneOf: - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ReasoningMessage' - $ref: '#/components/schemas/HiddenReasoningMessage' - $ref: '#/components/schemas/ToolCallMessage' - $ref: '#/components/schemas/ToolReturnMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ApprovalRequestMessage' - $ref: '#/components/schemas/ApprovalResponseMessage' - $ref: '#/components/schemas/SummaryMessage' - $ref: '#/components/schemas/EventMessage' discriminator: propertyName: message_type mapping: system_message: '#/components/schemas/SystemMessage' user_message: '#/components/schemas/UserMessage' reasoning_message: '#/components/schemas/ReasoningMessage' hidden_reasoning_message: '#/components/schemas/HiddenReasoningMessage' tool_call_message: '#/components/schemas/ToolCallMessage' tool_return_message: '#/components/schemas/ToolReturnMessage' assistant_message: '#/components/schemas/AssistantMessage' approval_request_message: '#/components/schemas/ApprovalRequestMessage' approval_response_message: '#/components/schemas/ApprovalResponseMessage' summary_message: '#/components/schemas/SummaryMessage' event_message: '#/components/schemas/EventMessage' LettaMessageContentUnion: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContent' image: '#/components/schemas/ImageContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolCallContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' LettaAssistantMessageContentUnion: oneOf: - $ref: '#/components/schemas/TextContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContent' LettaToolReturnContentUnion: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContent' image: '#/components/schemas/ImageContent' LettaUserMessageContentUnion: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContent' image: '#/components/schemas/ImageContent' securitySchemes: bearerAuth: type: http scheme: bearer tags: - name: Internal Agents description: Internal Agents operations. - name: Internal Blocks description: Internal Blocks operations. - name: Internal Runs description: Internal Runs operations. - name: Internal Templates description: Internal Templates operations. - name: Admin description: Administrative operations (org / billing / policy). - name: Agents description: Create, list, modify, export, and delete stateful agents with memory and tools. - name: Archives description: Manage archival memory archives and passages (RAG-style long-term store). - name: Blocks description: Manage in-context memory blocks (core memory) shared across agents. - name: Chat description: Chat operations. - name: Client-Side Access Tokens description: Mint short-lived client-side access tokens for browser/mobile use. - name: Conversations description: Conversational session threads anchored to an agent. - name: Device Storage description: Per-device storage for the Letta Code SDK and ADE. - name: Embeddings description: List configured embedding models. - name: Environments description: Environment variables and configuration scoped to agents/tools. - name: Feeds description: Subscribed feeds that drive agents. - name: Folders description: Organize agents and resources into folders. - name: Groups description: Coordinate multi-agent groups (supervisor/worker, round-robin, sleep-time). - name: Health description: Service health/readiness endpoint. - name: Identities description: Map external user identities to agents and memory contexts. - name: Jobs description: Manage long-running background jobs (e.g., file ingestion). - name: LLMs description: List available LLM models and configurations. - name: MCP Servers description: Register external Model Context Protocol servers and expose their tools to agents. - name: Memory Files description: Memory-mapped file resources attached to agents. - name: Messages description: Send messages, list message history, search, and batch operations. - name: Metadata description: Service/runtime metadata. - name: Models description: List available chat and embedding models exposed by configured providers. - name: Passages description: Individual archival memory passages (chunked context). - name: Pipelines description: Composable agent pipelines. - name: Projects description: Project-level scoping for agents and resources. - name: Providers description: Configure LLM provider credentials (OpenAI, Anthropic, Azure, Ollama, etc.). - name: Runs description: Inspect and manage agent runs (executions of an agent in response to a message). - name: Sandboxes description: Manage code-execution sandboxes used by sandbox tools. - name: Scheduled Messages description: Schedule one-time or recurring messages to drive agents over time. - name: Sources description: Manage data sources (files, URLs) used to populate agent archival memory. - name: Steps description: Per-step traces of an agent run. - name: Tag description: Tag-based filtering metadata. - name: Telemetry description: Run-step traces and observability data. - name: Templates description: Reusable agent templates for instantiation. - name: Tools description: Register and execute custom tools (sandboxed Python, client-side, MCP). - name: Voice description: Voice (low-latency) chat completions endpoint for agents.