---
title: "Append Message To Task"
method: POST
path: "/v1/chat/tasks/{task_id}/messages"
tags: ["sdk-v1"]
---

# Append Message To Task

`POST /v1/chat/tasks/{task_id}/messages`

Append the next user message to an existing task and kick off its next turn.

Phase 1 multi-turn model is task-centric: subsequent user inputs
extend the same ``task_id`` rather than creating a new task or a
new ``conversation_id``. This endpoint:

  1. Validates the path ``task_id`` exists and belongs to the
     key-bound agent (404 ``task_not_found`` otherwise).
  2. Validates ``body.agent_id`` matches the key-bound agent
     (404 ``agent_not_found`` otherwise).
  3. Rejects the call with 409 ``task_busy`` if the task is
     currently ``RUNNING`` -- the SDK client should poll
     ``GET /v1/chat/tasks/{id}`` until status leaves RUNNING and
     retry.
  4. Otherwise persists the new user message to
     ``task_chat_messages``, updates ``task.input`` to record
     this turn's input, and kicks off the next background turn
     via the same helper POST uses.

Args:
    task_id: Path parameter; the target task's primary key.
    request: Validated :class:`AppendMessageRequest`. ``message.content``
        is guaranteed non-empty by Pydantic.
    authed: ``(Agent, AgentApiKey)`` from the auth dependency.
    db: SQLAlchemy session.

Returns:
    :class:`AppendMessageResponse` with the task identity and an
    ``accepted_at`` timestamp.

Raises:
    V1ApiError 401: missing / invalid / revoked key.
    V1ApiError 404: task not found OR not owned by the agent OR
        body.agent_id doesn't match the bound agent.
    V1ApiError 409: ``task_busy`` -- task currently RUNNING.
    500: any other unexpected error (V1 envelope via global handler).

## Path parameters

- `task_id` integer, required

## Request body

- AppendMessageRequest — Body for ``POST /v1/chat/tasks/{task_id}/messages``. Same shape as :class:`CreateTaskRequest` minus the lack of a ``metadata`` field by default -- callers append a new user message to an existing task. ``agent_id`` is required again (consistent with the SDK contract: every write carries the agent_id explicitly for forward-compat with multi-agent keys).
  - `agent_id` integer, required — Target agent's primary key. Must match the agent the presented API key is bound to and the task's agent_id.
  - `message` MessageBody, required — One chat message in the SDK request body. Currently the SDK surface only accepts ``role='user'`` -- the SDK is for SaaS clients pushing user input, not for replaying transcripts. Future-proofed as a string so we don't have to break the wire shape when adding ``system`` / ``function`` later.
    - `role` 'user' — Currently must be 'user'. Reserved as a field for future expansion (system / function roles) without breaking the wire shape.
    - `content` string, required — The user's message text. Must be non-empty.
  - `metadata` object, nullable — Free-form correlation data passed through unchanged.

## Response `202`

Successful Response

- AppendMessageResponse — ``POST /v1/chat/tasks/{task_id}/messages`` -> 202 Accepted response. The new user message has been persisted and the next turn queued for background execution; callers poll the same way they would after the initial POST /v1/chat/tasks.
  - `task_id` integer, required — Existing task primary key.
  - `agent_id` integer, required — Agent the task is bound to.
  - `status` string, required — Initial status of the new turn, 'running' in the 202 response (the atomic claim inside POST commits the status flip before the response is sent).
  - `accepted_at` string, date-time, required — UTC timestamp when the server accepted the message and scheduled background execution. Not the message's stored created_at (which may differ slightly due to DB clock).

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/xorbitsai/apis/xagent.md) · [All operations](https://skmtc.net/xorbitsai/apis/xagent/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xorbitsai/xagent/revisions/33e4ba4936ad/schema)