# Messages ## List All Messages `client.messages.list(MessageListParamsquery?, RequestOptionsoptions?): MessageListResponse` **get** `/v1/messages/` List messages across all agents for the current user. ### Parameters - `query: MessageListParams` - `after?: string | null` Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-' - `before?: string | null` Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-' - `conversation_id?: string | null` Conversation ID to filter messages by - `include_return_message_types?: Array | null` Message types to include in response. When null, all message types are returned. - `"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"` - `limit?: number | null` Maximum number of messages to return - `order?: "asc" | "desc"` Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` ### Returns - `MessageListResponse = Array` - `SystemMessage` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err?: boolean | null` - `message_type?: "system_message"` The type of the message. - `"system_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `UserMessage` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: Array | string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `Array` - `TextContent` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `ImageContent` - `source: URLImage | Base64Image | LettaImage` The source of the image. - `URLImage` - `url: string` The URL of the image. - `type?: "url"` The source type for the image. - `"url"` - `Base64Image` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type?: "base64"` The source type for the image. - `"base64"` - `LettaImage` - `file_id: string` The unique identifier of the image file persisted in storage. - `data?: string | null` The base64 encoded image data. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type?: string | null` The media type for the image. - `type?: "letta"` The source type for the image. - `"letta"` - `type?: "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err?: boolean | null` - `message_type?: "user_message"` The type of the message. - `"user_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ReasoningMessage` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err?: boolean | null` - `message_type?: "reasoning_message"` The type of the message. - `"reasoning_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `signature?: string | null` - `source?: "reasoner_model" | "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id?: string | null` - `HiddenReasoningMessage` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" | "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning?: string | null` - `is_err?: boolean | null` - `message_type?: "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ToolCallMessage` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall | ToolCallDelta` - `ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `arguments?: string | null` - `name?: string | null` - `tool_call_id?: string | null` - `is_err?: boolean | null` - `message_type?: "tool_call_message"` The type of the message. - `"tool_call_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `tool_calls?: Array | ToolCallDelta | null` - `Array` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `ToolReturnMessage` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" | "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err?: boolean | null` - `message_type?: "tool_return_message"` The type of the message. - `"tool_return_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `stderr?: Array | null` - `stdout?: Array | null` - `step_id?: string | null` - `tool_returns?: Array | null` - `status: "success" | "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: Array | string` The tool return value - either a string or list of content parts (text/image) - `Array` - `TextContent` - `ImageContent` - `string` - `stderr?: Array | null` - `stdout?: Array | null` - `type?: "tool"` The message type to be created. - `"tool"` - `AssistantMessage` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: Array | string` The message content sent by the agent (can be a string or an array of content parts) - `Array` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err?: boolean | null` - `message_type?: "assistant_message"` The type of the message. - `"assistant_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall | ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall` - `ToolCallDelta` - `is_err?: boolean | null` - `message_type?: "approval_request_message"` The type of the message. - `"approval_request_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `tool_calls?: Array | ToolCallDelta | null` The tool calls that have been requested by the llm to run, which are pending approval - `Array` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `ApprovalResponseMessage` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id?: string | null` The message ID of the approval request - `approvals?: Array | null` The list of approval responses - `ApprovalReturn` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason?: string | null` An optional explanation for the provided approval status - `type?: "approval"` The message type to be created. - `"approval"` - `ToolReturn` - `status: "success" | "error"` - `tool_call_id: string` - `tool_return: Array | string` The tool return value - either a string or list of content parts (text/image) - `stderr?: Array | null` - `stdout?: Array | null` - `type?: "tool"` The message type to be created. - `approve?: boolean | null` Whether the tool has been approved - `is_err?: boolean | null` - `message_type?: "approval_response_message"` The type of the message. - `"approval_response_message"` - `name?: string | null` - `otid?: string | null` 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. - `reason?: string | null` An optional explanation for the provided approval status - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `SummaryMessage` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats?: CompactionStats | null` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after?: number | null` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before?: number | null` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err?: boolean | null` - `message_type?: "summary_message"` - `"summary_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `EventMessage` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: Record` - `event_type: "compaction"` - `"compaction"` - `is_err?: boolean | null` - `message_type?: "event_message"` - `"event_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` ### Example ```typescript import Letta from '@letta-ai/letta-client'; const client = new Letta({ apiKey: process.env['LETTA_API_KEY'], // This is the default and can be omitted }); const messages = await client.messages.list(); console.log(messages); ``` #### Response ```json [ { "id": "id", "content": "content", "date": "2019-12-27T18:11:19.117Z", "is_err": true, "message_type": "system_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id" } ] ``` ## Retrieve Message `client.messages.retrieve(stringmessageID, RequestOptionsoptions?): MessageRetrieveResponse` **get** `/v1/messages/{message_id}` Retrieve a message by ID. ### Parameters - `messageID: string` The ID of the message in the format 'message-' ### Returns - `MessageRetrieveResponse = Array` - `SystemMessage` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err?: boolean | null` - `message_type?: "system_message"` The type of the message. - `"system_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `UserMessage` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: Array | string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `Array` - `TextContent` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `ImageContent` - `source: URLImage | Base64Image | LettaImage` The source of the image. - `URLImage` - `url: string` The URL of the image. - `type?: "url"` The source type for the image. - `"url"` - `Base64Image` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type?: "base64"` The source type for the image. - `"base64"` - `LettaImage` - `file_id: string` The unique identifier of the image file persisted in storage. - `data?: string | null` The base64 encoded image data. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type?: string | null` The media type for the image. - `type?: "letta"` The source type for the image. - `"letta"` - `type?: "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err?: boolean | null` - `message_type?: "user_message"` The type of the message. - `"user_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ReasoningMessage` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err?: boolean | null` - `message_type?: "reasoning_message"` The type of the message. - `"reasoning_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `signature?: string | null` - `source?: "reasoner_model" | "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id?: string | null` - `HiddenReasoningMessage` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" | "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning?: string | null` - `is_err?: boolean | null` - `message_type?: "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ToolCallMessage` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall | ToolCallDelta` - `ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `arguments?: string | null` - `name?: string | null` - `tool_call_id?: string | null` - `is_err?: boolean | null` - `message_type?: "tool_call_message"` The type of the message. - `"tool_call_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `tool_calls?: Array | ToolCallDelta | null` - `Array` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `ToolReturnMessage` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" | "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err?: boolean | null` - `message_type?: "tool_return_message"` The type of the message. - `"tool_return_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `stderr?: Array | null` - `stdout?: Array | null` - `step_id?: string | null` - `tool_returns?: Array | null` - `status: "success" | "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: Array | string` The tool return value - either a string or list of content parts (text/image) - `Array` - `TextContent` - `ImageContent` - `string` - `stderr?: Array | null` - `stdout?: Array | null` - `type?: "tool"` The message type to be created. - `"tool"` - `AssistantMessage` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: Array | string` The message content sent by the agent (can be a string or an array of content parts) - `Array` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err?: boolean | null` - `message_type?: "assistant_message"` The type of the message. - `"assistant_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall | ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall` - `ToolCallDelta` - `is_err?: boolean | null` - `message_type?: "approval_request_message"` The type of the message. - `"approval_request_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `tool_calls?: Array | ToolCallDelta | null` The tool calls that have been requested by the llm to run, which are pending approval - `Array` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `ApprovalResponseMessage` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id?: string | null` The message ID of the approval request - `approvals?: Array | null` The list of approval responses - `ApprovalReturn` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason?: string | null` An optional explanation for the provided approval status - `type?: "approval"` The message type to be created. - `"approval"` - `ToolReturn` - `status: "success" | "error"` - `tool_call_id: string` - `tool_return: Array | string` The tool return value - either a string or list of content parts (text/image) - `stderr?: Array | null` - `stdout?: Array | null` - `type?: "tool"` The message type to be created. - `approve?: boolean | null` Whether the tool has been approved - `is_err?: boolean | null` - `message_type?: "approval_response_message"` The type of the message. - `"approval_response_message"` - `name?: string | null` - `otid?: string | null` 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. - `reason?: string | null` An optional explanation for the provided approval status - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `SummaryMessage` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats?: CompactionStats | null` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after?: number | null` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before?: number | null` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err?: boolean | null` - `message_type?: "summary_message"` - `"summary_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `EventMessage` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: Record` - `event_type: "compaction"` - `"compaction"` - `is_err?: boolean | null` - `message_type?: "event_message"` - `"event_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` ### Example ```typescript import Letta from '@letta-ai/letta-client'; const client = new Letta({ apiKey: process.env['LETTA_API_KEY'], // This is the default and can be omitted }); const messages = await client.messages.retrieve('message-123e4567-e89b-42d3-8456-426614174000'); console.log(messages); ``` #### Response ```json [ { "id": "id", "content": "content", "date": "2019-12-27T18:11:19.117Z", "is_err": true, "message_type": "system_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id" } ] ``` ## Search All Messages `client.messages.search(MessageSearchParamsbody, RequestOptionsoptions?): MessageSearchResponse` **post** `/v1/messages/search` 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. ### Parameters - `body: MessageSearchParams` - `query: string` Text query for full-text search - `agent_id?: string | null` Filter messages by agent ID - `conversation_id?: string | null` Filter messages by conversation ID - `end_date?: string | null` Filter messages created on or before this date - `limit?: number` Maximum number of results to return - `search_mode?: "vector" | "fts" | "hybrid"` Search mode to use - `"vector"` - `"fts"` - `"hybrid"` - `start_date?: string | null` Filter messages created after this date ### Returns - `MessageSearchResponse = Array` - `SystemMessageListResult` System message list result with agent context. Shape is identical to UpdateSystemMessage but includes the owning agent_id and message id. - `content: string` The message content sent by the system (can be a string or an array of multi-modal content parts) - `created_at: string` The time the message was created in ISO format. - `message_id: string` The unique identifier of the message. - `agent_id?: string | null` The unique identifier of the agent that owns the message. - `conversation_id?: string | null` The unique identifier of the conversation that the message belongs to. - `message_type?: "system_message"` - `"system_message"` - `UserMessageListResult` User message list result with agent context. Shape is identical to UpdateUserMessage but includes the owning agent_id and message id. - `content: Array | string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `Array` - `TextContent` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `ImageContent` - `source: URLImage | Base64Image | LettaImage` The source of the image. - `URLImage` - `url: string` The URL of the image. - `type?: "url"` The source type for the image. - `"url"` - `Base64Image` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type?: "base64"` The source type for the image. - `"base64"` - `LettaImage` - `file_id: string` The unique identifier of the image file persisted in storage. - `data?: string | null` The base64 encoded image data. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type?: string | null` The media type for the image. - `type?: "letta"` The source type for the image. - `"letta"` - `type?: "image"` The type of the message. - `"image"` - `string` - `created_at: string` The time the message was created in ISO format. - `message_id: string` The unique identifier of the message. - `agent_id?: string | null` The unique identifier of the agent that owns the message. - `conversation_id?: string | null` The unique identifier of the conversation that the message belongs to. - `message_type?: "user_message"` - `"user_message"` - `ReasoningMessageListResult` Reasoning message list result with agent context. Shape is identical to UpdateReasoningMessage but includes the owning agent_id and message id. - `created_at: string` The time the message was created in ISO format. - `message_id: string` The unique identifier of the message. - `reasoning: string` - `agent_id?: string | null` The unique identifier of the agent that owns the message. - `conversation_id?: string | null` The unique identifier of the conversation that the message belongs to. - `message_type?: "reasoning_message"` - `"reasoning_message"` - `AssistantMessageListResult` Assistant message list result with agent context. Shape is identical to UpdateAssistantMessage but includes the owning agent_id and message id. - `content: Array | string` The message content sent by the assistant (can be a string or an array of content parts) - `Array` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `string` - `created_at: string` The time the message was created in ISO format. - `message_id: string` The unique identifier of the message. - `agent_id?: string | null` The unique identifier of the agent that owns the message. - `conversation_id?: string | null` The unique identifier of the conversation that the message belongs to. - `message_type?: "assistant_message"` - `"assistant_message"` ### Example ```typescript import Letta from '@letta-ai/letta-client'; const client = new Letta({ apiKey: process.env['LETTA_API_KEY'], // This is the default and can be omitted }); const response = await client.messages.search({ query: 'query' }); console.log(response); ``` #### Response ```json [ { "content": "content", "created_at": "2019-12-27T18:11:19.117Z", "message_id": "message_id", "agent_id": "agent_id", "conversation_id": "conversation_id", "message_type": "system_message" } ] ``` ## Domain Types ### Message Search Request - `MessageSearchRequest` - `query: string` Text query for full-text search - `agent_id?: string | null` Filter messages by agent ID - `conversation_id?: string | null` Filter messages by conversation ID - `end_date?: string | null` Filter messages created on or before this date - `limit?: number` Maximum number of results to return - `search_mode?: "vector" | "fts" | "hybrid"` Search mode to use - `"vector"` - `"fts"` - `"hybrid"` - `start_date?: string | null` Filter messages created after this date ### Message Search Result - `MessageSearchResult` Result from a message search operation with scoring details. - `embedded_text: string` The embedded content (LLM-friendly) - `message: InternalMessage` The raw message object - `id: string` The human-friendly ID of the Message - `role: MessageRole` The role of the participant. - `"assistant"` - `"user"` - `"tool"` - `"function"` - `"system"` - `"approval"` - `"summary"` - `agent_id?: string | null` The unique identifier of the agent. - `approval_request_id?: string | null` The id of the approval request if this message is associated with a tool call request. - `approvals?: Array | null` The list of approvals for this message. - `ApprovalReturn` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason?: string | null` An optional explanation for the provided approval status - `type?: "approval"` The message type to be created. - `"approval"` - `LettaSchemasMessageToolReturnOutput` - `status: "success" | "error"` The status of the tool call - `"success"` - `"error"` - `func_response?: string | Array | null` The function response - either a string or list of content parts (text/image) - `string` - `Array` - `TextContent` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `ImageContent` - `source: URLImage | Base64Image | LettaImage` The source of the image. - `URLImage` - `url: string` The URL of the image. - `type?: "url"` The source type for the image. - `"url"` - `Base64Image` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type?: "base64"` The source type for the image. - `"base64"` - `LettaImage` - `file_id: string` The unique identifier of the image file persisted in storage. - `data?: string | null` The base64 encoded image data. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type?: string | null` The media type for the image. - `type?: "letta"` The source type for the image. - `"letta"` - `type?: "image"` The type of the message. - `"image"` - `stderr?: Array | null` Captured stderr from the tool invocation - `stdout?: Array | null` Captured stdout (e.g. prints, logs) from the tool invocation - `tool_call_id?: unknown` The ID for the tool call - `approve?: boolean | null` Whether tool call is approved. - `batch_item_id?: string | null` The id of the LLMBatchItem that this message is associated with - `content?: Array | null` The content of the message. - `TextContent` - `ImageContent` - `ToolCallContent` - `id: string` A unique identifier for this specific tool call instance. - `input: Record` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this tool call. - `type?: "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type?: "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature?: string | null` A unique identifier for this reasoning step. - `type?: "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type?: "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature?: string | null` A unique identifier for this reasoning step. - `type?: "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `SummarizedReasoningContent` The style of reasoning content returned by the OpenAI Responses API - `id: string` The unique identifier for this reasoning step. - `summary: Array` Summaries of the reasoning content. - `index: number` The index of the summary part. - `text: string` The text of the summary part. - `encrypted_content?: string` The encrypted reasoning content. - `type?: "summarized_reasoning"` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `conversation_id?: string | null` The conversation this message belongs to - `created_at?: string` The timestamp when the object was created. - `created_by_id?: string | null` The id of the user that made this object. - `denial_reason?: string | null` The reason the tool call request was denied. - `group_id?: string | null` The multi-agent group that the message was sent in - `is_err?: boolean | null` Whether this message is part of an error step. Used only for debugging purposes. - `last_updated_by_id?: string | null` The id of the user that made this object. - `model?: string | null` The model used to make the function call. - `name?: string | null` For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called. - `otid?: string | null` The offline threading id associated with this message - `run_id?: string | null` The id of the run that this message was created in. - `sender_id?: string | null` The id of the sender of the message, can be an identity id or agent id - `step_id?: string | null` The id of the step that this message was created in. - `tool_call_id?: string | null` The ID of the tool call. Only applicable for role tool. - `tool_calls?: Array | null` The list of tool calls requested. Only applicable for role assistant. - `id: string` - `function: Function` The function that the model called. - `arguments: string` - `name: string` - `type: "function"` - `"function"` - `tool_returns?: Array | null` Tool execution return information for prior tool calls - `status: "success" | "error"` The status of the tool call - `"success"` - `"error"` - `func_response?: string | Array | null` The function response - either a string or list of content parts (text/image) - `string` - `Array` - `TextContent` - `ImageContent` - `stderr?: Array | null` Captured stderr from the tool invocation - `stdout?: Array | null` Captured stdout (e.g. prints, logs) from the tool invocation - `tool_call_id?: unknown` The ID for the tool call - `updated_at?: string | null` The timestamp when the object was last updated. - `rrf_score: number` Reciprocal Rank Fusion combined score - `fts_rank?: number | null` Full-text search rank position if FTS was used - `vector_rank?: number | null` Vector search rank position if vector search was used ### Message List Response - `MessageListResponse = Array` - `SystemMessage` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err?: boolean | null` - `message_type?: "system_message"` The type of the message. - `"system_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `UserMessage` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: Array | string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `Array` - `TextContent` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `ImageContent` - `source: URLImage | Base64Image | LettaImage` The source of the image. - `URLImage` - `url: string` The URL of the image. - `type?: "url"` The source type for the image. - `"url"` - `Base64Image` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type?: "base64"` The source type for the image. - `"base64"` - `LettaImage` - `file_id: string` The unique identifier of the image file persisted in storage. - `data?: string | null` The base64 encoded image data. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type?: string | null` The media type for the image. - `type?: "letta"` The source type for the image. - `"letta"` - `type?: "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err?: boolean | null` - `message_type?: "user_message"` The type of the message. - `"user_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ReasoningMessage` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err?: boolean | null` - `message_type?: "reasoning_message"` The type of the message. - `"reasoning_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `signature?: string | null` - `source?: "reasoner_model" | "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id?: string | null` - `HiddenReasoningMessage` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" | "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning?: string | null` - `is_err?: boolean | null` - `message_type?: "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ToolCallMessage` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall | ToolCallDelta` - `ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `arguments?: string | null` - `name?: string | null` - `tool_call_id?: string | null` - `is_err?: boolean | null` - `message_type?: "tool_call_message"` The type of the message. - `"tool_call_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `tool_calls?: Array | ToolCallDelta | null` - `Array` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `ToolReturnMessage` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" | "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err?: boolean | null` - `message_type?: "tool_return_message"` The type of the message. - `"tool_return_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `stderr?: Array | null` - `stdout?: Array | null` - `step_id?: string | null` - `tool_returns?: Array | null` - `status: "success" | "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: Array | string` The tool return value - either a string or list of content parts (text/image) - `Array` - `TextContent` - `ImageContent` - `string` - `stderr?: Array | null` - `stdout?: Array | null` - `type?: "tool"` The message type to be created. - `"tool"` - `AssistantMessage` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: Array | string` The message content sent by the agent (can be a string or an array of content parts) - `Array` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err?: boolean | null` - `message_type?: "assistant_message"` The type of the message. - `"assistant_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall | ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall` - `ToolCallDelta` - `is_err?: boolean | null` - `message_type?: "approval_request_message"` The type of the message. - `"approval_request_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `tool_calls?: Array | ToolCallDelta | null` The tool calls that have been requested by the llm to run, which are pending approval - `Array` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `ApprovalResponseMessage` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id?: string | null` The message ID of the approval request - `approvals?: Array | null` The list of approval responses - `ApprovalReturn` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason?: string | null` An optional explanation for the provided approval status - `type?: "approval"` The message type to be created. - `"approval"` - `ToolReturn` - `status: "success" | "error"` - `tool_call_id: string` - `tool_return: Array | string` The tool return value - either a string or list of content parts (text/image) - `stderr?: Array | null` - `stdout?: Array | null` - `type?: "tool"` The message type to be created. - `approve?: boolean | null` Whether the tool has been approved - `is_err?: boolean | null` - `message_type?: "approval_response_message"` The type of the message. - `"approval_response_message"` - `name?: string | null` - `otid?: string | null` 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. - `reason?: string | null` An optional explanation for the provided approval status - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `SummaryMessage` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats?: CompactionStats | null` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after?: number | null` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before?: number | null` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err?: boolean | null` - `message_type?: "summary_message"` - `"summary_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `EventMessage` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: Record` - `event_type: "compaction"` - `"compaction"` - `is_err?: boolean | null` - `message_type?: "event_message"` - `"event_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` ### Message Retrieve Response - `MessageRetrieveResponse = Array` - `SystemMessage` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err?: boolean | null` - `message_type?: "system_message"` The type of the message. - `"system_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `UserMessage` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: Array | string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `Array` - `TextContent` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `ImageContent` - `source: URLImage | Base64Image | LettaImage` The source of the image. - `URLImage` - `url: string` The URL of the image. - `type?: "url"` The source type for the image. - `"url"` - `Base64Image` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type?: "base64"` The source type for the image. - `"base64"` - `LettaImage` - `file_id: string` The unique identifier of the image file persisted in storage. - `data?: string | null` The base64 encoded image data. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type?: string | null` The media type for the image. - `type?: "letta"` The source type for the image. - `"letta"` - `type?: "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err?: boolean | null` - `message_type?: "user_message"` The type of the message. - `"user_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ReasoningMessage` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err?: boolean | null` - `message_type?: "reasoning_message"` The type of the message. - `"reasoning_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `signature?: string | null` - `source?: "reasoner_model" | "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id?: string | null` - `HiddenReasoningMessage` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" | "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning?: string | null` - `is_err?: boolean | null` - `message_type?: "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ToolCallMessage` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall | ToolCallDelta` - `ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `arguments?: string | null` - `name?: string | null` - `tool_call_id?: string | null` - `is_err?: boolean | null` - `message_type?: "tool_call_message"` The type of the message. - `"tool_call_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `tool_calls?: Array | ToolCallDelta | null` - `Array` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `ToolReturnMessage` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" | "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err?: boolean | null` - `message_type?: "tool_return_message"` The type of the message. - `"tool_return_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `stderr?: Array | null` - `stdout?: Array | null` - `step_id?: string | null` - `tool_returns?: Array | null` - `status: "success" | "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: Array | string` The tool return value - either a string or list of content parts (text/image) - `Array` - `TextContent` - `ImageContent` - `string` - `stderr?: Array | null` - `stdout?: Array | null` - `type?: "tool"` The message type to be created. - `"tool"` - `AssistantMessage` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: Array | string` The message content sent by the agent (can be a string or an array of content parts) - `Array` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err?: boolean | null` - `message_type?: "assistant_message"` The type of the message. - `"assistant_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall | ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall` - `ToolCallDelta` - `is_err?: boolean | null` - `message_type?: "approval_request_message"` The type of the message. - `"approval_request_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `tool_calls?: Array | ToolCallDelta | null` The tool calls that have been requested by the llm to run, which are pending approval - `Array` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta` - `ApprovalResponseMessage` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id?: string | null` The message ID of the approval request - `approvals?: Array | null` The list of approval responses - `ApprovalReturn` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason?: string | null` An optional explanation for the provided approval status - `type?: "approval"` The message type to be created. - `"approval"` - `ToolReturn` - `status: "success" | "error"` - `tool_call_id: string` - `tool_return: Array | string` The tool return value - either a string or list of content parts (text/image) - `stderr?: Array | null` - `stdout?: Array | null` - `type?: "tool"` The message type to be created. - `approve?: boolean | null` Whether the tool has been approved - `is_err?: boolean | null` - `message_type?: "approval_response_message"` The type of the message. - `"approval_response_message"` - `name?: string | null` - `otid?: string | null` 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. - `reason?: string | null` An optional explanation for the provided approval status - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `SummaryMessage` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats?: CompactionStats | null` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after?: number | null` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before?: number | null` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err?: boolean | null` - `message_type?: "summary_message"` - `"summary_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` - `EventMessage` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: Record` - `event_type: "compaction"` - `"compaction"` - `is_err?: boolean | null` - `message_type?: "event_message"` - `"event_message"` - `name?: string | null` - `otid?: string | null` 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. - `run_id?: string | null` - `sender_id?: string | null` - `seq_id?: number | null` - `step_id?: string | null` ### Message Search Response - `MessageSearchResponse = Array` - `SystemMessageListResult` System message list result with agent context. Shape is identical to UpdateSystemMessage but includes the owning agent_id and message id. - `content: string` The message content sent by the system (can be a string or an array of multi-modal content parts) - `created_at: string` The time the message was created in ISO format. - `message_id: string` The unique identifier of the message. - `agent_id?: string | null` The unique identifier of the agent that owns the message. - `conversation_id?: string | null` The unique identifier of the conversation that the message belongs to. - `message_type?: "system_message"` - `"system_message"` - `UserMessageListResult` User message list result with agent context. Shape is identical to UpdateUserMessage but includes the owning agent_id and message id. - `content: Array | string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `Array` - `TextContent` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `ImageContent` - `source: URLImage | Base64Image | LettaImage` The source of the image. - `URLImage` - `url: string` The URL of the image. - `type?: "url"` The source type for the image. - `"url"` - `Base64Image` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type?: "base64"` The source type for the image. - `"base64"` - `LettaImage` - `file_id: string` The unique identifier of the image file persisted in storage. - `data?: string | null` The base64 encoded image data. - `detail?: string | null` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type?: string | null` The media type for the image. - `type?: "letta"` The source type for the image. - `"letta"` - `type?: "image"` The type of the message. - `"image"` - `string` - `created_at: string` The time the message was created in ISO format. - `message_id: string` The unique identifier of the message. - `agent_id?: string | null` The unique identifier of the agent that owns the message. - `conversation_id?: string | null` The unique identifier of the conversation that the message belongs to. - `message_type?: "user_message"` - `"user_message"` - `ReasoningMessageListResult` Reasoning message list result with agent context. Shape is identical to UpdateReasoningMessage but includes the owning agent_id and message id. - `created_at: string` The time the message was created in ISO format. - `message_id: string` The unique identifier of the message. - `reasoning: string` - `agent_id?: string | null` The unique identifier of the agent that owns the message. - `conversation_id?: string | null` The unique identifier of the conversation that the message belongs to. - `message_type?: "reasoning_message"` - `"reasoning_message"` - `AssistantMessageListResult` Assistant message list result with agent context. Shape is identical to UpdateAssistantMessage but includes the owning agent_id and message id. - `content: Array | string` The message content sent by the assistant (can be a string or an array of content parts) - `Array` - `text: string` The text content of the message. - `signature?: string | null` Stores a unique identifier for any reasoning associated with this text content. - `type?: "text"` The type of the message. - `"text"` - `string` - `created_at: string` The time the message was created in ISO format. - `message_id: string` The unique identifier of the message. - `agent_id?: string | null` The unique identifier of the agent that owns the message. - `conversation_id?: string | null` The unique identifier of the conversation that the message belongs to. - `message_type?: "assistant_message"` - `"assistant_message"`