> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarca.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create comment

> Posts a new top-level comment on a task.

<Info>
  Requires the `comments:write` scope. Viewers cannot post comments.
  Access-restricted members receive `403` if the task belongs to a list outside
  their permitted scope.
</Info>

## Path parameters

<ParamField path="id" type="string" required>
  The numeric task ID.
</ParamField>

## Request body

<ParamField body="content" type="string" required>
  Comment text. Accepts an HTML string. Whitespace-only content is rejected with `400`.
</ParamField>

## Response

Returns the created comment. `resolved` is always `false` for a new comment.

<ResponseField name="id" type="number" required>
  New comment identifier.
</ResponseField>

<ResponseField name="task_id" type="number" required>
  ID of the task this comment belongs to.
</ResponseField>

<ResponseField name="user_id" type="number" required>
  ID of the API key owner (the commenter).
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name of the commenter.
</ResponseField>

<ResponseField name="avatar_url" type="string | null">
  Profile picture URL of the commenter.
</ResponseField>

<ResponseField name="content" type="string" required>
  Comment content.
</ResponseField>

<ResponseField name="parent_comment_id" type="null" required>
  Always `null`. Threading is not supported via the API.
</ResponseField>

<ResponseField name="resolved" type="boolean" required>
  Always `false` for newly created comments.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  UTC ISO-8601 creation timestamp.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": 172,
    "task_id": 101,
    "user_id": 1,
    "name": "Alice",
    "avatar_url": null,
    "content": "Deploying to staging tonight.",
    "parent_comment_id": null,
    "resolved": false,
    "created_at": "2026-03-18T20:00:00.000Z"
  }
  ```

  ```json 400 theme={null}
  {
    "error": "content is required"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Scope 'comments:write' is required for this endpoint"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Task not found"
  }
  ```
</ResponseExample>