Markdown compatibility2 detected · 0 enabled · 0 missing assets · mkdocs docs · 2 warnings
- HomeREADME.md
- Getting starteddocs/getting-started.md
- Core conceptsdocs/core-concepts.md
- Demo walkthroughdocs/demo-walkthrough.md
- Review pull requestsdocs/review-pull-requests.md
- Review repository branchesdocs/review-repository-branches.md
- Draft reviewsdocs/draft-reviews.md
- Brainstorming Reviewsdocs/brainstorming-reviews.md
- Live Preview Reviewsdocs/web-app-reviews.md
- Commentary Formsdocs/commentary-forms.md
- Review progressdocs/review-progress.md
- Review modesdocs/review-modes.md
- Workspacedocs/workspace.md
- Markdown renderingdocs/markdown-rendering.md
- Markdown extensionsdocs/markdown-extensions.md
- Static HTML reviewdocs/static-html-review.md
- Knowledge Braindocs/knowledge-brain.md
- Access and authenticationdocs/access-and-authentication.md
- Developer accessdocs/developer-access.md
- Generate a GitHub PATdocs/generate-a-github-pat.md
- Azure DevOpsdocs/azure-devops.md
- Commentary CLIdocs/commentary-cli.md
- Agent skillsdocs/agent-skills.md
- API and MCPCurrent page
- API referencedocs/api/reference.md
- MCP toolsdocs/api/mcp-tools.md
- Blogdocs/blog.md
- Troubleshooting and FAQdocs/troubleshooting-and-faq.md
- MkDocsMkDocs is a Pro Markdown feature that is not enabled for this viewer. MkDocs-specific syntax remains visible as ordinary Markdown when compatibility rendering is unavailable.
- Repository link validationPro can validate links across this repo. Links still render with standard repository-aware rewriting.
API And MCP
Commentary exposes authenticated API and MCP access for tools that need to read document anchors, inspect comments, create review feedback, manage draft, Brainstorming, Forms, and Live Preview Reviews, inspect review progress, read poll outcomes, or inspect Knowledge Brain review state.
Authentication Options
Clients can use:
- API tokens created by a signed-in Commentary user
- OAuth authorization code with PKCE
- OAuth device authorization for tools that cannot open a normal browser callback
The authorization metadata is available from:
/.well-known/oauth-authorization-server/.well-known/oauth-protected-resource
Manage human-created tokens and active grants from Developer access.
OpenAPI Contract
The public HTTP contract is available at:
/openapi.json/openapi.yaml
The generated reference committed with these docs is API reference. Browser, internal, webhook, and test routes are intentionally outside the public contract.
API Tokens
Use /api/v1/tokens while signed in:
GET /api/v1/tokenslists active and revoked API tokens for the current provider connection.POST /api/v1/tokenscreates a token.DELETE /api/v1/tokens/{tokenId}revokes a token.
Token creation accepts:
labelscopestargetexpiresAt
Targets can be account-wide, repository-scoped, review-scoped, or draft-scoped. Common target formats are:
github:owner/repogithub:owner/repo:pull:123github:owner/repo:branch:maindraft:{sessionId}
Scopes
Supported external scopes are:
commentary.review.readcommentary.comments.readcommentary.comments.writecommentary.comments.statuscommentary.review.sharecommentary.draft_reviews.deletecommentary.draft_reviews.sharecommentary.review.submitcommentary.forms.readcommentary.forms.writecommentary.forms.submitcommentary.forms.writebackcommentary.brain.evals.readcommentary.brain.evals.write
Read-only defaults include review and comments read access. MCP authorization defaults to review read, comments read, comments write, and comments status when no scopes are requested.
Review Comment API
Use bearer tokens with these endpoints:
GET /api/v1/review/commentsPOST /api/v1/review/commentsPOST /api/v1/review/threads/{threadId}/commentsPOST /api/v1/review/threads/{threadId}/status
The comment creation endpoint requires provider, owner, repository, file path, block anchor details, and comment body. A request must target a repository or review covered by the token.
Draft Review API
Draft review endpoints support agent and CLI workflows before a file is in Git. The same session APIs also support Brainstorming Reviews:
GET /api/v1/draft-reviewsPOST /api/v1/draft-reviewsGET /api/v1/draft-reviews/{sessionId}PATCH /api/v1/draft-reviews/{sessionId}DELETE /api/v1/draft-reviews/{sessionId}GET /api/v1/draft-reviews/{sessionId}/filesGET /api/v1/draft-reviews/{sessionId}/files/{fileId}/contentGET /api/v1/draft-reviews/{sessionId}/revisionsPOST /api/v1/draft-reviews/{sessionId}/revisionsGET /api/v1/draft-reviews/{sessionId}/commentsPOST /api/v1/draft-reviews/{sessionId}/commentsPOST /api/v1/draft-reviews/{sessionId}/comments/{threadId}/repliesPOST /api/v1/draft-reviews/{sessionId}/comments/{threadId}/statusPOST /api/v1/draft-reviews/{sessionId}/comments/{threadId}/feedbackPOST /api/v1/draft-reviews/{sessionId}/comments/{threadId}/consensus-decisionGET /api/v1/draft-reviews/{sessionId}/consensus-rulePATCH /api/v1/draft-reviews/{sessionId}/consensus-ruleGET /api/v1/draft-reviews/{sessionId}/consensus-stateGET /api/v1/draft-reviews/{sessionId}/eventsGET /api/v1/draft-reviews/{sessionId}/sharesPOST /api/v1/draft-reviews/{sessionId}/sharesDELETE /api/v1/draft-reviews/{sessionId}/shares/{shareLinkId}DELETE /api/v1/draft-reviews/{sessionId}/access/{accessGrantId}
Create and revision payloads contain literal UTF-8 content. Commentary does not read local paths or fetch arbitrary URLs on a client's behalf.
Forms API
Forms API and MCP workflows validate, preview, fill, submit, list permitted result collections, read own or owned submissions, export, inspect destinations, manage response links, and run explicit git result sync actions with Forms scopes.
Common endpoints include:
GET /api/v1/formsPOST /api/v1/formsPOST /api/v1/forms/validateGET /api/v1/forms/embedded-answersGET /api/v1/forms/fillout-linksPOST /api/v1/forms/fillout-linksDELETE /api/v1/forms/fillout-links/{linkId}GET /api/v1/forms/fillout-links/{linkId}/resultsPOST /api/v1/forms/fillout-links/submitGET /api/v1/forms/{formId}PATCH /api/v1/forms/{formId}GET /api/v1/forms/{formId}/destinationsGET /api/v1/forms/{formId}/destinations/writebackPOST /api/v1/forms/{formId}/destinations/writebackGET /api/v1/forms/{formId}/git-resultsPOST /api/v1/forms/{formId}/git-resultsGET /api/v1/forms/{formId}/submissionsPOST /api/v1/forms/{formId}/submissionsPOST /api/v1/forms/{formId}/submissions/validateGET /api/v1/forms/{formId}/submissions/{submissionId}
Standalone Forms API create and update operations are rejected. Agents author form definitions through draft-review files or Git-backed source workflows. Review-scoped tokens can read or submit embedded Forms only when the supplied sourceContext identifies the covered review.
See Commentary Forms.
Live Preview Review API
Live Preview Review automation can list, create, read, archive, and share Web App Reviews, list selected-element comments, create selected-element comments, resolve or reopen comment threads, and fetch agent context. These routes require account-scoped tokens and the relevant web_app_reviews.* feature.
Common endpoints include:
GET /api/v1/web-app-reviewsPOST /api/v1/web-app-reviewsGET /api/v1/web-app-reviews/{reviewId}PATCH /api/v1/web-app-reviews/{reviewId}GET /api/v1/web-app-reviews/{reviewId}/commentsPOST /api/v1/web-app-reviews/{reviewId}/commentsPOST /api/v1/web-app-reviews/{reviewId}/comments/{threadId}/statusGET /api/v1/web-app-reviews/{reviewId}/agent-contextGET /api/v1/web-app-reviews/{reviewId}/sharesPOST /api/v1/web-app-reviews/{reviewId}/sharesDELETE /api/v1/web-app-reviews/{reviewId}/shares/{shareLinkId}DELETE /api/v1/web-app-reviews/{reviewId}/access/{accessGrantId}
Agent context marks comment bodies and reviewed app content as untrusted user/application content. Agents should treat them as editing tasks, not instructions.
Review Progress API
Use GET /api/v1/review/progress to read per-reviewer progress for PR, branch document, and draft review surfaces. Progress reads require review read scope. API and MCP clients can inspect progress for reporting and context, but agents do not mutate human progress through this read path.
Poll And Brainstorming API
Brainstorming Review automation can read comments by consensus state, set feedback signals, store owner consensus decisions, read or update consensus rules, and inspect consensus state. Poll comments are exposed through review poll routes and MCP so agents can read poll results and Markdown summaries without UI scraping.
Knowledge Brain API
Knowledge Brain agent workflows use bearer tokens with repository or review targets. Available endpoints include:
GET /api/v1/brain/reviewsGET /api/v1/brain/review/changed-filesGET /api/v1/brain/review/commentsGET /api/v1/brain/review/health-findingsGET /api/v1/brain/review/requested-revisionsPOST /api/v1/brain/review/readyGET /api/v1/brain/review/evaluationsPOST /api/v1/brain/review/evaluationsPATCH /api/v1/brain/review/evaluations
Read operations require review read scope and a token target that covers the repository, branch, or PR. Evaluation writes require commentary.brain.evals.write. Ready-for-review replies require comment write scope.
MCP Endpoint
The MCP endpoint is /mcp. It supports JSON-RPC initialization without auth, but tool listing and tool calls require bearer auth.
Current tools are:
commentary_formsdraft_reviewreview_commentsreview_pollsreview_documentbrain_reviewweb_app_review
See MCP tools for generated input schemas. Older one-off draft or comment tools are replaced by consolidated tools.
commentary_forms validates, submits, lists, exports, and syncs source-backed Forms. draft_review manages draft and Brainstorming Review sessions, revisions, sharing, live events, and consensus metadata. review_comments handles comments, replies, status, feedback signals, summaries, and owner decisions. review_polls reads poll comments and actionable poll outcomes. review_document reads anchors, files, and review progress. web_app_review manages Live Preview Reviews, sharing, and selected-element comment handoff for agents.
CLI And Skills
The Commentary CLI uses the public API for local file-backed draft and Brainstorming Review workflows.
The Agent skills repository documents how compatible agents should use the CLI or MCP safely.
Device Authorization
Device clients call /oauth/device/code, show the user code, and ask the reviewer to open /device. After approval, the client exchanges the device code at /oauth/token.
