Create, edit, vote, close, reopen, or archive a poll. Decision polls also require Consensus and cannot bypass blockers.

Read as Markdown

POST /api/v1/review/polls

Create, edit, vote, close, reopen, or archive a poll. Decision polls also require Consensus and cannot bypass blockers.

Access

Use a credential with commentary.comments.write.

Provider access, workspace membership, and agent grants are enforced separately. A token does not expand access to a repository or resource. Set up developer access.

Request body

Required. Supported content types: application/json.

Field	Type	Required	Description
action	"create" · "edit" · "vote" · "clear_vote" · "close" · "reopen" · "archive"	Yes
review	object or object or object or object or object or object or object	No
threadId	string	No
commentId	string	No
pollId	string	No
poll	object	No
selectedOptionIds	array of string	No
reason	string	No

Call the endpoint

Replace path placeholders and your credential. For body operations, create request.json using the required fields above; this command does not invent resource identifiers or consent.

curl --request POST \
  'https://commentary.dev/api/v1/review/polls' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Responses

Status	Meaning	Payload
200	Authorized review state or durable mutation receipt.	object
400	Invalid request.	See response headers or body contract
401	Authentication required.	See response headers or body contract
403	Current source, workspace, role or grant authority is required.	See response headers or body contract
404	Review or exact target is unavailable.	See response headers or body contract
409	Feature paused, stale version, or conflicting retry key. Refresh before creating a new intent.	See response headers or body contract

Successful response fields

Field	Type	Required	Description
ok	true	Yes

Recover from errors

Use the returned status and error body. Correct invalid fields before retrying; reconnect or narrow the target for authentication and permission errors. For conditional writes, reload the latest version before preparing a new request. Respect rate-limit headers and retry only when the operation’s idempotency contract permits it.

Contract and related guidance

Operation ID: mutateReviewPoll. Download the OpenAPI contract for complete constraints and code generation. Browse endpoints.