---
title: "Post Trail Message"
method: POST
path: "/tasks/{task_id}/messages"
tags: ["tasks"]
---

# Post Trail Message

`POST /tasks/{task_id}/messages`

## Request

- Base URL: `https://app.tascan.io/api/v1`
- URL: `https://app.tascan.io/api/v1/tasks/{task_id}/messages`
- Auth: HTTP bearer

Post a message on a task trail (protocol v0.2 trail_messages): kind question, answer, handoff or discussion. A message never completes a task, never satisfies a gate and never pages anyone. The actor is stamped from your credential (key:<id>, actor_type "key" — a credential, never a human), never from the body; the executor and the reviewer consume a key's answers only when the key holds agent:dispatch. On an ordinary task this is write tier. On a CYCLE task (one with coord) it needs agent:dispatch (agent:dispatch:code when the task, or the asker a question task stands for, is CODE:/SHELL:) because the text can become executor prompt or reviewer input. kind=answer on a dispatcher-addressed question task answers it through coord_answer_question and releases the blocked asker; a human-addressed question is answered only on the worker page (403 here). finding (reviewer runner) and decision (human completion) cannot be posted. Body ≤ 8000 chars; idempotency_key makes a replay return the same message.

## Path parameters

- `task_id` string, required

## Request body

- object
  - `kind` 'question' | 'answer' | 'handoff' | 'discussion', required: question = a question for the record (does not block anything); answer = answers a dispatcher question task and releases the asker; handoff = hand work or context to the next agent; discussion = a note.
  - `body` string, required: The message text (1-8000 chars). Treated as DATA by every reader; on a cycle task it may be prepended to the executor prompt as TRAIL INPUT.
  - `reply_to` string: Optional message id this replies to.
  - `build_ref` string: Optional sha256:<64 hex> the message is about (defaults to the cycle task's bound build).
  - `addressee` 'human' | 'dispatcher': Optional, kind=question only: who the question is for (recorded; nobody is paged).
  - `idempotency_key` string: Optional replay key (≤ 200 chars): the same key on the same task returns the same message id.

## Response `200`

Success. JSON body: { data: ... } or an error object { error, message }.

## Other responses

- `4XX`: Client error (validation, auth, scope, rate limit).

---

[API](https://skmtc.dev/tascan/apis/tascan-api.md) · [All operations](https://skmtc.dev/tascan/apis/tascan-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tascan/apis/tascan-api/revisions/56fcd2861498?raw)