{ "openapi": "3.1.0", "info": { "title": "Letta API", "version": "1.0.0" }, "servers": [ { "url": "https://app.letta.com", "description": "Letta Cloud" }, { "url": "http://localhost:8283", "description": "Self-hosted" } ], "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.\n\nThis 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/{passage_id}": { "delete": { "tags": ["archives"], "summary": "Delete Passage From Archive", "description": "Delete a passage from an archive.\n\nThis 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.\n\nRequires tool embedding to be enabled (embed_tools=True). Uses vector search,\nfull-text search, or hybrid mode to find tools matching the query.\n\nReturns 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:\n1. Fetching current tools from the MCP server\n2. Deleting tools that no longer exist on the server\n3. Updating schemas for existing tools\n4. Adding new tools from the server\n\nReturns 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.\nReturns 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.\nReturns 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.\nReturns 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/{session_id}": { "get": { "tags": ["tools"], "summary": "Mcp Oauth Callback", "description": "Handle OAuth callback for MCP server authentication.", "operationId": "mcp_oauth_callback", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "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.\n\nReturns structured metadata including:\n- Total number of sources\n- Total number of files across all sources\n- Total size of all files\n- 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.\n\n\nGet 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.\n\nReturns structured metadata including:\n- Total number of folders\n- Total number of files across all folders\n- Total size of all files\n- 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", "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." } ], "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.\nSupports 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." } ], "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 } ], "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" } } } } } } }, "/v1/agents/import": { "post": { "tags": ["agents"], "summary": "Import Agent", "description": "Import a serialized agent file and recreate the agent(s) in the system.\nReturns 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-'" } ], "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.\n\nAccepts 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.\n\nThis endpoint executes a tool that is attached to the agent, using the agent's\nstate 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.\n\nThis endpoint updates the file state for the agent so that no files are marked as open.\nTypically 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.\n\nThis endpoint marks a specific file as open in the agent's file state.\nThe file will be included in the agent's working memory view.\nReturns 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.\n\nThis endpoint marks a specific file as closed in the agent's file state.\nThe 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.\nThis 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}/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", "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": "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", "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/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.\n\nThis endpoint allows manual triggering of archival memory searches, enabling users to query\nan agent's archival memory store directly via the API. The search uses the same functionality\nas the agent's archival_memory_search tool but is accessible for external API usage.", "operationId": "search_archival_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-'" }, { "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", "deprecated": true, "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." } ], "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.\nThis endpoint accepts a message from a user and processes it through the agent.\n\nThe response format is controlled by the `streaming` field in the request body:\n- If `streaming=false` (default): Returns a complete LettaResponse with all messages\n- If `streaming=true`: Returns a Server-Sent Events (SSE) stream\n\nAdditional streaming options (only used when streaming=true):\n- `stream_tokens`: Stream individual tokens instead of complete steps\n- `include_pings`: Include keepalive pings to prevent connection timeouts\n- `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.", "operationId": "modify_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-'" }, { "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": "#/components/schemas/SummaryMessage", "event": "#/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.\n\nDeprecated: Use the `POST /{agent_id}/messages` endpoint with `streaming=true` in the request body instead.\n\nThis endpoint accepts a message from a user and processes it through the agent.\nIt 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.\n\nNote 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/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.\n\nThis 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.\nThe actual processing happens in the background, and the status can be checked using the run ID.\n\nThis is \"asynchronous\" in the sense that it's a background run and explicitly must be fetched by the run ID.", "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.\n\nThis endpoint processes the message through the agent loop up until\nthe LLM request, then returns the raw request payload that would\nbe 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/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.", "operationId": "list_conversations", "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The agent ID to list conversations for", "title": "Agent Id" }, "description": "The agent ID to list conversations for" }, { "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)" } ], "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" } } } } } } }, "/v1/conversations/{conversation_id}/messages": { "get": { "tags": ["conversations"], "summary": "List Conversation Messages", "description": "List all messages in a conversation.\n\nReturns LettaMessage objects (UserMessage, AssistantMessage, etc.) for all\nmessages in the conversation, ordered by position (oldest first),\nwith support for cursor-based pagination.", "operationId": "list_conversation_messages", "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-'" }, { "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 conversation", "title": "Before" }, "description": "Message ID cursor for pagination. Returns messages that come before this message ID in the conversation" }, { "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 conversation", "title": "After" }, "description": "Message ID cursor for pagination. Returns messages that come after this message ID in the conversation" }, { "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" } ], "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 streaming response.\n\nThis endpoint sends a message to an existing conversation and streams\nthe agent's response back.", "operationId": "send_conversation_message", "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/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/conversations/{conversation_id}/stream": { "post": { "tags": ["conversations"], "summary": "Retrieve Conversation Stream", "description": "Resume the stream for the most recent active run in a conversation.\n\nThis endpoint allows you to reconnect to an active background stream\nfor a conversation, enabling recovery from network interruptions.", "operationId": "retrieve_conversation_stream", "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": { "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/chat/completions": { "post": { "tags": ["chat"], "summary": "Create Chat Completion", "description": "Create a chat completion using a Letta agent (OpenAI-compatible).\n\nThis endpoint provides full OpenAI API compatibility. The agent is selected based on:\n- The 'model' parameter in the request (should contain an agent ID in format 'agent-...')\n\nWhen streaming is enabled (stream=true), the response will be Server-Sent Events\nwith 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", "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", "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", "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", "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", "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", "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": { "post": { "tags": ["groups"], "summary": "Send Group Message", "description": "Process a user message and return the group's response.\nThis endpoint accepts a message from a user and processes it through through agents in the group based on the specified pattern", "operationId": "send_group_message", "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-'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LettaRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LettaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": ["groups"], "summary": "List Group Messages", "description": "Retrieve message history for an agent.", "operationId": "list_group_messages", "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 } ], "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}/messages/stream": { "post": { "tags": ["groups"], "summary": "Send Group Message Streaming", "description": "Process a user message and return the group's responses.\nThis endpoint accepts a message from a user and processes it through agents in the group based on the specified pattern.\nIt will stream the steps of the response always, and stream the tokens if 'stream_tokens' is set to True.", "operationId": "send_group_message_streaming", "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-'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LettaStreamingRequest" } } } }, "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/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", "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": "#/components/schemas/SummaryMessage", "event": "#/components/schemas/EventMessage" } }, "title": "Response Modify Group Message" } } } }, "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", "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.\nThis will add the block to the group and all agents within the group.", "operationId": "attach_block_to_group", "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.\nThis will remove the block from the group and all agents within the group.", "operationId": "detach_block_from_group", "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", "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", "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", "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", "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", "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", "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", "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", "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", "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", "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.\nRaises 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": "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": "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.\nOptionally 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.\nDeletion 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.\n\nReturns Model format which extends LLMConfig with additional metadata fields.\nLegacy 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.\n\nReturns EmbeddingModel format which extends EmbeddingConfig with additional metadata fields.\nLegacy 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\n\nThe 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:\n1. Fetching current tools from the MCP server\n2. Deleting tools that no longer exist on the server\n3. Updating schemas for existing tools\n4. Adding new tools from the server\n\nReturns 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.\nReturns 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": "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 created by a user.", "operationId": "count_blocks", "parameters": [], "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.\nRaises 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.\n\nThis endpoint marks a job as cancelled, which will cause any associated\nagent 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": "Async health check endpoint.", "operationId": "check_health", "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/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}/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": "#/components/schemas/SummaryMessage", "event": "#/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 agent tags 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.\n\nRetrieve 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" } ], "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.\nReturns messages with FTS/vector ranks and total RRF score.\n\nThis 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.\n\nCreates a job that will fan out messages to all listed agents and process them in parallel.\nThe 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/passages/search": { "post": { "tags": ["passages"], "summary": "Search Passages", "description": "Search passages across the organization with optional agent and archive filtering.\nReturns passages with relevance scores.\n\nThis endpoint supports semantic search through passages:\n- If neither agent_id nor archive_id is provided, searches ALL passages in the organization\n- If agent_id is provided, searches passages across all archives attached to that agent\n- If archive_id is provided, searches passages within that specific archive\n- 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.\n\nThe voice functionality has been integrated into the main chat completions endpoint.\nPlease use the standard /v1/agents/{agent_id}/messages endpoint instead.\n\nThis 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"] }, "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/{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/{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/{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": ["clientSideAccessTokens"], "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": ["clientSideAccessTokens"], "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": ["clientSideAccessTokens"], "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" } }, "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"] }, "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" }, "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" }, "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" }, "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" } }, "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" }, "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": { "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 } }, "required": [ "email", "name", "organization_name", "organization_id", "current_project_name", "current_project_id" ] } } } }, "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": ["scheduledMessages"], "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": ["scheduledMessages"], "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": ["scheduledMessages"], "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": ["scheduledMessages"], "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": { "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" ] } }, "has_next_page": { "type": "boolean" }, "next_cursor": { "type": "number", "nullable": true } }, "required": ["messages", "has_next_page", "next_cursor"] } } } } } } }, "/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" }, "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", "cron_schedule", "merge_strategy", "prompt_template", "next_scheduled_at", "last_consumed_sequence", "last_consumed_at", "disabled_at", "created_at" ] } } } } } } }, "/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" }, "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", "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": { "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" }, "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", "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/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"] }, "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": { "default": 100, "type": "number" } }, "required": ["channels"] } }, "required": ["type", "data"] } ] }, "subscriber_agent_ids": { "type": "array", "items": { "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" }, "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": { "default": 100, "type": "number" } }, "required": ["channels"] } }, "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" }, "feed_name": { "type": "string" }, "subscriber_count": { "type": "number" }, "error_count": { "type": "number" } }, "required": [ "id", "name", "organization_id", "project_id", "integration_id", "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": "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" }, "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": { "default": 100, "type": "number" } }, "required": ["channels"] } }, "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" }, "feed_name": { "type": "string" }, "subscriber_count": { "type": "number" }, "error_count": { "type": "number" } }, "required": [ "id", "name", "organization_id", "project_id", "integration_id", "feed_id", "config", "next_scheduled_at", "last_run_at", "disabled_at", "created_at", "updated_at" ] } }, "hasNextPage": { "type": "boolean" } }, "required": ["pipelines", "hasNextPage"] } } } } } } }, "/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" }, "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": { "default": 100, "type": "number" } }, "required": ["channels"] } }, "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" }, "feed_name": { "type": "string" }, "subscriber_count": { "type": "number" }, "error_count": { "type": "number" } }, "required": [ "id", "name", "organization_id", "project_id", "integration_id", "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" }, "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": { "default": 100, "type": "number" } }, "required": ["channels"] } }, "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" }, "feed_name": { "type": "string" }, "subscriber_count": { "type": "number" }, "error_count": { "type": "number" } }, "required": [ "id", "name", "organization_id", "project_id", "integration_id", "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/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"] }, "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": { "default": 100, "type": "number" } }, "required": ["channels"] } }, "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"] } } } } } } } }, "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" }, "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/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" } ], "discriminator": { "propertyName": "provider_type", "mapping": { "anthropic": "#/components/schemas/AnthropicModelSettings", "azure": "#/components/schemas/AzureModelSettings", "bedrock": "#/components/schemas/BedrockModelSettings", "deepseek": "#/components/schemas/DeepseekModelSettings", "google_ai": "#/components/schemas/GoogleAIModelSettings", "google_vertex": "#/components/schemas/GoogleVertexModelSettings", "groq": "#/components/schemas/GroqModelSettings", "openai": "#/components/schemas/OpenAIModelSettings", "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": false }, "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"] }, { "type": "null" } ], "title": "Effort", "description": "Effort level for Opus 4.5 model (controls token conservation). Not setting this gives similar performance to 'high'." } }, "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" }, "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 }, "group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Id", "description": "The multi-agent group that the message was sent in" } }, "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" }, "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" }, "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\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 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": { "$ref": "#/components/schemas/EmbeddingConfig", "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", "embedding_config" ], "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.\n\nIntentionally 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).\n\nSupports 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" }, "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." }, "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.\n\nShape 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.\n[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": false }, "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" }, "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": false }, "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." }, "Block": { "properties": { "value": { "type": "string", "title": "Value", "description": "Value of the block." }, "limit": { "type": "integer", "title": "Limit", "description": "Character limit of the block.", "default": 20000 }, "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." } }, "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": 20000 }, "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." } }, "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": 20000 }, "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." }, "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." } }, "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." }, "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 }, "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\nabout 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\nmessages sent by the user. With o1 models and newer, `developer` messages\nreplace 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\nmessages sent by the user. With o1 models and newer, use `developer` messages\nfor this purpose instead." }, "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/TopLogprob" }, "type": "array", "title": "Top Logprobs" } }, "additionalProperties": true, "type": "object", "required": ["token", "logprob", "top_logprobs"], "title": "ChatCompletionTokenLogprob" }, "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\ninformation." }, "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/ChoiceLogprobs" }, { "type": "null" } ] }, "message": { "$ref": "#/components/schemas/ChatCompletionMessage" } }, "additionalProperties": true, "type": "object", "required": ["finish_reason", "index", "message"], "title": "Choice" }, "ChoiceLogprobs": { "properties": { "content": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "type": "array" }, { "type": "null" } ], "title": "Content" }, "refusal": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "type": "array" }, { "type": "null" } ], "title": "Refusal" } }, "additionalProperties": true, "type": "object", "title": "ChoiceLogprobs", "description": "Log probability information for the choice." }, "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.\n\nClient-side tools are executed by the client, not the server. When the agent\ncalls a client-side tool, execution pauses and returns control to the client\nto 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" }, "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" }, "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": { "type": "string", "title": "Model", "description": "Model handle to use for summarization (format: provider/model-name)." }, "model_settings": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/OpenAIModelSettings" }, { "$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" } ], "discriminator": { "propertyName": "provider_type", "mapping": { "anthropic": "#/components/schemas/AnthropicModelSettings", "azure": "#/components/schemas/AzureModelSettings", "bedrock": "#/components/schemas/BedrockModelSettings", "deepseek": "#/components/schemas/DeepseekModelSettings", "google_ai": "#/components/schemas/GoogleAIModelSettings", "google_vertex": "#/components/schemas/GoogleVertexModelSettings", "groq": "#/components/schemas/GroqModelSettings", "openai": "#/components/schemas/OpenAIModelSettings", "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": { "type": "string", "title": "Prompt", "description": "The prompt to use for summarization.", "default": "You have been interacting with a human user, and are in the middle of a conversation or a task. Write a summary that will allow you (or another instance of yourself) to resume without distruption, even after the conversation history is replaced with this summary. Your summary should be structured, concise, and actionable (if you are in the middle of a task). Include:\n\n1. Task or conversational overview\nThe user's core request and success criteria you are currently working on.\nAny clarifications or constraints they specified.\nAny details about the topic of messages that originated the current conversation or task.\n\n2. Current State\nWhat has been completed or discussed so far\nFiles created, modified, or analyzed (with paths if relevant)\nResources explored or referenced (with URLs if relevant)\nWhat has been discussed or explored so far with the user\n\n3. Next Steps\nThe next actions or steps you would have taken, if you were to continue the conversation or task.\n\nKeep your summary less than 100 words, do NOT exceed this word limit. Only output the summary, do NOT include anything else in your output." }, "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": 2000 }, "mode": { "type": "string", "enum": ["all", "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 mode)." } }, "type": "object", "required": ["model"], "title": "CompactionSettings", "description": "Configuration for conversation compaction / summarization.\n\n``model`` is the only required user-facing field – it specifies the summarizer\nmodel handle (e.g. ``\"openai/gpt-4o-mini\"``). Per-model settings (temperature,\nmax tokens, etc.) are derived from the default configuration for that handle." }, "CompactionSettings-Output": { "properties": { "model": { "type": "string", "title": "Model", "description": "Model handle to use for summarization (format: provider/model-name)." }, "model_settings": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/OpenAIModelSettings" }, { "$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" } ], "discriminator": { "propertyName": "provider_type", "mapping": { "anthropic": "#/components/schemas/AnthropicModelSettings", "azure": "#/components/schemas/AzureModelSettings", "bedrock": "#/components/schemas/BedrockModelSettings", "deepseek": "#/components/schemas/DeepseekModelSettings", "google_ai": "#/components/schemas/GoogleAIModelSettings", "google_vertex": "#/components/schemas/GoogleVertexModelSettings", "groq": "#/components/schemas/GroqModelSettings", "openai": "#/components/schemas/OpenAIModelSettings", "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": { "type": "string", "title": "Prompt", "description": "The prompt to use for summarization.", "default": "You have been interacting with a human user, and are in the middle of a conversation or a task. Write a summary that will allow you (or another instance of yourself) to resume without distruption, even after the conversation history is replaced with this summary. Your summary should be structured, concise, and actionable (if you are in the middle of a task). Include:\n\n1. Task or conversational overview\nThe user's core request and success criteria you are currently working on.\nAny clarifications or constraints they specified.\nAny details about the topic of messages that originated the current conversation or task.\n\n2. Current State\nWhat has been completed or discussed so far\nFiles created, modified, or analyzed (with paths if relevant)\nResources explored or referenced (with URLs if relevant)\nWhat has been discussed or explored so far with the user\n\n3. Next Steps\nThe next actions or steps you would have taken, if you were to continue the conversation or task.\n\nKeep your summary less than 100 words, do NOT exceed this word limit. Only output the summary, do NOT include anything else in your output." }, "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": 2000 }, "mode": { "type": "string", "enum": ["all", "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 mode)." } }, "type": "object", "required": ["model"], "title": "CompactionSettings", "description": "Configuration for conversation compaction / summarization.\n\n``model`` is the only required user-facing field – it specifies the summarizer\nmodel handle (e.g. ``\"openai/gpt-4o-mini\"``). Per-model settings (temperature,\nmax tokens, etc.) are derived from the default configuration for that handle." }, "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_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." } }, "additionalProperties": false, "type": "object", "required": ["id", "agent_id"], "title": "Conversation", "description": "Represents a conversation on an agent for concurrent messaging." }, "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" }, "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": "Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent.", "deprecated": true }, "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/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" } ], "discriminator": { "propertyName": "provider_type", "mapping": { "anthropic": "#/components/schemas/AnthropicModelSettings", "azure": "#/components/schemas/AzureModelSettings", "bedrock": "#/components/schemas/BedrockModelSettings", "deepseek": "#/components/schemas/DeepseekModelSettings", "google_ai": "#/components/schemas/GoogleAIModelSettings", "google_vertex": "#/components/schemas/GoogleVertexModelSettings", "groq": "#/components/schemas/GroqModelSettings", "openai": "#/components/schemas/OpenAIModelSettings", "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 } }, "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": 20000 }, "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." } }, "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." } }, "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": false }, "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", "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": "DynamicManager" }, "DynamicManagerUpdate": { "properties": { "manager_type": { "type": "string", "const": "dynamic", "title": "Manager Type", "description": "", "default": "dynamic" }, "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": "" } }, "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", "title": "Message Type", "default": "event_message" }, "otid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Otid" }, "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." }, "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": 20000 }, "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." }, "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`.\n\nThe 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`.\n\nThe 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" }, "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": false }, "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": false }, "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": false }, "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" }, "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" }, "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": "" }, "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" }, "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." }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "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": "Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent.", "deprecated": true }, "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/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" } ], "discriminator": { "propertyName": "provider_type", "mapping": { "anthropic": "#/components/schemas/AnthropicModelSettings", "azure": "#/components/schemas/AzureModelSettings", "bedrock": "#/components/schemas/BedrockModelSettings", "deepseek": "#/components/schemas/DeepseekModelSettings", "google_ai": "#/components/schemas/GoogleAIModelSettings", "google_vertex": "#/components/schemas/GoogleVertexModelSettings", "groq": "#/components/schemas/GroqModelSettings", "openai": "#/components/schemas/OpenAIModelSettings", "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" }, "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": 20000 }, "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." } }, "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" }, "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" }, "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", "mistral", "together", "bedrock", "deepseek", "xai", "zai" ], "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": 0.7 }, "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"] }, { "type": "null" } ], "title": "Effort", "description": "The effort level for Anthropic Opus 4.5 model (controls token spending). 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." } }, "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" } ] }, "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." }, "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" } ] }, "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." }, "agent_id": { "type": "string", "title": "Agent Id", "description": "The ID of the agent to send this batch request for" } }, "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." } }, "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": { "message_type": { "type": "string", "const": "ping", "title": "Message Type", "description": "The type of the message.", "default": "ping" } }, "type": "object", "required": ["message_type"], "title": "LettaPing", "description": "Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests." }, "LettaRequest": { "properties": { "messages": { "anyOf": [ { "items": { "anyOf": [ { "$ref": "#/components/schemas/MessageCreate" }, { "$ref": "#/components/schemas/ApprovalCreate" } ] }, "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." } }, "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." } }, "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" } ] }, "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." }, "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.\nEach 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." } }, "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." }, "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" }, "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" } ] }, "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" }, "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." }, "otid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Otid", "description": "The offline threading id associated with this message" }, "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" }, "group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Id", "description": "The multi-agent group that the message was sent in" } }, "type": "object", "required": ["role", "content"], "title": "MessageCreate", "description": "Request to create a message" }, "MessageRole": { "type": "string", "enum": ["assistant", "user", "tool", "function", "system", "approval"], "title": "MessageRole" }, "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" ], "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", "mistral", "together", "bedrock", "deepseek", "xai", "zai" ], "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"] }, { "type": "null" } ], "title": "Effort", "description": "The effort level for Anthropic Opus 4.5 model (controls token spending). 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." }, "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": false }, "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." } }, "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" }, "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": { "type": "string", "format": "date-time", "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." }, "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" } }, "type": "object", "required": ["text"], "title": "PassageCreateRequest", "description": "Request model for creating a passage in an archive." }, "PassageSearchRequest": { "properties": { "query": { "type": "string", "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", "required": ["query"], "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." }, "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" } }, "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 organization_id (str): The unique identifier of the organization.\n created_at (datetime): The timestamp when the object was created." }, "ProviderType": { "type": "string", "enum": [ "anthropic", "azure", "bedrock", "cerebras", "deepseek", "google_ai", "google_vertex", "groq", "hugging-face", "letta", "lmstudio_openai", "mistral", "ollama", "openai", "together", "vllm", "xai", "zai" ], "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" }, "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." }, "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.\n\nShape 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": { "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." }, "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" }, "SleeptimeManager": { "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": "SleeptimeManager" }, "SleeptimeManagerUpdate": { "properties": { "manager_type": { "type": "string", "const": "sleeptime", "title": "Manager Type", "description": "", "default": "sleeptime" }, "manager_agent_id": { "anyOf": [ { "type": "string" }, { "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_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." }, "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", "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", "title": "Message Type", "default": "summary_message" }, "otid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Otid" }, "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" } }, "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", "title": "Manager Agent Id", "description": "" } }, "type": "object", "required": ["manager_agent_id"], "title": "SupervisorManager" }, "SupervisorManagerUpdate": { "properties": { "manager_type": { "type": "string", "const": "supervisor", "title": "Manager Type", "description": "", "default": "supervisor" }, "manager_agent_id": { "anyOf": [ { "type": "string" }, { "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" }, "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." }, "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.\n\nShape 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": false }, "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.\n\nNOTE: all properties in ToolAnnotations are **hints**.\nThey are not guaranteed to provide a faithful description of\ntool behavior (including descriptive properties like `title`).\n\nClients should never make tool use decisions based on ToolAnnotations\nreceived 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" }, "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\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 (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.\n\nWhen used in a ChildToolRule, if this child is selected next, its `args` will be\napplied 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" }, "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" }, "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" }, "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" }, "UpdateAgent": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "The name of 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": "Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent.", "deprecated": true }, "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." }, "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" }, "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" }, "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/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" } ], "discriminator": { "propertyName": "provider_type", "mapping": { "anthropic": "#/components/schemas/AnthropicModelSettings", "azure": "#/components/schemas/AzureModelSettings", "bedrock": "#/components/schemas/BedrockModelSettings", "deepseek": "#/components/schemas/DeepseekModelSettings", "google_ai": "#/components/schemas/GoogleAIModelSettings", "google_vertex": "#/components/schemas/GoogleVertexModelSettings", "groq": "#/components/schemas/GroqModelSettings", "openai": "#/components/schemas/OpenAIModelSettings", "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" }, "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" }, "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." }, "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.\n\nShape is identical to UpdateUserMessage but includes the owning agent_id and message id." }, "UserUpdate": { "properties": { "id": { "type": "string", "title": "Id", "description": "The id of the user to update." }, "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", "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", "required": ["manager_agent_id"], "title": "VoiceSleeptimeManager" }, "VoiceSleeptimeManagerUpdate": { "properties": { "manager_type": { "type": "string", "const": "voice_sleeptime", "title": "Manager Type", "description": "", "default": "voice_sleeptime" }, "manager_agent_id": { "anyOf": [ { "type": "string" }, { "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": false }, "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": false }, "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." } }, "type": "object", "title": "ZAIModelSettings", "description": "Z.ai (ZhipuAI) model configuration (OpenAI-compatible)." }, "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": "Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent.", "deprecated": true }, "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/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" } ], "discriminator": { "propertyName": "provider_type", "mapping": { "anthropic": "#/components/schemas/AnthropicModelSettings", "azure": "#/components/schemas/AzureModelSettings", "bedrock": "#/components/schemas/BedrockModelSettings", "deepseek": "#/components/schemas/DeepseekModelSettings", "google_ai": "#/components/schemas/GoogleAIModelSettings", "google_vertex": "#/components/schemas/GoogleVertexModelSettings", "groq": "#/components/schemas/GroqModelSettings", "openai": "#/components/schemas/OpenAIModelSettings", "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" }, "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." }, "otid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Otid", "description": "The offline threading id associated with this message" }, "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" }, "group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Id", "description": "The multi-agent group that the message was sent in" }, "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" }, "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" } ] }, "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": { "type": "string", "title": "Tool Return" }, "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": { "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" }, { "type": "null" } ], "title": "Func Response", "description": "The function response string" } }, "type": "object", "required": ["status"], "title": "ToolReturn" }, "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__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_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." }, "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": "#/components/schemas/SummaryMessage", "event": "#/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" } } }, "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" } } } }