Post a comment

Adds a comment to a document, or a reply when parent_id is set.

POST /v1/documents/:id/comments

Permission

The key must be granted docs.comments.write

A key without it gets 403 insufficient_scope, with the missing permission named in details.

Needs comment access on the document, which is its own permission level in this product rather than a shade of edit.

Path parameters

Field	Type	Description
`id` required	string	The document to comment on.

Request body

Field	Type	Description
`body` required	string	The comment text.
`parent_id`	string	Makes this a reply to that comment rather than a new thread.
`anchor`	object	Where in the document it points, when it points anywhere. Passed through as the editor stores it.

Request

curl https://api.veruapis.com/v1/documents/:id/comments \
  -X POST \
  -H "Authorization: Bearer vak_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Checked against the ledger, this is right", "parent_id": "0192d001-0000-7a41-b8d2-5e9f0c3a7b41" }'

Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.

Response

Answers 201.

Field	Type	Description
`id`	string
`document_id`	string
`parent_id`	string	Set on a reply, absent on a thread's first comment.
`author_id`	string
`body`	string
`state`	string	`openresolved`
`created_at`	RFC 3339
`updated_at`	RFC 3339

{
  "data": { "id": "0192d003-0000-7a41-b8d2-5e9f0c3a7b41", "document_id": "0192a1c2-6f3e-7a41-b8d2-5e9f0c3a7b41", "parent_id": "0192d001-0000-7a41-b8d2-5e9f0c3a7b41", "author_id": "01918e4b-7c2e-7f11-b4a9-0242ac130003", "body": "Checked against the ledger, this is right", "state": "open", "created_at": "2026-09-10T09:20:00Z" },
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}

Worth knowing

parent_id makes it a reply; leave it out to start a thread. Needs comment access, which is its own permission level rather than a shade of edit.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

POST `/v1/documents/:id/comments`

Your API key Used once, never stored.

id

body parent_id