create_document_comments
Create one or more comments on a Polarion document in a single HTTP request. Supports top-level comments, replies, plain text or HTML, and optional resolved state and author.
Instructions
Create one or more comments on a Polarion document in a single request.
All comments in comments are sent in a single POST to
/projects/{p}/spaces/{s}/documents/{d}/comments. Polarion
returns a 201 with the IDs of all created comments.
Thread model: a comment with parent_comment_id=None is a
top-level review comment. To reply to an existing comment, set
parent_comment_id to the short ID returned in
list_document_comments (e.g. 'c42'); the tool composes the
full four-segment path proj/space/doc/c42 that the Polarion API
requires.
Text format: 'text/plain' (default) stores the body
verbatim. Use 'text/html' for HTML-formatted bodies — the HTML
is sent as-is, no sanitization.
resolved: omitting the field (None) lets Polarion default to
False; pass True to create a pre-resolved comment.
author_id: omit to have Polarion use the authenticated token's user.
This operation is NOT idempotent — retrying with the same input creates duplicate comments.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Polarion project ID. | |
| space_id | Yes | Space ID (use '_default' for the default space). | |
| document_name | Yes | Document name within ``space_id``. | |
| comments | Yes | One or more comments to create in a single request. | |
| dry_run | No | When True, return payload preview without calling Polarion. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| created | Yes | True on a real create; False on dry-run. | |
| dry_run | Yes | Whether this was a dry-run. | |
| comment_ids | Yes | Short IDs in Polarion's return order; empty on dry-run. | |
| payload_preview | Yes | JSON:API payload sent or previewed; None after real ops. |