---
title: "Create Message"
method: POST
path: "/messages"
tags: ["Messages"]
---

# Create Message

`POST /messages`

## Request body

- CreateTaskMessageRequest
  - `task_id` string, required
  - `content` union, required
    - TextContent
      - `type` 'text' — The type of the message, in this case `text`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `format` 'markdown' | 'plain' | 'code'
      - `content` string, required — The contents of the text message.
      - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata.
        - `file_id` string, required — The unique ID of the attached file
        - `name` string, required — The name of the file
        - `size` integer, required — The size of the file in bytes
        - `type` string, required — The MIME type or content type of the file
    - ReasoningContent
      - `type` 'reasoning' — The type of the message, in this case `reasoning`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `summary` string[], required — A list of short reasoning summaries
      - `content` string[], nullable — The reasoning content or chain-of-thought text
    - DataContent
      - `type` 'data' — The type of the message, in this case `data`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `data` object, required — The contents of the data message.
    - ToolRequestContent
      - `type` 'tool_request' — The type of the message, in this case `tool_request`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `tool_call_id` string, required — The ID of the tool call that is being requested.
      - `name` string, required — The name of the tool that is being requested.
      - `arguments` object, required — The arguments to the tool.
    - ToolResponseContent
      - `type` 'tool_response' — The type of the message, in this case `tool_response`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `tool_call_id` string, required — The ID of the tool call that is being responded to.
      - `name` string, required — The name of the tool that is being responded to.
      - `content` unknown, required
      - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status.
  - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable
  - `created_at` string, date-time, nullable — Optional timestamp for the message. Workflow callers should pass workflow.now() (Temporal's deterministic monotonic clock) so that two awaited messages.create calls from the same workflow are guaranteed to have monotonic timestamps regardless of HTTP scheduling at the server. If omitted, the server's wall clock at insert time is used.

## Response `200`

Successful Response

- TaskMessage — Represents a message in the agent system. This entity is used to store messages in MongoDB, with each message associated with a specific task.
  - `id` string, nullable — The task message's unique id
  - `task_id` string, required — ID of the task this message belongs to
  - `content` union, required
    - TextContent
      - `type` 'text' — The type of the message, in this case `text`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `format` 'markdown' | 'plain' | 'code'
      - `content` string, required — The contents of the text message.
      - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata.
        - `file_id` string, required — The unique ID of the attached file
        - `name` string, required — The name of the file
        - `size` integer, required — The size of the file in bytes
        - `type` string, required — The MIME type or content type of the file
    - ReasoningContent
      - `type` 'reasoning' — The type of the message, in this case `reasoning`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `summary` string[], required — A list of short reasoning summaries
      - `content` string[], nullable — The reasoning content or chain-of-thought text
    - DataContent
      - `type` 'data' — The type of the message, in this case `data`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `data` object, required — The contents of the data message.
    - ToolRequestContent
      - `type` 'tool_request' — The type of the message, in this case `tool_request`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `tool_call_id` string, required — The ID of the tool call that is being requested.
      - `name` string, required — The name of the tool that is being requested.
      - `arguments` object, required — The arguments to the tool.
    - ToolResponseContent
      - `type` 'tool_response' — The type of the message, in this case `tool_response`.
      - `author` 'user' | 'agent', required
      - `style` 'static' | 'active'
      - `tool_call_id` string, required — The ID of the tool call that is being responded to.
      - `name` string, required — The name of the tool that is being responded to.
      - `content` unknown, required
      - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status.
  - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable
  - `created_at` string, date-time, nullable — The timestamp when the message was created
  - `updated_at` string, date-time, nullable — The timestamp when the message was last updated

## Other responses

- `422` — Validation Error

## Changes

> 55 revisions in range; 4 could not be searched.

- **2026-07-10** `fbecbdbd7dc5` — 2 info
  - added the new optional request property `content/oneOf[subschema #5: ToolResponseContent]/is_error`
  - added the optional property `content/oneOf[subschema #5: ToolResponseContent]/is_error` to the response with the `200` status
- **2026-06-23** `94d73d46952b` — 2 warning
  - removed the request property `content/oneOf[subschema #5: ToolResponseContent]/is_error`
  - removed the optional property `content/oneOf[subschema #5: ToolResponseContent]/is_error` from the response with the `200` status
- **2026-06-22** `28b893025743` — 2 info
  - added the new optional request property `content/oneOf[subschema #5: ToolResponseContent]/is_error`
  - added the optional property `content/oneOf[subschema #5: ToolResponseContent]/is_error` to the response with the `200` status
- **2026-05-13** `dd15bb3a3624` — 1 info
  - added the new optional request property `created_at`

[Change history](https://skmtc.dev/scaleapi/apis/agentex-api/changes/messages/post.md)

---

[API](https://skmtc.dev/scaleapi/apis/agentex-api.md) · [All operations](https://skmtc.dev/scaleapi/apis/agentex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scaleapi/agentex-api/revisions/1e0aaafd5780/schema)