Markdown compatibility1 detected · 1 enabled · mkdocs docs
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
Enabled
- MkDocsMkDocs rendering is enabled. MkDocs-specific syntax remains visible as ordinary Markdown when compatibility rendering is unavailable.
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