---
title: "Create Document Comment"
method: POST
path: "/v1/documents/{document_id}/comments"
tags: ["Agent collaboration"]
---

# Create Document Comment

`POST /v1/documents/{document_id}/comments`

## Request

- Base URL: `https://api.corvio.ai`
- URL: `https://api.corvio.ai/v1/documents/{document_id}/comments`
- Auth: HTTP bearer

## Path parameters

- `document_id` string, uuid, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- PublicAgentCommentThreadCreateRequest
  - `body` string, required
  - `selection` object
  - `entry_point` string, nullable
  - `mention_targets` PublicAgentMentionTarget[]
    - `kind` 'user' | 'agent', required
    - `principal_id` string, uuid, required
    - `alias` string, required
  - `start_new_chain` boolean

## Response `201`

Successful Response

- PageCommentThreadResponse
  - `id` string, uuid, required
  - `page_id` string, uuid, required
  - `workspace_id` string, uuid, required
  - `status` string, required
  - `created_by_kind` string, required
  - `created_by_user_id` string, uuid, nullable
  - `created_by_agent_id` string, uuid, nullable
  - `created_at` string, date-time, required
  - `last_activity_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `anchor` PageCommentAnchorResponse, required
    - `target_scope` string
    - `section_id` string, nullable
    - `source_block_ids` string[]
    - `anchor` string, nullable
    - `heading_path` string[]
    - `quote_hash` string, nullable
    - `selection_preview` string, nullable
    - `selection_range_json` object, nullable
    - `table_selection_json` object, nullable
    - `surface_selection_json` object, nullable
    - `source_page_revision` integer, nullable
    - `resolved_block_ids` string[]
    - `resolved_via` string, nullable
    - `needs_reanchor` boolean
  - `entries` PageCommentEntryResponse[]
    - `id` string, uuid, required
    - `thread_id` string, uuid, required
    - `author_kind` string, required
    - `author_agent_id` string, uuid, nullable
    - `actor_identity` object, nullable
    - `body` string, required
    - `mentions` string[]
    - `structured_mentions` object[]
    - `user_mentions` object[]
    - `agent_mentions` object[]
    - `entry_point` string, nullable
    - `request_id` string, uuid, nullable
    - `run_id` string, nullable
    - `conversation_thread_id` string, uuid, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

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