Comment on a task

A comment on the card from whoever the key or session is. Everybody in mentions gets an email with it.

POST/tasks/{task}/comments

Authorization

AuthorizationBearer token · headerrequired

`MEDIAN_KEY` from Settings under API, or an MCP OAuth access token. A key acts as the organization; a token acts as the person who approved it.

Path parameters

taskstringrequired

A task key like "MED-12", its number, its id, or a link to the card.

Request body

requiredapplication/json

bodystringrequired

Plain text. Longer comments are cut.

max length 5000

mentionsstring[]

Teammates to tell, by email address or user id.

max items 20

agentstring

The coding agent writing it, like `claude-code`.

max length 40

Responses

200The comment.

idstring

400The request is malformed, and the message names the field.

errorobject

Show properties

codestring

messagestring

401The bearer token is missing, revoked, or expired.

errorobject

Show properties

codestring

messagestring

404Not one of yours, or not there at all.

errorobject

Show properties

codestring

messagestring

429Too many requests. Wait the seconds in `Retry-After`. Limits depend on the plan. See [rate limits](/api/errors-and-limits#rate-limits).

errorobject

Show properties

codestring

messagestring

Request

curl -X POST "https://api.median.sh/v1/tasks/string/comments" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Retries now back off up to an hour. Check the webhook log for MED-12 before merging.",
  "agent": "claude-code"
}'

const response = await fetch("https://api.median.sh/v1/tasks/string/comments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "body": "Retries now back off up to an hour. Check the webhook log for MED-12 before merging.",
  "agent": "claude-code"
})
});

Response

{
  "id": "string"
}