openapi: 3.1.0 info: title: Letta Admin Messages API version: 1.0.0 description: REST API for Letta, the stateful agents platform. Manage agents, memory blocks, archival passages, sources, custom tools, MCP servers, multi-agent groups, runs, and streaming responses. Available as Letta Cloud (managed) at https://api.letta.com/v1 and as the self-hosted open-source server (Apache-2.0) typically run at http://localhost:8283. contact: name: Letta url: https://www.letta.com/ email: support@letta.com license: name: Apache-2.0 url: https://github.com/letta-ai/letta/blob/main/LICENSE x-logo: url: https://www.letta.com/favicon.ico servers: - url: https://api.letta.com description: Letta Cloud (managed) - url: https://app.letta.com description: Letta Cloud (app) - url: http://localhost:8283 description: Self-hosted Letta server security: - bearerAuth: [] tags: - name: Messages description: Send messages, list message history, search, and batch operations. paths: /v1/messages/: get: tags: - Messages summary: List All Messages description: List messages across all agents for the current user. operationId: list_all_messages parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first - name: conversation_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Conversation ID to filter messages by title: Conversation Id description: Conversation ID to filter messages by - name: include_return_message_types in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/MessageType' - type: 'null' description: Message types to include in response. When null, all message types are returned. title: Include Return Message Types description: Message types to include in response. When null, all message types are returned. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/LettaMessageUnion' title: Response List All Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/search: post: tags: - Messages summary: Search All Messages description: 'Search messages across the organization with optional agent filtering. Returns messages with FTS/vector ranks and total RRF score. This is a cloud-only feature.' operationId: search_all_messages parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchAllMessagesRequest' responses: '200': description: Successful Response content: application/json: schema: type: array items: oneOf: - $ref: '#/components/schemas/SystemMessageListResult' - $ref: '#/components/schemas/UserMessageListResult' - $ref: '#/components/schemas/ReasoningMessageListResult' - $ref: '#/components/schemas/AssistantMessageListResult' discriminator: propertyName: message_type mapping: system_message: '#/components/schemas/SystemMessageListResult' user_message: '#/components/schemas/UserMessageListResult' reasoning_message: '#/components/schemas/ReasoningMessageListResult' assistant_message: '#/components/schemas/AssistantMessageListResult' title: Response Search All Messages '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/batches: post: tags: - Messages summary: Create Batch description: 'Submit a batch of agent runs for asynchronous processing. Creates a job that will fan out messages to all listed agents and process them in parallel. The request will be rejected if it exceeds 256MB.' operationId: create_batch parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBatch' description: Messages and config for all agents responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchJob' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' get: tags: - Messages summary: List Batches description: List all batch runs. operationId: list_batches parameters: - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Job ID cursor for pagination. Returns jobs that come before this job ID in the specified sort order title: Before description: Job ID cursor for pagination. Returns jobs that come before this job ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Job ID cursor for pagination. Returns jobs that come after this job ID in the specified sort order title: After description: Job ID cursor for pagination. Returns jobs that come after this job ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of jobs to return default: 100 title: Limit description: Maximum number of jobs to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for jobs by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for jobs by creation time. 'asc' for oldest first, 'desc' for newest first - name: order_by in: query required: false schema: const: created_at type: string description: Field to sort by default: created_at title: Order By description: Field to sort by responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/BatchJob' title: Response List Batches '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/batches/{batch_id}: get: tags: - Messages summary: Retrieve Batch description: Retrieve the status and details of a batch run. operationId: retrieve_batch parameters: - name: batch_id in: path required: true schema: type: string title: Batch Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchJob' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/batches/{batch_id}/messages: get: tags: - Messages summary: List Messages for Batch description: Get response messages for a specific batch job. operationId: list_messages_for_batch parameters: - name: batch_id in: path required: true schema: type: string title: Batch Id - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order title: Before description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order title: After description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' description: Maximum number of messages to return default: 100 title: Limit description: Maximum number of messages to return - name: order in: query required: false schema: enum: - asc - desc type: string description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first default: desc title: Order description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first - name: order_by in: query required: false schema: const: created_at type: string description: Field to sort by default: created_at title: Order By description: Field to sort by - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter messages by agent ID title: Agent Id description: Filter messages by agent ID responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LettaBatchMessages' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/batches/{batch_id}/cancel: patch: tags: - Messages summary: Cancel Batch description: Cancel a batch run. operationId: cancel_batch parameters: - name: batch_id in: path required: true schema: type: string title: Batch Id responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/messages/{message_id}: get: tags: - Messages summary: Retrieve Message description: Retrieve a message by ID. operationId: retrieve_message parameters: - name: message_id in: path required: true schema: type: string minLength: 44 maxLength: 44 pattern: ^message-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ description: The ID of the message in the format 'message-' examples: - message-123e4567-e89b-42d3-8456-426614174000 title: Message Id description: The ID of the message in the format 'message-' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/LettaMessageUnion' title: Response Retrieve Message '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: 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 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 SystemMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: system_message title: Message Type description: The type of the message. default: system_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id content: type: string title: Content description: The message content sent by the system type: object required: - id - date - content title: SystemMessage description: "A message generated by the system. Never streamed back on a response, only used for cursor pagination.\n\nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n name (Optional[str]): The name of the sender of the message\n content (str): The message content sent by the system" CompactionStats: properties: trigger: type: string title: Trigger description: What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') context_tokens_before: anyOf: - type: integer - type: 'null' title: Context Tokens Before description: Token count before compaction (from LLM usage stats, includes full context sent to LLM) context_tokens_after: anyOf: - type: integer - type: 'null' title: Context Tokens After description: Token count after compaction (message tokens only, does not include tool definitions) context_window: type: integer title: Context Window description: The model's context window size messages_count_before: type: integer title: Messages Count Before description: Number of messages before compaction messages_count_after: type: integer title: Messages Count After description: Number of messages after compaction type: object required: - trigger - context_window - messages_count_before - messages_count_after title: CompactionStats description: Statistics about a memory compaction operation. MessageRole: type: string enum: - assistant - user - tool - function - system - approval - summary title: MessageRole 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 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 LettaBatchRequest: properties: messages: anyOf: - items: anyOf: - $ref: '#/components/schemas/MessageCreate' - $ref: '#/components/schemas/ApprovalCreate' - $ref: '#/components/schemas/ToolReturnCreate' type: array - type: 'null' title: Messages description: The messages to be sent to the agent. input: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' - $ref: '#/components/schemas/SummarizedReasoningContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' summarized_reasoning: '#/components/schemas/SummarizedReasoningContent' text: '#/components/schemas/TextContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolReturnContent' type: array - type: 'null' title: Input description: 'Syntactic sugar for a single user message. Equivalent to messages=[{''role'': ''user'', ''content'': input}].' max_steps: type: integer title: Max Steps description: Maximum number of steps the agent should take to process the request. default: 50 use_assistant_message: type: boolean title: Use Assistant Message description: Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: true deprecated: true assistant_message_tool_name: type: string title: Assistant Message Tool Name description: The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: send_message deprecated: true assistant_message_tool_kwarg: type: string title: Assistant Message Tool Kwarg description: The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. default: message deprecated: true include_return_message_types: anyOf: - items: $ref: '#/components/schemas/MessageType' type: array - type: 'null' title: Include Return Message Types description: Only return specified message types in the response. If `None` (default) returns all messages. enable_thinking: type: string title: Enable Thinking description: If set to True, enables reasoning before responses or tool calls from the agent. default: true deprecated: true client_tools: anyOf: - items: $ref: '#/components/schemas/ClientToolSchema' type: array - type: 'null' title: Client Tools description: Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. client_skills: anyOf: - items: $ref: '#/components/schemas/ClientSkillSchema' type: array - type: 'null' title: Client Skills description: Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. override_model: anyOf: - type: string - type: 'null' title: Override Model description: Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. include_compaction_messages: type: boolean title: Include Compaction Messages description: If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. default: false return_logprobs: type: boolean title: Return Logprobs description: If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). default: false top_logprobs: anyOf: - type: integer - type: 'null' title: Top Logprobs description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. return_token_ids: type: boolean title: Return Token Ids description: If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. default: false override_system: anyOf: - type: string - type: 'null' title: Override System description: Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. agent_id: type: string maxLength: 42 minLength: 42 pattern: ^agent-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ title: Agent Id description: The ID of the agent to send this batch request for examples: - agent-123e4567-e89b-42d3-8456-426614174000 type: object required: - agent_id title: LettaBatchRequest LettaBatchMessages: properties: messages: items: $ref: '#/components/schemas/Message' type: array title: Messages type: object required: - messages title: LettaBatchMessages AssistantMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: assistant_message title: Message Type description: The type of the message. default: assistant_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id content: anyOf: - items: $ref: '#/components/schemas/LettaAssistantMessageContentUnion' type: array - type: string title: Content description: The message content sent by the agent (can be a string or an array of content parts) type: object required: - id - date - content title: AssistantMessage description: "A message sent by the LLM in response to user input. Used in the LLM context.\n\nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n name (Optional[str]): The name of the sender of the message\n content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)" 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 Message: properties: created_by_id: anyOf: - type: string - type: 'null' title: Created By Id description: The id of the user that made this object. last_updated_by_id: anyOf: - type: string - type: 'null' title: Last Updated By Id description: The id of the user that made this object. created_at: type: string format: date-time title: Created At description: The timestamp when the object was created. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The timestamp when the object was last updated. id: type: string pattern: ^message-[a-fA-F0-9]{8} title: Id description: The human-friendly ID of the Message examples: - message-123e4567-e89b-12d3-a456-426614174000 agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent. model: anyOf: - type: string - type: 'null' title: Model description: The model used to make the function call. role: $ref: '#/components/schemas/MessageRole' description: The role of the participant. content: anyOf: - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' - $ref: '#/components/schemas/ToolCallContent' - $ref: '#/components/schemas/ToolReturnContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/RedactedReasoningContent' - $ref: '#/components/schemas/OmittedReasoningContent' - $ref: '#/components/schemas/SummarizedReasoningContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' omitted_reasoning: '#/components/schemas/OmittedReasoningContent' reasoning: '#/components/schemas/ReasoningContent' redacted_reasoning: '#/components/schemas/RedactedReasoningContent' summarized_reasoning: '#/components/schemas/SummarizedReasoningContent' text: '#/components/schemas/TextContent' tool_call: '#/components/schemas/ToolCallContent' tool_return: '#/components/schemas/ToolReturnContent' type: array - type: 'null' title: Content description: The content of the message. name: anyOf: - type: string - type: 'null' title: Name description: 'For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.' tool_calls: anyOf: - items: $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall-Output' type: array - type: 'null' title: Tool Calls description: The list of tool calls requested. Only applicable for role assistant. tool_call_id: anyOf: - type: string - type: 'null' title: Tool Call Id description: The ID of the tool call. Only applicable for role tool. step_id: anyOf: - type: string - type: 'null' title: Step Id description: The id of the step that this message was created in. run_id: anyOf: - type: string - type: 'null' title: Run Id description: The id of the run that this message was created in. otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id associated with this message tool_returns: anyOf: - items: $ref: '#/components/schemas/letta__schemas__message__ToolReturn-Output' type: array - type: 'null' title: Tool Returns description: Tool execution return information for prior tool calls group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in sender_id: anyOf: - type: string - type: 'null' title: Sender Id description: The id of the sender of the message, can be an identity id or agent id batch_item_id: anyOf: - type: string - type: 'null' title: Batch Item Id description: The id of the LLMBatchItem that this message is associated with conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The conversation this message belongs to is_err: anyOf: - type: boolean - type: 'null' title: Is Err description: Whether this message is part of an error step. Used only for debugging purposes. approval_request_id: anyOf: - type: string - type: 'null' title: Approval Request Id description: The id of the approval request if this message is associated with a tool call request. approve: anyOf: - type: boolean - type: 'null' title: Approve description: Whether tool call is approved. denial_reason: anyOf: - type: string - type: 'null' title: Denial Reason description: The reason the tool call request was denied. approvals: anyOf: - items: anyOf: - $ref: '#/components/schemas/ApprovalReturn' - $ref: '#/components/schemas/letta__schemas__message__ToolReturn-Output' type: array - type: 'null' title: Approvals description: The list of approvals for this message. additionalProperties: false type: object required: - role title: Message description: " Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats.\n\n Attributes:\n id (str): The unique identifier of the message.\n role (MessageRole): The role of the participant.\n text (str): The text of the message.\n user_id (str): The unique identifier of the user.\n agent_id (str): The unique identifier of the agent.\n model (str): The model used to make the function call.\n name (str): The name of the participant.\n created_at (datetime): The time the message was created.\n tool_calls (List[OpenAIToolCall,]): The list of tool calls requested.\n tool_call_id (str): The id of the tool call.\n step_id (str): The id of the step that this message was created in.\n otid (str): The offline threading id associated with this message.\n tool_returns (List[ToolReturn]): The list of tool returns requested.\n group_id (str): The multi-agent group that the message was sent in.\n sender_id (str): The id of the sender of the message, can be an identity id or agent id.\n conversation_id (str): The conversation this message belongs to.\nt" 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 JobStatus: type: string enum: - created - running - completed - failed - pending - cancelled - expired title: JobStatus description: Status of the job. ToolReturnCreate: properties: type: type: string const: tool_return title: Type description: The message type to be created. default: tool_return otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in tool_returns: items: $ref: '#/components/schemas/letta__schemas__letta_message__ToolReturn' type: array title: Tool Returns description: List of tool returns from client-side execution type: object required: - tool_returns title: ToolReturnCreate description: 'Submit tool return(s) from client-side tool execution. This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case.' UserMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: user_message title: Message Type description: The type of the message. default: user_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id content: anyOf: - items: $ref: '#/components/schemas/LettaUserMessageContentUnion' type: array - type: string title: Content description: The message content sent by the user (can be a string or an array of multi-modal content parts) type: object required: - id - date - content title: UserMessage description: "A message sent by the user. Never streamed back on a response, only used for cursor pagination.\n\nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n name (Optional[str]): The name of the sender of the message\n content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)" letta__schemas__letta_message__ToolReturn: properties: type: type: string const: tool title: Type description: The message type to be created. default: tool tool_return: anyOf: - items: $ref: '#/components/schemas/LettaToolReturnContentUnion' type: array - type: string title: Tool Return description: The tool return value - either a string or list of content parts (text/image) status: type: string enum: - success - error title: Status tool_call_id: type: string title: Tool Call Id stdout: anyOf: - items: type: string type: array - type: 'null' title: Stdout stderr: anyOf: - items: type: string type: array - type: 'null' title: Stderr type: object required: - tool_return - status - tool_call_id title: ToolReturn HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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 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 LettaUserMessageContentUnion: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContent' image: '#/components/schemas/ImageContent' 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' HiddenReasoningMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: hidden_reasoning_message title: Message Type description: The type of the message. default: hidden_reasoning_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id state: type: string enum: - redacted - omitted title: State hidden_reasoning: anyOf: - type: string - type: 'null' title: Hidden Reasoning type: object required: - id - date - state title: HiddenReasoningMessage description: "Representation of an agent's internal reasoning where reasoning content\nhas been hidden from the response.\n\nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n name (Optional[str]): The name of the sender of the message\n state (Literal[\"redacted\", \"omitted\"]): Whether the reasoning\n content was redacted by the provider or simply omitted by the API\n hidden_reasoning (Optional[str]): The internal reasoning of the agent" SystemMessageListResult: properties: message_type: type: string const: system_message title: Message Type default: system_message content: type: string title: Content description: The message content sent by the system (can be a string or an array of multi-modal content parts) message_id: type: string title: Message Id description: The unique identifier of the message. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent that owns the message. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation that the message belongs to. created_at: type: string format: date-time title: Created At description: The time the message was created in ISO format. type: object required: - content - message_id - created_at title: SystemMessageListResult description: 'System message list result with agent context. Shape is identical to UpdateSystemMessage but includes the owning agent_id and message id.' ToolReturnMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: tool_return_message title: Message Type description: The type of the message. default: tool_return_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id tool_return: type: string title: Tool Return deprecated: true status: type: string enum: - success - error title: Status deprecated: true tool_call_id: type: string title: Tool Call Id deprecated: true stdout: anyOf: - items: type: string type: array - type: 'null' title: Stdout deprecated: true stderr: anyOf: - items: type: string type: array - type: 'null' title: Stderr deprecated: true tool_returns: anyOf: - items: $ref: '#/components/schemas/letta__schemas__letta_message__ToolReturn' type: array - type: 'null' title: Tool Returns type: object required: - id - date - tool_return - status - tool_call_id title: ToolReturnMessage description: "A message representing the return value of a tool call (generated by Letta executing the requested tool).\n\nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n name (Optional[str]): The name of the sender of the message\n tool_return (str): The return value of the tool (deprecated, use tool_returns)\n status (Literal[\"success\", \"error\"]): The status of the tool call (deprecated, use tool_returns)\n tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns)\n stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns)\n stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns)\n tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support" UserMessageListResult: properties: message_type: type: string const: user_message title: Message Type default: user_message content: anyOf: - items: $ref: '#/components/schemas/LettaUserMessageContentUnion' type: array - type: string title: Content description: The message content sent by the user (can be a string or an array of multi-modal content parts) message_id: type: string title: Message Id description: The unique identifier of the message. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent that owns the message. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation that the message belongs to. created_at: type: string format: date-time title: Created At description: The time the message was created in ISO format. type: object required: - content - message_id - created_at title: UserMessageListResult description: 'User message list result with agent context. Shape is identical to UpdateUserMessage but includes the owning agent_id and message id.' 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) EventMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: event_message title: Message Type default: event_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id event_type: type: string const: compaction title: Event Type event_data: additionalProperties: true type: object title: Event Data type: object required: - id - date - event_type - event_data title: EventMessage description: A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. ToolCallMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: tool_call_message title: Message Type description: The type of the message. default: tool_call_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id tool_call: anyOf: - $ref: '#/components/schemas/ToolCall' - $ref: '#/components/schemas/ToolCallDelta' title: Tool Call deprecated: true tool_calls: anyOf: - items: $ref: '#/components/schemas/ToolCall' type: array - $ref: '#/components/schemas/ToolCallDelta' - type: 'null' title: Tool Calls type: object required: - id - date - tool_call title: ToolCallMessage description: "A message representing a request to call a tool (generated by the LLM to trigger tool execution).\n\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" MessageType: type: string enum: - system_message - user_message - assistant_message - reasoning_message - hidden_reasoning_message - tool_call_message - tool_return_message - approval_request_message - approval_response_message - summary_message - event_message title: MessageType LettaToolReturnContentUnion: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContent' image: '#/components/schemas/ImageContent' ApprovalResponseMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: approval_response_message title: Message Type description: The type of the message. default: approval_response_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id approvals: anyOf: - items: oneOf: - $ref: '#/components/schemas/ApprovalReturn' - $ref: '#/components/schemas/letta__schemas__letta_message__ToolReturn' discriminator: propertyName: type mapping: approval: '#/components/schemas/ApprovalReturn' tool: '#/components/schemas/letta__schemas__letta_message__ToolReturn' type: array - type: 'null' title: Approvals description: The list of approval responses approve: anyOf: - type: boolean - type: 'null' title: Approve description: Whether the tool has been approved deprecated: true approval_request_id: anyOf: - type: string - type: 'null' title: Approval Request Id description: The message ID of the approval request deprecated: true reason: anyOf: - type: string - type: 'null' title: Reason description: An optional explanation for the provided approval status deprecated: true type: object required: - id - date title: ApprovalResponseMessage description: "A message representing a response form the user indicating whether a tool has been approved to run.\n\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" ReasoningMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: reasoning_message title: Message Type description: The type of the message. default: reasoning_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id source: type: string enum: - reasoner_model - non_reasoner_model title: Source default: non_reasoner_model reasoning: type: string title: Reasoning signature: anyOf: - type: string - type: 'null' title: Signature type: object required: - id - date - reasoning title: ReasoningMessage description: "Representation of an agent's internal reasoning.\n\nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n name (Optional[str]): The name of the sender of the message\n source (Literal[\"reasoner_model\", \"non_reasoner_model\"]): Whether the reasoning\n content was generated natively by a reasoner model or derived via prompting\n reasoning (str): The internal reasoning of the agent\n signature (Optional[str]): The model-generated signature of the reasoning step" 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 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 ClientToolSchema: properties: name: type: string title: Name description: The name of the tool function description: anyOf: - type: string - type: 'null' title: Description description: Description of what the tool does parameters: anyOf: - additionalProperties: true type: object - type: 'null' title: Parameters description: JSON Schema for the function parameters type: object required: - name title: ClientToolSchema description: 'Schema for a client-side tool passed in the request. Client-side tools are executed by the client, not the server. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result.' SummaryMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: summary_message title: Message Type default: summary_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id summary: type: string title: Summary compaction_stats: anyOf: - $ref: '#/components/schemas/CompactionStats' - type: 'null' type: object required: - id - date - summary title: SummaryMessage description: A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. MessageCreate: properties: type: anyOf: - type: string const: message - type: 'null' title: Type description: The message type to be created. default: message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in role: type: string enum: - user - system - assistant title: Role description: The role of the participant. content: anyOf: - items: $ref: '#/components/schemas/LettaMessageContentUnion' type: array - type: string title: Content description: The content of the message. name: anyOf: - type: string - type: 'null' title: Name description: The name of the participant. sender_id: anyOf: - type: string - type: 'null' title: Sender Id description: The id of the sender of the message, can be an identity id or agent id batch_item_id: anyOf: - type: string - type: 'null' title: Batch Item Id description: The id of the LLMBatchItem that this message is associated with type: object required: - role - content title: MessageCreate description: Request to create a message 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 JobType: type: string enum: - job - run - batch title: JobType letta__schemas__message__ToolReturn-Output: properties: tool_call_id: anyOf: - {} - type: 'null' title: Tool Call Id description: The ID for the tool call status: type: string enum: - success - error title: Status description: The status of the tool call stdout: anyOf: - items: type: string type: array - type: 'null' title: Stdout description: Captured stdout (e.g. prints, logs) from the tool invocation stderr: anyOf: - items: type: string type: array - type: 'null' title: Stderr description: Captured stderr from the tool invocation func_response: anyOf: - type: string - items: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' discriminator: propertyName: type mapping: image: '#/components/schemas/ImageContent' text: '#/components/schemas/TextContent' type: array - type: 'null' title: Func Response description: The function response - either a string or list of content parts (text/image) type: object required: - status title: ToolReturn 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 ReasoningMessageListResult: properties: reasoning: type: string title: Reasoning message_type: type: string const: reasoning_message title: Message Type default: reasoning_message message_id: type: string title: Message Id description: The unique identifier of the message. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent that owns the message. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation that the message belongs to. created_at: type: string format: date-time title: Created At description: The time the message was created in ISO format. type: object required: - reasoning - message_id - created_at title: ReasoningMessageListResult description: 'Reasoning message list result with agent context. Shape is identical to UpdateReasoningMessage but includes the owning agent_id and message id.' ApprovalRequestMessage: properties: id: type: string title: Id date: type: string format: date-time title: Date name: anyOf: - type: string - type: 'null' title: Name message_type: type: string const: approval_request_message title: Message Type description: The type of the message. default: approval_request_message otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. sender_id: anyOf: - type: string - type: 'null' title: Sender Id step_id: anyOf: - type: string - type: 'null' title: Step Id is_err: anyOf: - type: boolean - type: 'null' title: Is Err seq_id: anyOf: - type: integer - type: 'null' title: Seq Id run_id: anyOf: - type: string - type: 'null' title: Run Id tool_call: anyOf: - $ref: '#/components/schemas/ToolCall' - $ref: '#/components/schemas/ToolCallDelta' title: Tool Call description: The tool call that has been requested by the llm to run deprecated: true tool_calls: anyOf: - items: $ref: '#/components/schemas/ToolCall' type: array - $ref: '#/components/schemas/ToolCallDelta' - type: 'null' title: Tool Calls description: The tool calls that have been requested by the llm to run, which are pending approval type: object required: - id - date - tool_call title: ApprovalRequestMessage description: "A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).\n\nArgs:\n id (str): The ID of the message\n date (datetime): The date the message was created in ISO format\n name (Optional[str]): The name of the sender of the message\n tool_call (ToolCall): The tool call" 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 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. 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 ClientSkillSchema: properties: name: type: string title: Name description: The name of the skill description: type: string title: Description description: Description of what the skill does location: type: string title: Location description: Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) type: object required: - name - description - location title: ClientSkillSchema description: 'Schema for a client-side skill passed in the request. Client-side skills represent environment-provided capabilities (e.g. project-scoped skills) that are not stored in the agent''s MemFS but should appear in the system prompt''s available skills section.' LettaMessageUnion: oneOf: - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ReasoningMessage' - $ref: '#/components/schemas/HiddenReasoningMessage' - $ref: '#/components/schemas/ToolCallMessage' - $ref: '#/components/schemas/ToolReturnMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ApprovalRequestMessage' - $ref: '#/components/schemas/ApprovalResponseMessage' - $ref: '#/components/schemas/SummaryMessage' - $ref: '#/components/schemas/EventMessage' discriminator: propertyName: message_type mapping: system_message: '#/components/schemas/SystemMessage' user_message: '#/components/schemas/UserMessage' reasoning_message: '#/components/schemas/ReasoningMessage' hidden_reasoning_message: '#/components/schemas/HiddenReasoningMessage' tool_call_message: '#/components/schemas/ToolCallMessage' tool_return_message: '#/components/schemas/ToolReturnMessage' assistant_message: '#/components/schemas/AssistantMessage' approval_request_message: '#/components/schemas/ApprovalRequestMessage' approval_response_message: '#/components/schemas/ApprovalResponseMessage' summary_message: '#/components/schemas/SummaryMessage' event_message: '#/components/schemas/EventMessage' LettaAssistantMessageContentUnion: oneOf: - $ref: '#/components/schemas/TextContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContent' 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 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 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. AssistantMessageListResult: properties: message_type: type: string const: assistant_message title: Message Type default: assistant_message content: anyOf: - items: $ref: '#/components/schemas/LettaAssistantMessageContentUnion' type: array - type: string title: Content description: The message content sent by the assistant (can be a string or an array of content parts) message_id: type: string title: Message Id description: The unique identifier of the message. agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The unique identifier of the agent that owns the message. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The unique identifier of the conversation that the message belongs to. created_at: type: string format: date-time title: Created At description: The time the message was created in ISO format. type: object required: - content - message_id - created_at title: AssistantMessageListResult description: 'Assistant message list result with agent context. Shape is identical to UpdateAssistantMessage but includes the owning agent_id and message id.' 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 ApprovalCreate: properties: type: type: string const: approval title: Type description: The message type to be created. default: approval otid: anyOf: - type: string - type: 'null' title: Otid description: The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. group_id: anyOf: - type: string - type: 'null' title: Group Id description: The multi-agent group that the message was sent in approvals: anyOf: - items: oneOf: - $ref: '#/components/schemas/ApprovalReturn' - $ref: '#/components/schemas/letta__schemas__letta_message__ToolReturn' discriminator: propertyName: type mapping: approval: '#/components/schemas/ApprovalReturn' tool: '#/components/schemas/letta__schemas__letta_message__ToolReturn' type: array - type: 'null' title: Approvals description: The list of approval responses approve: anyOf: - type: boolean - type: 'null' title: Approve description: Whether the tool has been approved deprecated: true approval_request_id: anyOf: - type: string - type: 'null' title: Approval Request Id description: The message ID of the approval request deprecated: true reason: anyOf: - type: string - type: 'null' title: Reason description: An optional explanation for the provided approval status deprecated: true type: object title: ApprovalCreate description: Input to approve or deny a tool call request StopReasonType: type: string enum: - end_turn - error - llm_api_error - invalid_llm_response - invalid_tool_call - max_steps - max_tokens_exceeded - no_tool_call - tool_rule - cancelled - insufficient_credits - requires_approval - context_window_overflow_in_system_prompt title: StopReasonType 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 securitySchemes: bearerAuth: type: http scheme: bearer