v4

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-13216144508.7 KB
sdk-v1

Append Message To Task

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).

post/v1/chat/tasks/{task_id}/messages

Path parameters

task_idinteger required

Request body

agent_idinteger required

Target agent's primary key. Must match the agent the presented API key is bound to and the task's agent_id.

metadataobject nullable

Free-form correlation data passed through unchanged.

Response

Successful Response

task_idinteger required

Existing task primary key.

agent_idinteger required

Agent the task is bound to.

statusstring 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_atstring 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).