---
title: "Modify Message"
method: PATCH
path: "/v1/agents/{agent_id}/messages/{message_id}"
tags: ["agents"]
---

# Modify Message

`PATCH /v1/agents/{agent_id}/messages/{message_id}`

Update the details of a message associated with an agent.

## Path parameters

- `agent_id` string, required
- `message_id` string, required

## Request body

- union
  - UpdateSystemMessage
    - `message_type` 'system_message'
    - `content` string, required — The message content sent by the system (can be a string or an array of multi-modal content parts)
  - UpdateUserMessage
    - `message_type` 'user_message'
    - `content` union, required — The message content sent by the user (can be a string or an array of multi-modal content parts)
      - LettaUserMessageContentUnion[]
        - union
          - TextContent
            - `type` 'text' — The type of the message.
            - `text` string, required — The text content of the message.
            - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this text content.
          - ImageContent
            - `type` 'image' — The type of the message.
            - `source` union, required — The source of the image.
              - …
      - string
  - UpdateReasoningMessage
    - `reasoning` string, required
    - `message_type` 'reasoning_message'
  - UpdateAssistantMessage
    - `message_type` 'assistant_message'
    - `content` union, required — The message content sent by the assistant (can be a string or an array of content parts)
      - LettaAssistantMessageContentUnion[]
        - `type` 'text' — The type of the message.
        - `text` string, required — The text content of the message.
        - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this text content.
      - string

## Response `200`

Successful Response

- union
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'system_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `content` string, required — The message content sent by the system
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'user_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `content` union, required — The message content sent by the user (can be a string or an array of multi-modal content parts)
      - LettaUserMessageContentUnion[]
        - union
          - TextContent
            - `type` 'text' — The type of the message.
            - `text` string, required — The text content of the message.
            - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this text content.
          - ImageContent
            - `type` 'image' — The type of the message.
            - `source` union, required — The source of the image.
              - …
      - string
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'reasoning_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `source` 'reasoner_model' | 'non_reasoner_model'
    - `reasoning` string, required
    - `signature` string, nullable
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'hidden_reasoning_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `state` 'redacted' | 'omitted', required
    - `hidden_reasoning` string, nullable
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'tool_call_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `tool_call` union, required
      - ToolCall
        - `name` string, required
        - `arguments` string, required
        - `tool_call_id` string, required
      - ToolCallDelta
        - `name` string, nullable
        - `arguments` string, nullable
        - `tool_call_id` string, nullable
    - `tool_calls` union
      - ToolCall[]
        - `name` string, required
        - `arguments` string, required
        - `tool_call_id` string, required
      - ToolCallDelta
        - `name` string, nullable
        - `arguments` string, nullable
        - `tool_call_id` string, nullable
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'tool_return_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `tool_return` string, required
    - `status` 'success' | 'error', required
    - `tool_call_id` string, required
    - `stdout` string[], nullable
    - `stderr` string[], nullable
    - `tool_returns` LettaSchemasLettaMessageToolReturn[], nullable
      - `tool_return` string, required
      - `status` 'success' | 'error', required
      - `tool_call_id` string, required
      - `stdout` string[], nullable
      - `stderr` string[], nullable
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'assistant_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `content` union, required — The message content sent by the agent (can be a string or an array of content parts)
      - LettaAssistantMessageContentUnion[]
        - `type` 'text' — The type of the message.
        - `text` string, required — The text content of the message.
        - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this text content.
      - string
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'approval_request_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `tool_call` union, required — The tool call that has been requested by the llm to run
      - ToolCall
        - `name` string, required
        - `arguments` string, required
        - `tool_call_id` string, required
      - ToolCallDelta
        - `name` string, nullable
        - `arguments` string, nullable
        - `tool_call_id` string, nullable
  - 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, required
    - `date` string, date-time, required
    - `name` string, nullable
    - `message_type` 'approval_response_message' — The type of the message.
    - `otid` string, nullable
    - `sender_id` string, nullable
    - `step_id` string, nullable
    - `is_err` boolean, nullable
    - `seq_id` integer, nullable
    - `run_id` string, nullable
    - `approve` boolean, required — Whether the tool has been approved
    - `approval_request_id` string, required — The message ID of the approval request
    - `reason` string, nullable — An optional explanation for the provided approval status

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.net/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yu-code666/letta-api/versions/6cec99480c13/schema)