{"openapi":"3.1.0","info":{"title":"Commentary Public API","version":"0.1.0","summary":"Authenticated API and MCP surfaces for Commentary review automation.","description":"This contract documents the stable external API surface. Browser, internal, webhook, and test routes are intentionally excluded.","x-commentary-feature-key":"api.openapi_docs"},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","servers":[{"url":"https://commentary.dev","description":"Configured Commentary origin."},{"url":"http://localhost:3000","description":"Local development."}],"tags":[{"name":"Authentication"},{"name":"Tokens"},{"name":"Forms"},{"name":"Review comments"},{"name":"Draft reviews"},{"name":"Web App reviews"},{"name":"Knowledge Brain"},{"name":"MCP"},{"name":"Health"},{"name":"OpenAPI"}],"paths":{"/.well-known/oauth-authorization-server":{"get":{"operationId":"getOAuthAuthorizationServerMetadata","tags":["Authentication"],"summary":"Get OAuth authorization server metadata.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string","format":"uri"},"authorization_endpoint":{"type":"string","format":"uri"},"token_endpoint":{"type":"string","format":"uri"},"registration_endpoint":{"type":"string","format":"uri"},"device_authorization_endpoint":{"type":"string","format":"uri"},"scopes_supported":{"type":"array","items":{"$ref":"#/components/schemas/ExternalScope"}}},"additionalProperties":true}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getOAuthProtectedResourceMetadata","tags":["Authentication"],"summary":"Get OAuth protected resource metadata.","parameters":[{"name":"resource","in":"query","required":false,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"resource_documentation":{"type":"string","format":"uri"},"scopes_supported":{"type":"array","items":{"$ref":"#/components/schemas/ExternalScope"}},"commentary_resources":{"type":"array","items":{"type":"string","format":"uri"}},"commentary_openapi":{"type":"string","format":"uri"}},"additionalProperties":true}}}}}}},"/oauth/register":{"post":{"operationId":"registerOAuthClient","tags":["Authentication"],"summary":"Register a public OAuth client.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string","format":"uri"}},"grant_types":{"type":"array","items":{"type":"string"}},"response_types":{"type":"array","items":{"type":"string"}},"scope":{"type":"string"},"token_endpoint_auth_method":{"type":"string","enum":["none"]}},"additionalProperties":true}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"client_name":{"type":["string","null"]},"redirect_uris":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_method":{"type":"string","enum":["none"]}},"additionalProperties":true}}}},"400":{"description":"OAuth request error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}},"/oauth/authorize":{"get":{"operationId":"showOAuthAuthorizePage","tags":["Authentication"],"summary":"Show the OAuth authorization page.","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":false,"schema":{"type":"string","format":"uri"}},{"name":"response_type","in":"query","required":false,"schema":{"type":"string","enum":["code"]}},{"name":"code_challenge","in":"query","required":false,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":false,"schema":{"type":"string","enum":["S256"]}},{"name":"scope","in":"query","required":false,"schema":{"type":"string"}},{"name":"resource","in":"query","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"HTML authorization page."},"302":{"description":"Redirect to the client with an authorization error."}}},"post":{"operationId":"approveOAuthAuthorizeRequest","tags":["Authentication"],"summary":"Approve an OAuth authorization request.","security":[{"commentarySession":[]}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"302":{"description":"Redirect to the client with an authorization code or error."}}}},"/oauth/device/code":{"post":{"operationId":"createOAuthDeviceCode","tags":["Authentication"],"summary":"Start OAuth device authorization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_id"],"properties":{"client_id":{"type":"string"},"scope":{"type":"string"},"target":{"$ref":"#/components/schemas/TokenTarget"},"resource":{"type":"string"},"client_name":{"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["client_id"],"properties":{"client_id":{"type":"string"},"scope":{"type":"string"},"target":{"$ref":"#/components/schemas/TokenTarget"},"resource":{"type":"string"},"client_name":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"integer"},"interval":{"type":"integer"}}}}}},"400":{"description":"OAuth request error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}},"/oauth/token":{"post":{"operationId":"exchangeOAuthToken","tags":["Authentication"],"summary":"Exchange OAuth authorization code, device code, or refresh token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token","urn:ietf:params:oauth:grant-type:device_code"]},"code":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"client_id":{"type":"string"},"code_verifier":{"type":"string"},"refresh_token":{"type":"string"},"device_code":{"type":"string"},"resource":{"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token","urn:ietf:params:oauth:grant-type:device_code"]},"code":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"client_id":{"type":"string"},"code_verifier":{"type":"string"},"refresh_token":{"type":"string"},"device_code":{"type":"string"},"resource":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthToken"}}}},"400":{"description":"OAuth request error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"401":{"description":"OAuth token exchange was rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}},"/api/health":{"get":{"operationId":"getHealth","tags":["Health"],"summary":"Get shallow, deep, storage, or PostgreSQL health.","parameters":[{"name":"check","in":"query","required":false,"schema":{"type":"string","enum":["postgres","storage","deep"]}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Health check failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/tokens":{"get":{"operationId":"listApiTokens","tags":["Tokens"],"summary":"List API tokens for the signed-in provider connection.","security":[{"commentarySession":[]}],"x-commentary-feature-key":"api.agent_access","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["ok","tokens"],"properties":{"ok":{"const":true},"tokens":{"type":"array","items":{"$ref":"#/components/schemas/TokenSummary"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createApiToken","tags":["Tokens"],"summary":"Create an API token for scripts, MCP clients, or agents.","security":[{"commentarySession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTokenRequest"}}}},"x-commentary-feature-key":"api.agent_access","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["ok","id","grantId","token","tokenHint"],"properties":{"ok":{"const":true},"id":{"type":"string"},"grantId":{"type":"string"},"token":{"type":"string"},"tokenHint":{"type":"string"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/tokens/{tokenId}":{"delete":{"operationId":"revokeApiToken","tags":["Tokens"],"summary":"Revoke an API token.","security":[{"commentarySession":[]}],"parameters":[{"name":"tokenId","in":"path","required":true,"schema":{"type":"string"},"description":"API token id."}],"x-commentary-feature-key":"api.agent_access","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["ok","id"],"properties":{"ok":{"const":true},"id":{"type":"string"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms":{"get":{"operationId":"listForms","tags":["Forms"],"summary":"List owned forms and visible result collections for the account-scoped token principal.","security":[{"bearerAuth":["commentary.forms.read"]}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"forms":{"type":"array","items":{"type":"object","additionalProperties":true}},"resultCollections":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createForm","tags":["Forms"],"summary":"Reject standalone Forms API creation.","description":"Standalone Forms API creation has been removed. Agents should create or update draft review files through draft-review APIs, or author Git-backed form definitions in the reviewed source.","security":[{"bearerAuth":["commentary.forms.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormContractRequest"}}}},"x-commentary-feature-key":"forms.agent_api","responses":{"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"410":{"description":"Standalone form creation has been removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/validate":{"post":{"operationId":"validateFormContract","tags":["Forms"],"summary":"Validate a literal Form Contract v1 payload without persisting it.","security":[{"bearerAuth":["commentary.forms.read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormContractRequest"}}}},"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"valid":{"type":"boolean"},"contract":{"$ref":"#/components/schemas/FormContract"},"diagnostics":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/embedded-answers":{"get":{"operationId":"listEmbeddedFormAnswers","tags":["Forms"],"summary":"List embedded review form answers for an authorized result context.","description":"Requires explicit Forms read scope for raw submission values. Review-scoped tokens must include repository owner/repo and prNumber or branchRef, or draftReviewSessionId, in the query. Result-list access still requires draft ownership or a trusted source write-permission determination; callers cannot grant this by passing sourceContext fields.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"formId","in":"query","required":false,"schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"},"description":"Repository owner."},{"name":"repo","in":"query","required":false,"schema":{"type":"string"},"description":"Repository name."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number."},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number alias used by Brain endpoints."},{"name":"branch","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref for branch document review."},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref alias used by Brain endpoints."},{"name":"rootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder."},{"name":"brainRootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder alias."},{"name":"draftReviewSessionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"webAppReviewId","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"documentVersionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"formInstanceId","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"submissions":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmission"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/fillout-links":{"get":{"operationId":"listFormFilloutLinks","tags":["Forms"],"summary":"List response links owned by the account-scoped token principal.","security":[{"bearerAuth":["commentary.forms.read"]}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"filloutLinks":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createFormFilloutLink","tags":["Forms"],"summary":"Create a response link from an accessible source-backed form.","description":"The caller becomes the dedicated result-set owner. The source review remains the edit location, and source review owners do not automatically see response-link replies.","security":[{"bearerAuth":["commentary.forms.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["formId"],"properties":{"formId":{"type":"string"},"sourceContext":{"type":"object","additionalProperties":true},"sourceReviewHref":{"type":"string"},"renderer":{"type":"object","properties":{"mode":{"type":"string","enum":["default","review_file"]},"path":{"type":"string"},"kind":{"type":"string","enum":["markdown","html"]}},"additionalProperties":true},"shareMode":{"type":"string","enum":["specific_user","authenticated","anonymous"]},"replyMode":{"type":"string","enum":["identified","anonymous"]},"repeatSubmissions":{"type":"boolean"},"recipient":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}},"x-commentary-feature-key":"forms.agent_api","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"filloutLink":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/fillout-links/submit":{"post":{"operationId":"submitFormFilloutLink","tags":["Forms"],"summary":"Submit answers through a response link.","description":"Identified links require an authenticated Forms submit token. Anonymous reply mode intentionally omits submitter identity from stored submission records.","security":[{"bearerAuth":["commentary.forms.submit"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"shareToken":{"type":"string"},"values":{"type":"object","additionalProperties":true},"submissionOrigin":{"type":"string","enum":["api","mcp","cli","agent_api"]},"agentAlias":{"type":"string"},"clientName":{"type":"string"}},"additionalProperties":true}}}},"x-commentary-feature-key":"forms.agent_api","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"submission":{"$ref":"#/components/schemas/FormSubmission"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/fillout-links/{linkId}":{"delete":{"operationId":"revokeFormFilloutLink","tags":["Forms"],"summary":"Revoke a response link owned by the account-scoped token principal.","security":[{"bearerAuth":["commentary.forms.write"]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"},"description":"Response link id."}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/fillout-links/{linkId}/results":{"get":{"operationId":"listFormFilloutLinkResults","tags":["Forms"],"summary":"List result submissions owned by a response link.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"},"description":"Response link id."}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"filloutLink":{"type":"object","additionalProperties":true},"submissions":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmission"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/{formId}":{"get":{"operationId":"getForm","tags":["Forms"],"summary":"Get a form contract and metadata.","description":"Review-scoped tokens can read embedded forms only when query parameters identify the covered review context.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"},"description":"Repository owner."},{"name":"repo","in":"query","required":false,"schema":{"type":"string"},"description":"Repository name."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number."},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number alias used by Brain endpoints."},{"name":"branch","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref for branch document review."},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref alias used by Brain endpoints."},{"name":"rootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder."},{"name":"brainRootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder alias."},{"name":"draftReviewSessionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"documentVersionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"formInstanceId","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"form":{"$ref":"#/components/schemas/FormRecord"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"patch":{"operationId":"updateForm","tags":["Forms"],"summary":"Reject standalone Forms API editing.","description":"Standalone Forms API editing has been removed. Update the source review artifact or draft review file instead.","security":[{"bearerAuth":["commentary.forms.write"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormContractRequest"}}}},"x-commentary-feature-key":"forms.agent_api","responses":{"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"410":{"description":"Standalone form editing has been removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/{formId}/destinations":{"get":{"operationId":"listFormDestinations","tags":["Forms"],"summary":"List form destinations and read-only write-back status.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"formId":{"type":"string"},"destinations":{"type":"array","items":{"type":"object","additionalProperties":true}},"destinationConfig":{"type":"object","additionalProperties":true},"writebackStatus":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/{formId}/destinations/writeback":{"get":{"operationId":"getFormWritebackStatus","tags":["Forms"],"summary":"Inspect optional GitHub writeback availability for a form target.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string"}},{"name":"branch","in":"query","required":false,"schema":{"type":"string"}},{"name":"path","in":"query","required":false,"schema":{"type":"string"}},{"name":"baseBranch","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"formId":{"type":"string"},"writebackStatus":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"writeFormArtifactToGitHub","tags":["Forms"],"summary":"Explicitly write a form definition or final submission batch to GitHub through the optional writeback app.","description":"Requires commentary.forms.writeback, the forms.github_writeback license feature, a configured optional GitHub writeback app, an installed repository target, and a valid branch/path target. Submission writeback accepts submissionId or submissionIds, writes one canonical JSON result file per submission in one commit, overwrites existing result paths, can explicitly create target branches with target.createBranch and target.baseBranch, and can optionally open a pull request. Commentary storage remains available when writeback is unavailable.","security":[{"bearerAuth":["commentary.forms.writeback"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetType":{"type":"string","enum":["form_definition","submission"]},"submissionId":{"type":"string"},"submissionIds":{"type":"array","items":{"type":"string"},"maxItems":50},"target":{"type":"object","properties":{"owner":{"type":"string"},"repo":{"type":"string"},"branch":{"type":"string"},"path":{"type":"string"},"baseBranch":{"type":"string"},"createBranch":{"type":"boolean"}},"additionalProperties":false},"format":{"type":"string","enum":["json","yaml"]},"commitMessage":{"type":"string"},"openPullRequest":{"type":"boolean"},"pullRequestTitle":{"type":"string"},"pullRequestBody":{"type":"string"}},"additionalProperties":true}}}},"x-commentary-feature-key":"forms.github_writeback","responses":{"202":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"formId":{"type":"string"},"submissionId":{"type":"string"},"submissionIds":{"type":"array","items":{"type":"string"}},"writeback":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/{formId}/git-results":{"get":{"operationId":"listFormGitResults","tags":["Forms"],"summary":"List canonical git-hosted result files for a source-backed form.","description":"Discovers files in the canonical results directory near the form source path. Use action=status for read-only sync status and canonical location details.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."},{"name":"action","in":"query","required":false,"schema":{"type":"string","enum":["list","status"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string"}},{"name":"ref","in":"query","required":false,"schema":{"type":"string"}},{"name":"branch","in":"query","required":false,"schema":{"type":"string"}},{"name":"sourcePath","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"formId":{"type":"string"},"target":{"type":"object","additionalProperties":true},"files":{"type":"array","items":{"type":"object","additionalProperties":true}},"diagnostics":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"syncFormGitResults","tags":["Forms"],"summary":"Preview result writeback or explicitly import canonical git-hosted result files.","description":"Import and preview actions require commentary.forms.writeback and the forms.github_writeback license feature. Import validates canonical JSON/YAML result files, deduplicates by external id, records audit events, and stores imported submissions with git sync metadata.","security":[{"bearerAuth":["commentary.forms.writeback"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormGitResultsRequest"}}}},"x-commentary-feature-key":"forms.github_writeback","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/{formId}/submissions":{"get":{"operationId":"listFormSubmissions","tags":["Forms"],"summary":"List submissions for a permitted result collection.","description":"Result-list access is separate from form fill access. Draft results default to the draft owner; PR and branch results require trusted write-permission detection. When write permission cannot be determined, list access is denied.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"submissions":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmission"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"submitForm","tags":["Forms"],"summary":"Submit final form answers.","description":"All writes validate server-side. Invalid answers are stored as draft validation failures and return diagnostics without finalizing.","security":[{"bearerAuth":["commentary.forms.submit"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmissionRequest"}}}},"x-commentary-feature-key":"forms.agent_api","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"submission":{"$ref":"#/components/schemas/FormSubmission"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/{formId}/submissions/events":{"get":{"operationId":"streamFormSubmissionEvents","tags":["Forms"],"summary":"Stream final form submission events using Server-Sent Events.","description":"Streams summary-only submission.submitted events for permitted result contexts. Raw values are not included in the event payload; call the submission detail endpoint when value access is required.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Event cursor or latest."},{"name":"once","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Return the current batch and close."},{"name":"kind","in":"query","required":false,"schema":{"type":"string"},"description":"Source context kind for review-scoped submissions."},{"name":"draftReviewSessionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"webAppReviewId","in":"query","required":false,"schema":{"type":"string"}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string"}},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"}},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"documentVersionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"formInstanceId","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Server-Sent Events stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/{formId}/submissions/validate":{"post":{"operationId":"validateFormAnswers","tags":["Forms"],"summary":"Validate form answers against the current form contract without storing a submission.","security":[{"bearerAuth":["commentary.forms.submit"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmissionRequest"}}}},"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"valid":{"type":"boolean"},"diagnostics":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/forms/{formId}/submissions/{submissionId}":{"get":{"operationId":"getFormSubmission","tags":["Forms"],"summary":"Read or export one form submission including raw values for an authorized principal.","description":"Pass format=json, yaml, or csv to download a bounded stable export for one submission. CSV is available only when submitted field values are tabular scalars or scalar arrays.","security":[{"bearerAuth":["commentary.forms.read"]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Form id or reference id."},{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"},"description":"Form submission id."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","yaml","csv"]},"description":"Optional export format. Omit for the normal JSON API envelope."},{"name":"kind","in":"query","required":false,"schema":{"type":"string"},"description":"Source context kind when exporting a review-scoped embedded answer."},{"name":"draftReviewSessionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"webAppReviewId","in":"query","required":false,"schema":{"type":"string"}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string"}},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"}},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"documentVersionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"formInstanceId","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"forms.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"submission":{"$ref":"#/components/schemas/FormSubmission"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"409":{"description":"CSV export is not available for this submission shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"413":{"description":"The export exceeded the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/review/comments":{"get":{"operationId":"listReviewComments","tags":["Review comments"],"summary":"List review comments for a PR or branch document file.","security":[{"bearerAuth":["commentary.comments.read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string"}},{"name":"file","in":"query","required":false,"schema":{"type":"string"},"description":"File path."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"}},{"name":"branch","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"api.review.read","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"threads":{"type":"array","items":{"$ref":"#/components/schemas/ReviewThread"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createReviewComment","tags":["Review comments"],"summary":"Create a review comment thread on a PR or branch document.","security":[{"bearerAuth":["commentary.comments.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReviewCommentRequest"}}}},"x-commentary-feature-key":"api.comments.write","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"thread":{"$ref":"#/components/schemas/ReviewThread"},"threadId":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/review/participants":{"get":{"operationId":"listReviewParticipants","tags":["Review participants"],"summary":"List users and agents taggable in a review.","security":[{"bearerAuth":["commentary.comments.read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string"}},{"name":"draftSessionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"webAppReviewId","in":"query","required":false,"schema":{"type":"string"}},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"}},{"name":"branch","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"review.mentions","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"participants":{"type":"array","items":{"$ref":"#/components/schemas/ReviewParticipant"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"addReviewParticipant","tags":["Review participants"],"summary":"Add a taggable user or register an agent alias for the current user.","description":"Provider-backed users are taggable metadata only. Draft Review user additions create a user share link.","security":[{"bearerAuth":["commentary.comments.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddReviewParticipantRequest"}}}},"x-commentary-feature-key":"review.mentions","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"participant":{"$ref":"#/components/schemas/ReviewParticipant"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/ReviewParticipant"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/review/mention-notifications":{"get":{"operationId":"listMentionNotifications","tags":["Review participants"],"summary":"List mention notifications for the current token principal.","security":[{"bearerAuth":["commentary.comments.read"]}],"parameters":[{"name":"unread","in":"query","required":false,"schema":{"type":"integer","enum":[0,1]}}],"x-commentary-feature-key":"review.mentions","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"notifications":{"type":"array","items":{"$ref":"#/components/schemas/ReviewMentionNotification"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/review/mention-notifications/{notificationId}/read":{"post":{"operationId":"markMentionNotificationRead","tags":["Review participants"],"summary":"Mark a mention notification read for the current token principal.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"notificationId","in":"path","required":true,"schema":{"type":"string"},"description":"Mention notification id."}],"x-commentary-feature-key":"review.mentions","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/review/progress":{"get":{"operationId":"getReviewProgress","tags":["Review progress"],"summary":"Read per-reviewer progress for a PR, branch document, or draft review.","description":"Agents can read progress but cannot mutate human review progress through the external API.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string"}},{"name":"draftSessionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"file","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Repeat for one or more file paths."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"}},{"name":"branch","in":"query","required":false,"schema":{"type":"string"}},{"name":"revision","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"api.review.read","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewProgressResponse"}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/review/threads/{threadId}/comments":{"post":{"operationId":"replyToReviewThread","tags":["Review comments"],"summary":"Reply to an existing review thread.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Review thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadReplyRequest"}}}},"x-commentary-feature-key":"api.comments.write","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"thread":{"$ref":"#/components/schemas/ReviewThread"},"threadId":{"type":"string"},"commentId":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/review/threads/{threadId}/status":{"post":{"operationId":"updateReviewThreadStatus","tags":["Review comments"],"summary":"Resolve or reopen an existing review thread.","security":[{"bearerAuth":["commentary.comments.status"]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Review thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadStatusRequest"}}}},"x-commentary-feature-key":"api.comments.write","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"thread":{"$ref":"#/components/schemas/ReviewThread"},"threadId":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews":{"get":{"operationId":"listDraftReviews","tags":["Draft reviews"],"summary":"List draft or Brainstorming Reviews owned by the account-scoped token principal.","description":"Use mode=brainstorming to list Brainstorming Reviews available to the token. Brainstorming agent operations require the brainstorming_reviews.agent_api license feature.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["draft","brainstorming"]}}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"draftReviews":{"type":"array","items":{"$ref":"#/components/schemas/DraftReview"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createDraftReview","tags":["Draft reviews"],"summary":"Create a draft or Brainstorming Review session, optionally with initial file content.","description":"File content fields are literal UTF-8 payloads. Commentary never treats submitted paths as local files to read.","security":[{"bearerAuth":["commentary.comments.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDraftReviewRequest"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"draftReview":{"$ref":"#/components/schemas/DraftReview"},"sessionId":{"type":"string"},"reviewUrl":{"type":"string","format":"uri"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}":{"get":{"operationId":"getDraftReview","tags":["Draft reviews"],"summary":"Get a draft review session.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"draftReview":{"$ref":"#/components/schemas/DraftReview"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"patch":{"operationId":"updateDraftReview","tags":["Draft reviews"],"summary":"Update draft review metadata or Git base metadata.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDraftReviewRequest"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"draftReview":{"$ref":"#/components/schemas/DraftReview"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"delete":{"operationId":"deleteDraftReview","tags":["Draft reviews"],"summary":"Permanently delete a draft review from active Commentary storage.","security":[{"bearerAuth":["commentary.draft_reviews.delete"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"x-commentary-feature-key":"draft_reviews.delete","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"deleted":{"type":"boolean"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/files":{"get":{"operationId":"listDraftReviewFiles","tags":["Draft reviews"],"summary":"List draft review files.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"files":{"type":"array","items":{"$ref":"#/components/schemas/DraftReviewFile"}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/files/{fileId}/content":{"get":{"operationId":"getDraftReviewFileContent","tags":["Draft reviews"],"summary":"Download the latest content for a draft review file.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"fileId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review file id."}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Raw latest file content.","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/revisions":{"get":{"operationId":"listDraftReviewRevisions","tags":["Draft reviews"],"summary":"List draft review revisions.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"revisions":{"type":"array","items":{"$ref":"#/components/schemas/DraftRevision"}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"uploadDraftReviewRevision","tags":["Draft reviews"],"summary":"Upload a new draft or Brainstorming Review revision from literal file content.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftRevisionUploadRequest"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"revision":{"$ref":"#/components/schemas/DraftRevision"},"changedFiles":{"type":"array","items":{"type":"object","additionalProperties":true}},"addressedThreadIds":{"type":"array","items":{"type":"string"}},"source":{"type":"object","additionalProperties":true},"noOp":{"type":"boolean"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/consensus-rule":{"get":{"operationId":"getDraftReviewConsensusRule","tags":["Draft reviews"],"summary":"Get the configured Brainstorming Review consensus rule.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"consensusRule":{"$ref":"#/components/schemas/ConsensusRule"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"patch":{"operationId":"updateDraftReviewConsensusRule","tags":["Draft reviews"],"summary":"Update the Brainstorming Review consensus rule, including countAgentSignals and delegatedOwnerAgentParticipantId. Owner access is required.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsensusRule"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"consensusRule":{"$ref":"#/components/schemas/ConsensusRule"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/consensus-state":{"get":{"operationId":"getDraftReviewConsensusState","tags":["Draft reviews"],"summary":"Get Brainstorming Review consensus counts and file readiness.","security":[{"bearerAuth":["commentary.comments.read"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"consensusRule":{"$ref":"#/components/schemas/ConsensusRule"},"counts":{"type":"object","additionalProperties":true},"filesWithActionableThreads":{"type":"array","items":{"type":"string"}},"filesWithBlockedThreads":{"type":"array","items":{"type":"string"}},"agentReady":{"type":"boolean"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/comments":{"get":{"operationId":"listDraftReviewComments","tags":["Draft reviews"],"summary":"List comments for a draft review.","security":[{"bearerAuth":["commentary.comments.read"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"fileId","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","resolved"]}},{"name":"consensusState","in":"query","required":false,"schema":{"type":"string","enum":["pending","accepted_for_change","blocked","needs_owner_decision","rejected","out_of_scope","applied","resolved"]}}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"threads":{"type":"array","items":{"$ref":"#/components/schemas/ReviewThread"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createDraftReviewComment","tags":["Draft reviews"],"summary":"Create a comment thread on a draft review.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDraftCommentRequest"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"thread":{"$ref":"#/components/schemas/ReviewThread"},"threadId":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/comments/{threadId}/replies":{"post":{"operationId":"replyToDraftReviewComment","tags":["Draft reviews"],"summary":"Reply to a draft review comment.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Review thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadReplyRequest"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"thread":{"$ref":"#/components/schemas/ReviewThread"},"threadId":{"type":"string"},"commentId":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/comments/{threadId}/status":{"post":{"operationId":"updateDraftReviewCommentStatus","tags":["Draft reviews"],"summary":"Resolve or reopen a draft review comment.","security":[{"bearerAuth":["commentary.comments.status"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Review thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadStatusRequest"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"thread":{"$ref":"#/components/schemas/ReviewThread"},"threadId":{"type":"string"},"commentId":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/comments/{threadId}/feedback":{"post":{"operationId":"updateDraftReviewCommentFeedback","tags":["Draft reviews"],"summary":"Set or clear a Brainstorming Review feedback stance. When countAgentSignals is enabled, registered agent aliases can provide independent signals.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Review thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadFeedbackRequest"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"thread":{"$ref":"#/components/schemas/ReviewThread"},"threadId":{"type":"string"},"commentId":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/comments/{threadId}/consensus-decision":{"post":{"operationId":"updateDraftReviewCommentConsensusDecision","tags":["Draft reviews"],"summary":"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.","security":[{"bearerAuth":["commentary.comments.status"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Review thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsensusDecisionRequest"}}}},"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"thread":{"$ref":"#/components/schemas/ReviewThread"},"threadId":{"type":"string"},"commentId":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/events":{"get":{"operationId":"streamDraftReviewEvents","tags":["Draft reviews"],"summary":"Stream draft or Brainstorming Review live events using Server-Sent Events.","description":"Events include comment.created, reply.created, comment.resolved, comment.reopened, feedback_signal.changed, feedback.marked_addressed, file.added, file.updated, file.archived, revision.created, draft.converted_to_brainstorming, brainstorming.metadata_changed, and brainstorming.status_changed.","security":[{"bearerAuth":["commentary.comments.read"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Event cursor or latest."},{"name":"once","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Return the current batch and close."}],"x-commentary-feature-key":"draft_reviews.agent_api","responses":{"200":{"description":"Server-Sent Events stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/shares":{"get":{"operationId":"listDraftReviewShares","tags":["Draft reviews"],"summary":"List share links and access grants for a draft review.","security":[{"bearerAuth":["commentary.draft_reviews.share"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"x-commentary-feature-key":"draft_reviews.sharing","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"shares":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createDraftReviewShare","tags":["Draft reviews"],"summary":"Create a draft review share link.","security":[{"bearerAuth":["commentary.draft_reviews.share"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDraftShareRequest"}}}},"x-commentary-feature-key":"draft_reviews.sharing","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"shareUrl":{"type":"string","format":"uri"},"link":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/shares/{shareLinkId}":{"delete":{"operationId":"revokeDraftReviewShare","tags":["Draft reviews"],"summary":"Revoke a draft review share link.","security":[{"bearerAuth":["commentary.draft_reviews.share"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"shareLinkId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review share link id."}],"x-commentary-feature-key":"draft_reviews.sharing","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"revoked":{"type":"boolean"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/draft-reviews/{sessionId}/access/{accessGrantId}":{"delete":{"operationId":"removeDraftReviewAccess","tags":["Draft reviews"],"summary":"Remove a draft review access grant.","security":[{"bearerAuth":["commentary.draft_reviews.share"]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review session id."},{"name":"accessGrantId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review access grant id."}],"x-commentary-feature-key":"draft_reviews.sharing","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"removed":{"type":"boolean"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/web-app-reviews":{"get":{"operationId":"listWebAppReviews","tags":["Web App reviews"],"summary":"List Web App Reviews owned by the account-scoped token principal.","security":[{"bearerAuth":["commentary.review.read"]}],"x-commentary-feature-key":"web_app_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"webAppReviews":{"type":"array","items":{"$ref":"#/components/schemas/WebAppReview"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createWebAppReview","tags":["Web App reviews"],"summary":"Create a Web App Review for a deployed or localhost preview URL.","description":"The preview app must be customer-controlled and frameable by Commentary. The Web App Review SDK enables selector comments; screenshot comments can target bounded areas when the SDK is unavailable.","security":[{"bearerAuth":["commentary.comments.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebAppReviewRequest"}}}},"x-commentary-feature-key":"web_app_reviews.agent_api","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"webAppReview":{"$ref":"#/components/schemas/WebAppReview"},"reviewId":{"type":"string"},"reviewUrl":{"type":"string","format":"uri"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/web-app-reviews/{reviewId}":{"get":{"operationId":"getWebAppReview","tags":["Web App reviews"],"summary":"Get Web App Review metadata.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."}],"x-commentary-feature-key":"web_app_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"webAppReview":{"$ref":"#/components/schemas/WebAppReview"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"patch":{"operationId":"updateWebAppReview","tags":["Web App reviews"],"summary":"Update Web App Review metadata.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchWebAppReviewRequest"}}}},"x-commentary-feature-key":"web_app_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"webAppReview":{"$ref":"#/components/schemas/WebAppReview"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/web-app-reviews/{reviewId}/comments":{"get":{"operationId":"listWebAppReviewComments","tags":["Web App reviews"],"summary":"List selector and screenshot comments for a Web App Review.","security":[{"bearerAuth":["commentary.comments.read"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."},{"name":"includeImages","in":"query","required":false,"schema":{"type":"boolean"}}],"x-commentary-feature-key":"web_app_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"comments":{"type":"array","items":{"$ref":"#/components/schemas/WebAppReviewComment"}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createWebAppReviewComment","tags":["Web App reviews"],"summary":"Create a selector or screenshot comment for a Web App Review.","security":[{"bearerAuth":["commentary.comments.write"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebAppReviewCommentRequest"}}}},"x-commentary-feature-key":"web_app_reviews.agent_api","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"comment":{"$ref":"#/components/schemas/WebAppReviewComment"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/web-app-reviews/{reviewId}/comments/{threadId}/status":{"post":{"operationId":"updateWebAppReviewCommentStatus","tags":["Web App reviews"],"summary":"Resolve or reopen a Web App Review comment thread.","security":[{"bearerAuth":["commentary.comments.status"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."},{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Review thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadStatusRequest"}}}},"x-commentary-feature-key":"web_app_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"comment":{"$ref":"#/components/schemas/WebAppReviewComment"},"comments":{"type":"array","items":{"$ref":"#/components/schemas/WebAppReviewComment"}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/web-app-reviews/{reviewId}/agent-context":{"get":{"operationId":"getWebAppReviewAgentContext","tags":["Web App reviews"],"summary":"Get Web App Review comments as actionable, untrusted agent editing tasks.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."},{"name":"includeResolved","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"includeImages","in":"query","required":false,"schema":{"type":"boolean"}}],"x-commentary-feature-key":"web_app_reviews.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebAppReviewAgentContext"}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/web-app-reviews/{reviewId}/shares":{"get":{"operationId":"listWebAppReviewShares","tags":["Web App reviews"],"summary":"List share links and access grants for a deployed Web App Review.","security":[{"bearerAuth":["commentary.review.share"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."}],"x-commentary-feature-key":"web_app_reviews.sharing","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"shares":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createWebAppReviewShare","tags":["Web App reviews"],"summary":"Create a deployed Web App Review share link.","description":"Localhost Web App Reviews cannot be shared through Commentary share links.","security":[{"bearerAuth":["commentary.review.share"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDraftShareRequest"}}}},"x-commentary-feature-key":"web_app_reviews.sharing","responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"shareUrl":{"type":"string","format":"uri"},"link":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/web-app-reviews/{reviewId}/shares/{shareLinkId}":{"delete":{"operationId":"revokeWebAppReviewShare","tags":["Web App reviews"],"summary":"Revoke a Web App Review share link.","security":[{"bearerAuth":["commentary.review.share"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."},{"name":"shareLinkId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review share link id."}],"x-commentary-feature-key":"web_app_reviews.sharing","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"revoked":{"type":"boolean"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/web-app-reviews/{reviewId}/access/{accessGrantId}":{"delete":{"operationId":"removeWebAppReviewAccess","tags":["Web App reviews"],"summary":"Remove a Web App Review access grant.","security":[{"bearerAuth":["commentary.review.share"]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Web App Review id."},{"name":"accessGrantId","in":"path","required":true,"schema":{"type":"string"},"description":"Draft review access grant id."}],"x-commentary-feature-key":"web_app_reviews.sharing","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"removed":{"type":"boolean"}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/brain/reviews":{"get":{"operationId":"listBrainReviews","tags":["Knowledge Brain"],"summary":"List Knowledge Brain reviews available to the token.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string"}},{"name":"rootFolder","in":"query","required":false,"schema":{"type":"string"}},{"name":"brainRootFolder","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"brain.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/BrainReview"}}}}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/brain/review/changed-files":{"get":{"operationId":"listChangedBrainFiles","tags":["Knowledge Brain"],"summary":"List changed files for a Knowledge Brain review.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"},"description":"Repository owner."},{"name":"repo","in":"query","required":false,"schema":{"type":"string"},"description":"Repository name."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number."},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number alias used by Brain endpoints."},{"name":"branch","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref for branch document review."},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref alias used by Brain endpoints."},{"name":"rootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder."},{"name":"brainRootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder alias."},{"name":"file","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"brain.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"changedFiles":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/brain/review/comments":{"get":{"operationId":"listBrainReviewComments","tags":["Knowledge Brain"],"summary":"List comments for a Knowledge Brain review.","security":[{"bearerAuth":["commentary.comments.read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"},"description":"Repository owner."},{"name":"repo","in":"query","required":false,"schema":{"type":"string"},"description":"Repository name."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number."},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number alias used by Brain endpoints."},{"name":"branch","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref for branch document review."},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref alias used by Brain endpoints."},{"name":"rootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder."},{"name":"brainRootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder alias."},{"name":"file","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"brain.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"threads":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/brain/review/health-findings":{"get":{"operationId":"listBrainHealthFindings","tags":["Knowledge Brain"],"summary":"List health findings for a Knowledge Brain review.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"},"description":"Repository owner."},{"name":"repo","in":"query","required":false,"schema":{"type":"string"},"description":"Repository name."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number."},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number alias used by Brain endpoints."},{"name":"branch","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref for branch document review."},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref alias used by Brain endpoints."},{"name":"rootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder."},{"name":"brainRootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder alias."},{"name":"file","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"brain.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"healthFindings":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/brain/review/requested-revisions":{"get":{"operationId":"listBrainRequestedRevisions","tags":["Knowledge Brain"],"summary":"List requested revisions for a Knowledge Brain review.","security":[{"bearerAuth":["commentary.review.read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"},"description":"Repository owner."},{"name":"repo","in":"query","required":false,"schema":{"type":"string"},"description":"Repository name."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number."},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number alias used by Brain endpoints."},{"name":"branch","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref for branch document review."},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref alias used by Brain endpoints."},{"name":"rootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder."},{"name":"brainRootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder alias."},{"name":"file","in":"query","required":false,"schema":{"type":"string"}},{"name":"filePath","in":"query","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}}],"x-commentary-feature-key":"brain.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"requestedRevisions":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/brain/review/ready":{"post":{"operationId":"markBrainReviewReady","tags":["Knowledge Brain"],"summary":"Mark a Knowledge Brain requested revision ready for review.","security":[{"bearerAuth":["commentary.comments.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrainReadyRequest"}}}},"x-commentary-feature-key":"brain.agent_api","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/v1/brain/review/evaluations":{"get":{"operationId":"listBrainEvaluations","tags":["Knowledge Brain"],"summary":"List Knowledge Brain evaluation ledger entries.","security":[{"bearerAuth":["commentary.brain.evals.read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["github"]}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"},"description":"Repository owner."},{"name":"repo","in":"query","required":false,"schema":{"type":"string"},"description":"Repository name."},{"name":"pr","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number."},{"name":"prNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Pull request number alias used by Brain endpoints."},{"name":"branch","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref for branch document review."},{"name":"branchRef","in":"query","required":false,"schema":{"type":"string"},"description":"Branch ref alias used by Brain endpoints."},{"name":"rootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder."},{"name":"brainRootFolder","in":"query","required":false,"schema":{"type":"string"},"description":"Knowledge Brain root folder alias."}],"x-commentary-feature-key":"brain.evaluations","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"evaluations":{"type":"array","items":{"$ref":"#/components/schemas/BrainEvaluation"}}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"createBrainEvaluation","tags":["Knowledge Brain"],"summary":"Create a Knowledge Brain evaluation ledger entry.","security":[{"bearerAuth":["commentary.brain.evals.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrainEvaluationRequest"}}}},"x-commentary-feature-key":"brain.evaluations","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"evaluation":{"$ref":"#/components/schemas/BrainEvaluation"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"patch":{"operationId":"updateBrainEvaluation","tags":["Knowledge Brain"],"summary":"Update a Knowledge Brain evaluation ledger entry.","security":[{"bearerAuth":["commentary.brain.evals.write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrainEvaluationRequest"}}}},"x-commentary-feature-key":"brain.evaluations","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"evaluation":{"$ref":"#/components/schemas/BrainEvaluation"}},"additionalProperties":true}}}},"400":{"description":"The request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"403":{"description":"The token or session does not have permission for this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"429":{"description":"The request was rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/mcp":{"get":{"operationId":"getMcpEndpoint","tags":["MCP"],"summary":"Probe MCP endpoint authentication and protocol support.","security":[{"bearerAuth":[]}],"x-commentary-feature-key":"mcp.review","responses":{"200":{"description":"Authenticated GET is accepted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Bearer authentication challenge with protected resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"post":{"operationId":"postMcpJsonRpc","tags":["MCP"],"summary":"Call Commentary MCP over Streamable HTTP JSON-RPC.","description":"Authenticated tools/list advertises: commentary_forms, draft_review, review_comments, web_app_review, review_participants, review_polls, review_document, brain_review.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcRequest"}}}},"x-commentary-feature-key":"mcp.review","responses":{"200":{"description":"JSON-RPC response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Accepted JSON-RPC notification."},"400":{"description":"Invalid JSON-RPC request.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Bearer authentication challenge.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiJson","tags":["OpenAPI"],"summary":"Get the Commentary OpenAPI contract as JSON.","x-commentary-feature-key":"api.openapi_docs","responses":{"200":{"description":"OpenAPI JSON document.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/openapi.yaml":{"get":{"operationId":"getOpenApiYaml","tags":["OpenAPI"],"summary":"Get the Commentary OpenAPI contract as YAML.","x-commentary-feature-key":"api.openapi_docs","responses":{"200":{"description":"OpenAPI YAML document.","content":{"application/yaml":{"schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Commentary external access token","description":"Bearer token from an API token, OAuth authorization code flow, OAuth refresh token flow, or OAuth device flow."},"commentarySession":{"type":"apiKey","in":"cookie","name":"commentary_session","description":"Signed-in Commentary browser session. Used for API token management routes."}},"schemas":{"ExternalError":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false},"error":{"type":"string"}},"additionalProperties":true},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"additionalProperties":true},"OAuthToken":{"type":"object","required":["access_token","refresh_token","token_type","expires_in","scope"],"properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer"},"scope":{"type":"string","description":"Space-delimited scopes actually granted to this token. Registered OAuth clients may receive a subset of requested scopes."}}},"ExternalScope":{"type":"string","enum":["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"]},"TokenTarget":{"type":"string","description":"Target string such as account, github:owner/repo, github:owner/repo:pull:123, github:owner/repo:branch:main, or draft:sessionId."},"CreateTokenRequest":{"type":"object","properties":{"label":{"type":"string"},"scopes":{"oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ExternalScope"}}]},"target":{"$ref":"#/components/schemas/TokenTarget"},"expiresAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"TokenSummary":{"type":"object","properties":{"id":{"type":"string"},"grantId":{"type":"string"},"tokenType":{"type":"string"},"tokenHint":{"type":"string"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ExternalScope"}},"resourceScope":{"type":"string","enum":["review","repo","account"]},"owner":{"type":["string","null"]},"repo":{"type":["string","null"]},"prNumber":{"type":["integer","null"]},"branchRef":{"type":["string","null"]},"draftReviewSessionId":{"type":["string","null"]},"clientName":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"FormContract":{"type":"object","description":"Normalized Commentary Form Contract v1.","additionalProperties":true},"FormSourceContext":{"type":"object","description":"Embedded review context such as repository owner/repo plus prNumber or branchRef, draftReviewSessionId, filePath, documentVersionId, formInstanceId, and route.","additionalProperties":true},"FormRecord":{"type":"object","properties":{"id":{"type":"string"},"referenceId":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["active","archived"]},"visibility":{"type":"string","enum":["private","shared","public_placeholder"]},"sourceType":{"type":"string","enum":["commentary","github","embedded","custom"]},"contractHash":{"type":"string"},"currentVersionId":{"type":["string","null"]},"sourceMetadata":{"type":"object","additionalProperties":true},"destinationConfig":{"type":"object","additionalProperties":true},"contract":{"$ref":"#/components/schemas/FormContract"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"FormSubmission":{"type":"object","properties":{"id":{"type":"string"},"formId":{"type":"string"},"formVersionId":{"type":"string"},"status":{"type":"string","enum":["draft","final","replaced","voided"]},"validationResult":{"type":"object","additionalProperties":true},"values":{"type":"object","description":"Raw submitted values. Requires commentary.forms.read.","additionalProperties":true},"sourceContext":{"$ref":"#/components/schemas/FormSourceContext"},"sourceContextSummary":{"type":"object","additionalProperties":true},"submissionOrigin":{"type":"string","enum":["web","api","mcp","cli","agent_api"]},"submitterViewerId":{"type":["string","null"]},"submitterLogin":{"type":["string","null"]},"agentAlias":{"type":["string","null"]},"clientName":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true},"FormContractRequest":{"type":"object","properties":{"contract":{"$ref":"#/components/schemas/FormContract"},"contractSource":{"type":"string","description":"Literal JSON or YAML form contract source."},"sourceFormat":{"type":"string","enum":["json","yaml","auto"]},"referenceId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["private","shared","public_placeholder"]},"sourceType":{"type":"string","enum":["commentary","github","embedded","custom"]},"sourceMetadata":{"type":"object","additionalProperties":true},"destinationConfig":{"type":"object","additionalProperties":true},"agentAlias":{"type":"string"},"clientName":{"type":"string"}},"additionalProperties":false},"FormSubmissionRequest":{"type":"object","properties":{"values":{"type":"object","additionalProperties":true},"sourceContext":{"$ref":"#/components/schemas/FormSourceContext"},"submissionId":{"type":"string"},"submissionOrigin":{"type":"string","enum":["api","mcp","cli","agent_api"]},"agentAlias":{"type":"string"},"clientName":{"type":"string"}},"additionalProperties":false},"FormGitResultsRequest":{"type":"object","properties":{"action":{"type":"string","enum":["import","preview_writeback"]},"submissionId":{"type":"string"},"submissionIds":{"type":"array","items":{"type":"string"},"maxItems":50},"paths":{"type":"array","items":{"type":"string"}},"target":{"type":"object","properties":{"owner":{"type":"string"},"repo":{"type":"string"},"ref":{"type":"string"},"branch":{"type":"string"},"sourcePath":{"type":"string"},"baseBranch":{"type":"string"},"createBranch":{"type":"boolean"}},"additionalProperties":true},"summary":{"type":"string"},"commitMessage":{"type":"string"},"openPullRequest":{"type":"boolean"},"pullRequestTitle":{"type":"string"},"pullRequestBody":{"type":"string"},"agentAlias":{"type":"string"},"clientName":{"type":"string"}},"additionalProperties":true},"ReviewThread":{"type":"object","properties":{"id":{"type":"string"},"filePath":{"type":"string"},"status":{"type":"string","enum":["open","resolved"]},"anchorStatus":{"type":"string"},"blockId":{"type":"string"},"nodeType":{"type":"string"},"sourceLineStart":{"type":"integer"},"sourceLineEnd":{"type":"integer"},"selectedText":{"type":["string","null"]},"prefixText":{"type":["string","null"]},"suffixText":{"type":["string","null"]},"feedbackSignals":{"type":"array","items":{"type":"object","additionalProperties":true}},"feedbackSummary":{"type":["object","null"],"additionalProperties":true},"consensus":{"type":["object","null"],"additionalProperties":true},"comments":{"type":"array","items":{"type":"object","additionalProperties":true}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"ReviewParticipant":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["user","agent"]},"providerLogin":{"type":["string","null"]},"providerUserId":{"type":["string","null"]},"viewerId":{"type":["string","null"]},"agentAlias":{"type":["string","null"]},"displayName":{"type":"string"},"mentionHandle":{"type":"string"},"source":{"type":"string"},"taggable":{"type":"boolean"}},"additionalProperties":true},"AddReviewParticipantRequest":{"type":"object","properties":{"provider":{"type":"string","enum":["github"],"default":"github"},"owner":{"type":"string"},"repo":{"type":"string"},"prNumber":{"type":"integer"},"branchRef":{"type":"string"},"draftSessionId":{"type":"string"},"webAppReviewId":{"type":"string"},"kind":{"type":"string","enum":["user","agent"]},"providerLogin":{"type":"string"},"providerUserId":{"type":"string"},"userId":{"type":"string"},"agentAlias":{"type":"string"},"displayName":{"type":"string"},"mentionHandle":{"type":"string"},"recipient":{"type":"string"}},"additionalProperties":false},"ReviewMentionNotification":{"type":"object","properties":{"id":{"type":"string"},"contextKey":{"type":"string"},"threadId":{"type":"string"},"commentId":{"type":"string"},"mentionHandle":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"readAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true},"ReviewProgressFile":{"type":"object","required":["filePath","status","changedSinceReviewed"],"properties":{"filePath":{"type":"string"},"status":{"type":"string","enum":["not_started","in_progress","reviewed","needs_re_review","skipped"]},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewedByViewerId":{"type":["string","null"]},"reviewedByLogin":{"type":["string","null"]},"lastInteractedAt":{"type":["string","null"],"format":"date-time"},"reviewedRevision":{"type":["string","null"]},"currentRevision":{"type":["string","null"]},"changedSinceReviewed":{"type":"boolean"},"skippedReason":{"type":["string","null"]},"partial":{"type":["object","null"],"additionalProperties":true}},"additionalProperties":true},"ReviewProgressSummary":{"type":"object","properties":{"totalFiles":{"type":"integer"},"reviewedFiles":{"type":"integer"},"inProgressFiles":{"type":"integer"},"skippedFiles":{"type":"integer"},"needsReReviewFiles":{"type":"integer"},"notStartedFiles":{"type":"integer"},"changedSinceReviewedFiles":{"type":"integer"},"percentReviewed":{"type":"integer"},"lastReviewedFilePath":{"type":["string","null"]},"lastReviewedSectionTitle":{"type":["string","null"]}},"additionalProperties":false},"ReviewProgressResponse":{"type":"object","required":["ok","viewerScoped","summary","files"],"properties":{"ok":{"const":true},"viewerScoped":{"type":"boolean"},"summary":{"$ref":"#/components/schemas/ReviewProgressSummary"},"files":{"type":"array","items":{"$ref":"#/components/schemas/ReviewProgressFile"}}},"additionalProperties":false},"CreateReviewCommentRequest":{"type":"object","required":["owner","repo","filePath","blockId","nodeType","sourceLineStart","sourceLineEnd","bodyMarkdown"],"properties":{"provider":{"type":"string","enum":["github"],"default":"github"},"owner":{"type":"string"},"repo":{"type":"string"},"prNumber":{"type":"integer"},"branchRef":{"type":"string"},"filePath":{"type":"string"},"blockId":{"type":"string"},"nodeType":{"type":"string"},"sourceLineStart":{"type":"integer"},"sourceLineEnd":{"type":"integer"},"selectedText":{"type":["string","null"]},"prefixText":{"type":["string","null"]},"suffixText":{"type":["string","null"]},"bodyMarkdown":{"type":"string"},"agentAlias":{"type":["string","null"]}}},"ThreadReplyRequest":{"type":"object","required":["bodyMarkdown"],"properties":{"bodyMarkdown":{"type":"string"},"agentAlias":{"type":["string","null"]}},"additionalProperties":false},"ThreadStatusRequest":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["open","resolved"]},"bodyMarkdown":{"type":"string","description":"Optional closing or reopening reply. Requires comment write scope when present."},"agentAlias":{"type":["string","null"]}},"additionalProperties":false},"ThreadFeedbackRequest":{"type":"object","required":["signal"],"properties":{"signal":{"type":"string","enum":["agree","object","blocker","needs_clarification","addressed"],"description":"agree, object, blocker, and needs_clarification are exclusive reviewer stances per actor and thread. addressed is owner-only and clears unresolved feedback."},"active":{"type":"boolean","default":true},"agentAlias":{"type":["string","null"]},"clientName":{"type":["string","null"]}},"additionalProperties":false},"ConsensusRule":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["owner_decides","no_open_blockers","n_of_m","required_reviewers"]},"agreementThreshold":{"type":"integer"},"minResponseCount":{"type":"integer"},"requiredReviewerIds":{"type":"array","items":{"type":"string"}},"delegatedOwnerAgentParticipantId":{"type":["string","null"]},"requiredReviewerCondition":{"type":"string","enum":["all_required_agree","no_required_objects","owner_plus_one_required_agrees","threshold_no_blockers"]},"objectionPolicy":{"type":"string","enum":["block","owner_decision","ignore"]},"blockersBlock":{"type":"boolean"},"ownerOverrideAllowed":{"type":"boolean"},"countOwnerAgreement":{"type":"boolean"},"countAgentSignals":{"type":"boolean"},"autoApplyAcceptedThreads":{"type":"boolean"},"staleOnNewActivity":{"type":"boolean"},"decisionPollCompletion":{"type":"string","enum":["closed","threshold"]}},"additionalProperties":true},"ConsensusDecisionRequest":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["accepted_for_change","rejected","out_of_scope","clear"]},"reason":{"type":["string","null"]},"agentAlias":{"type":["string","null"]}},"additionalProperties":false},"DraftGitBase":{"type":["object","null"],"properties":{"provider":{"type":"string","enum":["github"]},"owner":{"type":"string"},"repo":{"type":"string"},"ref":{"type":["string","null"]},"sha":{"type":["string","null"]},"path":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":true}},"additionalProperties":true},"DraftReviewFileInput":{"type":"object","properties":{"path":{"type":"string"},"fileId":{"type":"string"},"content":{"type":"string"},"contentType":{"type":"string","enum":["markdown","html","plain_text","auto"]}},"additionalProperties":false},"CreateDraftReviewRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"mode":{"type":"string","enum":["draft","brainstorming"]},"sourceType":{"type":"string","enum":["api","mcp","cli","agent_api"]},"files":{"type":"array","items":{"$ref":"#/components/schemas/DraftReviewFileInput"}},"gitBase":{"$ref":"#/components/schemas/DraftGitBase"},"base":{"$ref":"#/components/schemas/DraftGitBase"}},"additionalProperties":false},"PatchDraftReviewRequest":{"type":"object","properties":{"title":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","archived",null]},"mode":{"type":["string","null"],"enum":["draft","brainstorming",null]},"gitBase":{"$ref":"#/components/schemas/DraftGitBase"},"base":{"$ref":"#/components/schemas/DraftGitBase"}},"additionalProperties":false},"DraftReview":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"mode":{"type":"string","enum":["draft","brainstorming"]},"description":{"type":["string","null"]},"sourceType":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"visibility":{"type":"string"},"gitBase":{"$ref":"#/components/schemas/DraftGitBase"},"reviewUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"planOfRecordRevision":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"revisionNumber":{"type":"number"},"summary":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":true},{"type":"null"}]},"files":{"type":"array","items":{"$ref":"#/components/schemas/DraftReviewFile"}},"latestRevision":{"oneOf":[{"$ref":"#/components/schemas/DraftRevision"},{"type":"null"}]}},"additionalProperties":true},"DraftReviewFile":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"displayName":{"type":"string"},"contentType":{"type":"string","enum":["markdown","html","plain_text"]},"currentRevisionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"DraftRevision":{"type":"object","properties":{"id":{"type":"string"},"revisionNumber":{"type":"integer"},"label":{"type":"string"},"origin":{"type":"string"},"summary":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"files":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"DraftRevisionUploadRequest":{"type":"object","required":["files"],"properties":{"summary":{"type":"string"},"sourceType":{"type":"string","enum":["api","mcp","cli","agent_api"]},"files":{"type":"array","items":{"$ref":"#/components/schemas/DraftReviewFileInput"}},"addressedThreadIds":{"type":"array","items":{"type":"string"},"description":"Brainstorming Review thread ids to mark addressed after the literal-content revision is accepted. Requires commentary.comments.status."}},"additionalProperties":false},"CreateDraftCommentRequest":{"type":"object","required":["blockId","nodeType","sourceLineStart","sourceLineEnd","bodyMarkdown"],"properties":{"fileId":{"type":["string","null"]},"filePath":{"type":["string","null"]},"blockId":{"type":"string"},"nodeType":{"type":"string"},"sourceLineStart":{"type":"integer"},"sourceLineEnd":{"type":"integer"},"selectedText":{"type":["string","null"]},"prefixText":{"type":["string","null"]},"suffixText":{"type":["string","null"]},"bodyMarkdown":{"type":"string"},"agentAlias":{"type":["string","null"]}},"additionalProperties":false},"CreateDraftShareRequest":{"type":"object","properties":{"audience":{"type":"string","enum":["anyone","user"],"default":"anyone"},"recipient":{"type":"string"}},"additionalProperties":false},"WebAppReviewRepo":{"type":"object","properties":{"provider":{"type":["string","null"]},"owner":{"type":["string","null"]},"name":{"type":["string","null"]},"branch":{"type":["string","null"]},"commitSha":{"type":["string","null"]},"deploymentId":{"type":["string","null"]},"buildId":{"type":["string","null"]}},"additionalProperties":false},"WebAppReviewPrincipalIdentity":{"type":"object","properties":{"viewerId":{"type":["string","null"]},"providerAccountId":{"type":["string","null"]},"login":{"type":["string","null"]}},"additionalProperties":false},"WebAppReview":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"owner":{"$ref":"#/components/schemas/WebAppReviewPrincipalIdentity"},"currentUser":{"$ref":"#/components/schemas/WebAppReviewPrincipalIdentity"},"sourceType":{"type":"string","enum":["deployed_url","localhost"]},"previewUrl":{"type":"string","format":"uri"},"previewOrigin":{"type":"string"},"repo":{"$ref":"#/components/schemas/WebAppReviewRepo"},"status":{"type":"string","enum":["active","archived"]},"reviewUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"CreateWebAppReviewRequest":{"type":"object","required":["title","sourceType","previewUrl"],"properties":{"title":{"type":"string"},"sourceType":{"type":"string","enum":["deployed_url","localhost"]},"previewUrl":{"type":"string","format":"uri"},"repo":{"$ref":"#/components/schemas/WebAppReviewRepo"},"externalMetadata":{"type":"object","additionalProperties":true}},"additionalProperties":false},"PatchWebAppReviewRequest":{"type":"object","properties":{"title":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","archived",null]},"repo":{"$ref":"#/components/schemas/WebAppReviewRepo"},"externalMetadata":{"type":"object","additionalProperties":true}},"additionalProperties":false},"WebAppElementContextInput":{"type":"object","required":["route","url","origin","selector","fallbackSelector","tagName","boundingRect","viewport"],"properties":{"route":{"type":"string"},"url":{"type":"string","format":"uri"},"origin":{"type":"string"},"selector":{"type":"string"},"fallbackSelector":{"type":"string"},"tagName":{"type":"string"},"role":{"type":["string","null"]},"accessibleName":{"type":["string","null"]},"textSnippet":{"type":["string","null"]},"boundingRect":{"type":"object","additionalProperties":true},"viewport":{"type":"object","additionalProperties":true},"component":{"type":["object","null"],"additionalProperties":true},"commitSha":{"type":["string","null"]}},"additionalProperties":false},"WebAppScreenshotContextInput":{"type":"object","required":["targetKind","route","url","origin","viewport","screenshot"],"properties":{"targetKind":{"const":"screenshot"},"route":{"type":"string"},"url":{"type":"string","format":"uri"},"origin":{"type":"string"},"viewport":{"type":"object","additionalProperties":true},"screenshot":{"type":"object","required":["mimeType","width","height","screenshotRect","cursorPage","cursorImage"],"properties":{"mimeType":{"type":"string","enum":["image/png","image/jpeg","image/webp"]},"dataUrl":{"type":"string"},"base64":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"screenshotRect":{"type":"object","additionalProperties":true},"cursorPage":{"type":"object","additionalProperties":true},"cursorImage":{"type":"object","additionalProperties":true}},"additionalProperties":true},"commitSha":{"type":["string","null"]}},"additionalProperties":false},"CreateWebAppReviewCommentRequest":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/WebAppElementContextInput"},{"type":"object","required":["bodyMarkdown"],"properties":{"targetKind":{"type":"string","enum":["element"]},"bodyMarkdown":{"type":"string"},"reviewSessionId":{"type":["string","null"]}},"additionalProperties":false}]},{"allOf":[{"$ref":"#/components/schemas/WebAppScreenshotContextInput"},{"type":"object","required":["bodyMarkdown"],"properties":{"bodyMarkdown":{"type":"string"},"reviewSessionId":{"type":["string","null"]}},"additionalProperties":false}]}]},"WebAppReviewComment":{"type":"object","properties":{"id":{"type":"string"},"threadId":{"type":"string"},"reviewId":{"type":"string"},"targetKind":{"type":"string","enum":["element","screenshot"]},"bodyMarkdown":{"type":"string"},"status":{"type":"string","enum":["open","resolved"]},"route":{"type":"string"},"url":{"type":"string"},"selector":{"type":"string"},"fallbackSelector":{"type":"string"},"element":{"type":"object","additionalProperties":true},"boundingRect":{"type":"object","additionalProperties":true},"viewport":{"type":"object","additionalProperties":true},"component":{"type":["object","null"],"additionalProperties":true},"screenshot":{"type":["object","null"],"additionalProperties":true},"commitSha":{"type":["string","null"]},"author":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"WebAppReviewAgentContext":{"type":"object","properties":{"ok":{"const":true},"review":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"web_app"},"owner":{"$ref":"#/components/schemas/WebAppReviewPrincipalIdentity"},"currentUser":{"$ref":"#/components/schemas/WebAppReviewPrincipalIdentity"}},"additionalProperties":true},"comments":{"type":"array","items":{"type":"object","properties":{"type":{"const":"web_app_review_comment"},"security":{"type":"object","properties":{"untrusted":{"const":true},"warning":{"type":"string"}},"required":["untrusted","warning"]}},"additionalProperties":true}}},"additionalProperties":true},"BrainReview":{"type":"object","additionalProperties":true},"BrainEvaluation":{"type":"object","additionalProperties":true},"BrainEvaluationRequest":{"type":"object","properties":{"provider":{"type":"string","enum":["github"]},"owner":{"type":"string"},"repo":{"type":"string"},"prNumber":{"type":["integer","null"]},"branchRef":{"type":["string","null"]},"rootFolder":{"type":["string","null"]},"id":{"type":["string","null"]},"question":{"type":["string","null"]},"expectedAnswer":{"type":["string","null"]},"expectedSourcePages":{},"actualAnswer":{"type":["string","null"]},"retrievedPages":{},"grade":{},"reviewerNotes":{"type":["string","null"]}},"additionalProperties":false},"BrainReadyRequest":{"type":"object","properties":{"threadId":{"type":"string"},"bodyMarkdown":{"type":["string","null"]}},"additionalProperties":false},"McpJsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","number","null"]},"method":{"type":"string","enum":["initialize","notifications/initialized","tools/list","tools/call"]},"params":{"type":"object","additionalProperties":true}},"additionalProperties":true},"McpToolsList":{"type":"object","required":["tools"],"properties":{"tools":{"type":"array","items":{"type":"object","required":["name","description","inputSchema"],"properties":{"name":{"type":"string","enum":["commentary_forms","draft_review","review_comments","web_app_review","review_participants","review_polls","review_document","brain_review"]},"description":{"type":"string"},"inputSchema":{"type":"object","additionalProperties":true}}}}}}}}}