Markdown compatibility2 detected · 0 enabled · mkdocs docs · 2 warnings
Docs project
mkdocs · Commentary API Reference · 28 section pages
<!-- Generated by npm run openapi:write. Do not edit reference.md by hand. --> # Commentary API Reference
- 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 MCPdocs/api-and-mcp.md
- API referenceCurrent page
- MCP toolsdocs/api/mcp-tools.md
- Blogdocs/blog.md
- Troubleshooting and FAQdocs/troubleshooting-and-faq.md
Pro disabled
- 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.
DocsApiReference
28 pages from docs configurationmkdocs
Commentary API Reference
This file summarizes the stable public HTTP API contract. The canonical source is src/lib/api-contract/openapi.ts; generated JSON and YAML are committed next to this file.
OpenAPI version: 3.1.0
Endpoints
| Method | Path | Operation | Auth scopes |
|---|---|---|---|
GET | /.well-known/oauth-authorization-server | Get OAuth authorization server metadata. | session/public |
GET | /.well-known/oauth-protected-resource | Get OAuth protected resource metadata. | session/public |
GET | /api/health | Get shallow, deep, storage, or PostgreSQL health. | session/public |
GET | /api/v1/brain/review/changed-files | List changed files for a Knowledge Brain review. | commentary.review.read |
GET | /api/v1/brain/review/comments | List comments for a Knowledge Brain review. | commentary.comments.read |
GET | /api/v1/brain/review/evaluations | List Knowledge Brain evaluation ledger entries. | commentary.brain.evals.read |
PATCH | /api/v1/brain/review/evaluations | Update a Knowledge Brain evaluation ledger entry. | commentary.brain.evals.write |
POST | /api/v1/brain/review/evaluations | Create a Knowledge Brain evaluation ledger entry. | commentary.brain.evals.write |
GET | /api/v1/brain/review/health-findings | List health findings for a Knowledge Brain review. | commentary.review.read |
POST | /api/v1/brain/review/ready | Mark a Knowledge Brain requested revision ready for review. | commentary.comments.write |
GET | /api/v1/brain/review/requested-revisions | List requested revisions for a Knowledge Brain review. | commentary.review.read |
GET | /api/v1/brain/reviews | List Knowledge Brain reviews available to the token. | commentary.review.read |
GET | /api/v1/draft-reviews | List draft or Brainstorming Reviews owned by the account-scoped token principal. | commentary.review.read |
POST | /api/v1/draft-reviews | Create a draft or Brainstorming Review session, optionally with initial file content. | commentary.comments.write |
DELETE | /api/v1/draft-reviews/{sessionId} | Permanently delete a draft review from active Commentary storage. | commentary.draft_reviews.delete |
GET | /api/v1/draft-reviews/{sessionId} | Get a draft review session. | commentary.review.read |
PATCH | /api/v1/draft-reviews/{sessionId} | Update draft review metadata or Git base metadata. | commentary.comments.write |
DELETE | /api/v1/draft-reviews/{sessionId}/access/{accessGrantId} | Remove a draft review access grant. | commentary.draft_reviews.share |
GET | /api/v1/draft-reviews/{sessionId}/comments | List comments for a draft review. | commentary.comments.read |
POST | /api/v1/draft-reviews/{sessionId}/comments | Create a comment thread on a draft review. | commentary.comments.write |
POST | /api/v1/draft-reviews/{sessionId}/comments/{threadId}/consensus-decision | Accept, reject, mark out of scope, or clear an owner consensus decision for a Brainstorming Review thread. In multi-agent mode, aliased owner decisions require the delegated owner agent. | commentary.comments.status |
POST | /api/v1/draft-reviews/{sessionId}/comments/{threadId}/feedback | Set or clear a Brainstorming Review feedback stance. When countAgentSignals is enabled, registered agent aliases can provide independent signals. | commentary.comments.write |
POST | /api/v1/draft-reviews/{sessionId}/comments/{threadId}/replies | Reply to a draft review comment. | commentary.comments.write |
POST | /api/v1/draft-reviews/{sessionId}/comments/{threadId}/status | Resolve or reopen a draft review comment. | commentary.comments.status |
GET | /api/v1/draft-reviews/{sessionId}/consensus-rule | Get the configured Brainstorming Review consensus rule. | commentary.review.read |
PATCH | /api/v1/draft-reviews/{sessionId}/consensus-rule | Update the Brainstorming Review consensus rule, including countAgentSignals and delegatedOwnerAgentParticipantId. Owner access is required. | commentary.comments.write |
GET | /api/v1/draft-reviews/{sessionId}/consensus-state | Get Brainstorming Review consensus counts and file readiness. | commentary.comments.read |
GET | /api/v1/draft-reviews/{sessionId}/events | Stream draft or Brainstorming Review live events using Server-Sent Events. | commentary.comments.read |
GET | /api/v1/draft-reviews/{sessionId}/files | List draft review files. | commentary.review.read |
GET | /api/v1/draft-reviews/{sessionId}/files/{fileId}/content | Download the latest content for a draft review file. | commentary.review.read |
GET | /api/v1/draft-reviews/{sessionId}/revisions | List draft review revisions. | commentary.review.read |
POST | /api/v1/draft-reviews/{sessionId}/revisions | Upload a new draft or Brainstorming Review revision from literal file content. | commentary.comments.write |
GET | /api/v1/draft-reviews/{sessionId}/shares | List share links and access grants for a draft review. | commentary.draft_reviews.share |
POST | /api/v1/draft-reviews/{sessionId}/shares | Create a draft review share link. | commentary.draft_reviews.share |
DELETE | /api/v1/draft-reviews/{sessionId}/shares/{shareLinkId} | Revoke a draft review share link. | commentary.draft_reviews.share |
GET | /api/v1/forms | List owned forms and visible result collections for the account-scoped token principal. | commentary.forms.read |
POST | /api/v1/forms | Reject standalone Forms API creation. | commentary.forms.write |
GET | /api/v1/forms/{formId} | Get a form contract and metadata. | commentary.forms.read |
PATCH | /api/v1/forms/{formId} | Reject standalone Forms API editing. | commentary.forms.write |
GET | /api/v1/forms/{formId}/destinations | List form destinations and read-only write-back status. | commentary.forms.read |
GET | /api/v1/forms/{formId}/destinations/writeback | Inspect optional GitHub writeback availability for a form target. | commentary.forms.read |
POST | /api/v1/forms/{formId}/destinations/writeback | Explicitly write a form definition or final submission to GitHub through the optional writeback app. | commentary.forms.writeback |
GET | /api/v1/forms/{formId}/git-results | List canonical git-hosted result files for a source-backed form. | commentary.forms.read |
POST | /api/v1/forms/{formId}/git-results | Preview result writeback or explicitly import canonical git-hosted result files. | commentary.forms.writeback |
GET | /api/v1/forms/{formId}/submissions | List submissions for a permitted result collection. | commentary.forms.read |
POST | /api/v1/forms/{formId}/submissions | Submit final form answers. | commentary.forms.submit |
GET | /api/v1/forms/{formId}/submissions/{submissionId} | Read or export one form submission including raw values for an authorized principal. | commentary.forms.read |
POST | /api/v1/forms/{formId}/submissions/validate | Validate form answers against the current form contract without storing a submission. | commentary.forms.submit |
GET | /api/v1/forms/embedded-answers | List embedded review form answers for an authorized result context. | commentary.forms.read |
GET | /api/v1/forms/fillout-links | List response links owned by the account-scoped token principal. | commentary.forms.read |
POST | /api/v1/forms/fillout-links | Create a response link from an accessible source-backed form. | commentary.forms.write |
DELETE | /api/v1/forms/fillout-links/{linkId} | Revoke a response link owned by the account-scoped token principal. | commentary.forms.write |
GET | /api/v1/forms/fillout-links/{linkId}/results | List result submissions owned by a response link. | commentary.forms.read |
POST | /api/v1/forms/fillout-links/submit | Submit answers through a response link. | commentary.forms.submit |
POST | /api/v1/forms/validate | Validate a literal Form Contract v1 payload without persisting it. | commentary.forms.read |
GET | /api/v1/review/comments | List review comments for a PR or branch document file. | commentary.comments.read |
POST | /api/v1/review/comments | Create a review comment thread on a PR or branch document. | commentary.comments.write |
GET | /api/v1/review/mention-notifications | List mention notifications for the current token principal. | commentary.comments.read |
POST | /api/v1/review/mention-notifications/{notificationId}/read | Mark a mention notification read for the current token principal. | commentary.comments.write |
GET | /api/v1/review/participants | List users and agents taggable in a review. | commentary.comments.read |
POST | /api/v1/review/participants | Add a taggable user or register an agent alias for the current user. | commentary.comments.write |
GET | /api/v1/review/progress | Read per-reviewer progress for a PR, branch document, or draft review. | commentary.review.read |
POST | /api/v1/review/threads/{threadId}/comments | Reply to an existing review thread. | commentary.comments.write |
POST | /api/v1/review/threads/{threadId}/status | Resolve or reopen an existing review thread. | commentary.comments.status |
GET | /api/v1/tokens | List API tokens for the signed-in provider connection. | session/public |
POST | /api/v1/tokens | Create an API token for scripts, MCP clients, or agents. | session/public |
DELETE | /api/v1/tokens/{tokenId} | Revoke an API token. | session/public |
GET | /api/v1/web-app-reviews | List Web App Reviews owned by the account-scoped token principal. | commentary.review.read |
POST | /api/v1/web-app-reviews | Create a Web App Review for a deployed or localhost preview URL. | commentary.comments.write |
GET | /api/v1/web-app-reviews/{reviewId} | Get Web App Review metadata. | commentary.review.read |
PATCH | /api/v1/web-app-reviews/{reviewId} | Update Web App Review metadata. | commentary.comments.write |
DELETE | /api/v1/web-app-reviews/{reviewId}/access/{accessGrantId} | Remove a Web App Review access grant. | commentary.review.share |
GET | /api/v1/web-app-reviews/{reviewId}/agent-context | Get Web App Review comments as actionable, untrusted agent editing tasks. | commentary.review.read |
GET | /api/v1/web-app-reviews/{reviewId}/comments | List selected-element comments for a Web App Review. | commentary.comments.read |
POST | /api/v1/web-app-reviews/{reviewId}/comments | Create a selected-element comment for a Web App Review. | commentary.comments.write |
POST | /api/v1/web-app-reviews/{reviewId}/comments/{threadId}/status | Resolve or reopen a Web App Review comment thread. | commentary.comments.status |
GET | /api/v1/web-app-reviews/{reviewId}/shares | List share links and access grants for a deployed Web App Review. | commentary.review.share |
POST | /api/v1/web-app-reviews/{reviewId}/shares | Create a deployed Web App Review share link. | commentary.review.share |
DELETE | /api/v1/web-app-reviews/{reviewId}/shares/{shareLinkId} | Revoke a Web App Review share link. | commentary.review.share |
GET | /mcp | Probe MCP endpoint authentication and protocol support. | session/public |
POST | /mcp | Call Commentary MCP over Streamable HTTP JSON-RPC. | session/public |
GET | /oauth/authorize | Show the OAuth authorization page. | session/public |
POST | /oauth/authorize | Approve an OAuth authorization request. | session/public |
POST | /oauth/device/code | Start OAuth device authorization. | session/public |
POST | /oauth/register | Register a public OAuth client. | session/public |
POST | /oauth/token | Exchange OAuth authorization code, device code, or refresh token. | session/public |
GET | /openapi.json | Get the Commentary OpenAPI contract as JSON. | session/public |
GET | /openapi.yaml | Get the Commentary OpenAPI contract as YAML. | session/public |
Scopes
commentary.review.read, commentary.comments.read, commentary.comments.write, commentary.comments.status, commentary.review.share, commentary.draft_reviews.delete, commentary.draft_reviews.share, commentary.review.submit, commentary.forms.read, commentary.forms.write, commentary.forms.submit, commentary.forms.writeback, commentary.brain.evals.read, commentary.brain.evals.write