openapi: 3.2.0 info: title: V12 Findings API version: 2.0.0 description: Findings, runs and context documents of one V12 organization. Every path but /me sits under /orgs/{org}, where {org} is the organization's slug (GET /me returns it); a token reaches only its own organization, and any other slug answers 404. servers: - url: https://v12.sh/api/v2 tags: - name: Findings paths: /orgs/{org}/repositories/{owner}/{repo}/findings: get: operationId: listRepositoryFindings summary: List a repository's findings at a position description: 'The repository inbox at one commit: every finding with its code state there. Without at, the default branch head. The response pins the evaluated commit in position.at; later pages stay on it. Highest finding number first; counts are before filters, total after.' tags: - Findings security: - bearer: [] - oauth2: - findings:read x-mcp-tool: list_repository_findings parameters: - name: org in: path required: true description: Organization slug; must be the token's organization. schema: type: string - name: owner in: path required: true description: Repository owner. schema: type: string - name: repo in: path required: true description: Repository name. schema: type: string - name: at in: query required: false schema: type: string maxLength: 512 description: 'Repository position: "default", "branch:[@]", "pr:[@]" or "commit:". Omitted means "default".' - name: status in: query required: false schema: maxItems: 6 type: array items: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate style: form explode: false - name: severity in: query required: false schema: maxItems: 5 type: array items: type: string enum: - info - low - medium - high - critical style: form explode: false - name: assignee in: query required: false schema: description: '"me", "none", a member email, or a member username. A username several members share matches all of them.' type: string minLength: 1 maxLength: 320 - name: steer in: query required: false schema: type: string minLength: 1 maxLength: 200 description: Steer slug. - name: limit in: query required: false schema: default: 50 type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false schema: type: string minLength: 1 maxLength: 2048 description: '`nextCursor` from the previous page.' responses: '200': description: List a repository's findings at a position content: application/json: schema: type: object properties: nextCursor: anyOf: - type: string - type: 'null' items: type: array items: type: object properties: number: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Number within the organization, e.g. 42. key: type: string description: Display key, e.g. "F-42". title: type: string severity: type: string enum: - info - low - medium - high - critical status: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate investigating: type: boolean decision: anyOf: - type: object properties: kind: type: string enum: - wont-fix - risk-accepted reason: type: string required: - kind - reason additionalProperties: false - type: 'null' duplicateOf: anyOf: - type: string - type: 'null' description: Key of the finding this one duplicates. assignee: anyOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' required: - username - email additionalProperties: false - type: 'null' steer: anyOf: - type: object properties: slug: type: string title: type: string required: - slug - title additionalProperties: false - type: 'null' firstObservedAt: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ reportCount: type: integer minimum: 0 maximum: 9007199254740991 sources: type: array items: type: string enum: - agent - user - integration runs: type: array items: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 repositories: type: array items: type: object properties: repository: type: object properties: slug: type: string fullName: type: string required: - slug - fullName additionalProperties: false position: type: object properties: at: type: string description: Pinned position; send it back to stay on this commit. kind: type: string enum: - branch - pull-request - commit branch: anyOf: - type: string - type: 'null' pullRequest: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' sha: type: string isDefault: type: boolean required: - at - kind - branch - pullRequest - sha - isDefault additionalProperties: false codeState: type: string enum: - present - needs-check - absent - conflicting - false-positive paths: anyOf: - type: array items: type: string - type: 'null' comparison: anyOf: - type: string enum: - not-compared - introduced-here - inherited-from-base - type: 'null' required: - repository - position - codeState - paths - comparison additionalProperties: false webUrl: type: string required: - number - key - title - severity - status - investigating - decision - duplicateOf - assignee - steer - firstObservedAt - reportCount - sources - runs - repositories - webUrl additionalProperties: false repository: type: object properties: slug: type: string fullName: type: string required: - slug - fullName additionalProperties: false position: type: object properties: at: type: string description: Pinned position; send it back to stay on this commit. kind: type: string enum: - branch - pull-request - commit branch: anyOf: - type: string - type: 'null' pullRequest: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' sha: type: string isDefault: type: boolean required: - at - kind - branch - pullRequest - sha - isDefault additionalProperties: false reviewCoverage: type: object properties: state: type: string enum: - never-reviewed - reviewed - partially-reviewed - behind run: anyOf: - type: integer exclusiveMinimum: 0 maximum: 2147483647 - type: 'null' description: Number of the run the coverage comes from. commitsBehind: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' required: - state - run - commitsBehind additionalProperties: false counts: type: object properties: byStatus: type: object propertyNames: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate additionalProperties: type: integer minimum: 0 maximum: 9007199254740991 required: - open - investigating - fixed - wont-fix - false-positive - duplicate bySeverity: type: object propertyNames: type: string enum: - info - low - medium - high - critical additionalProperties: type: integer minimum: 0 maximum: 9007199254740991 required: - info - low - medium - high - critical required: - byStatus - bySeverity additionalProperties: false total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 asOf: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - nextCursor - items - repository - position - reviewCoverage - counts - total - asOf additionalProperties: false '400': description: The request is invalid content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '401': description: Missing or invalid bearer token content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '403': description: The token lacks a scope, or its user lacks a permission content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '404': description: Not found in the token organization content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '409': description: The request conflicts with the current state content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '429': description: Rate limited; see Retry-After content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '503': description: Temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' /orgs/{org}/findings: get: operationId: listFindings summary: List organization findings description: Findings across every registered repository at its default branch head, highest finding number first (numbers grow as findings are created; firstObservedAt can be older). counts covers every finding before filters; total counts the filtered result. unavailableRepositories lists the slugs of repositories whose default branch V12 cannot read; list_repository_findings on one says why. tags: - Findings security: - bearer: [] - oauth2: - findings:read x-mcp-tool: list_findings parameters: - name: org in: path required: true description: Organization slug; must be the token's organization. schema: type: string - name: status in: query required: false schema: maxItems: 6 type: array items: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate style: form explode: false - name: severity in: query required: false schema: maxItems: 5 type: array items: type: string enum: - info - low - medium - high - critical style: form explode: false - name: assignee in: query required: false schema: description: '"me", "none", a member email, or a member username. A username several members share matches all of them.' type: string minLength: 1 maxLength: 320 - name: steer in: query required: false schema: type: string minLength: 1 maxLength: 200 description: Steer slug. - name: limit in: query required: false schema: default: 50 type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false schema: type: string minLength: 1 maxLength: 2048 description: '`nextCursor` from the previous page.' responses: '200': description: List organization findings content: application/json: schema: type: object properties: nextCursor: anyOf: - type: string - type: 'null' items: type: array items: type: object properties: number: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Number within the organization, e.g. 42. key: type: string description: Display key, e.g. "F-42". title: type: string severity: type: string enum: - info - low - medium - high - critical status: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate investigating: type: boolean decision: anyOf: - type: object properties: kind: type: string enum: - wont-fix - risk-accepted reason: type: string required: - kind - reason additionalProperties: false - type: 'null' duplicateOf: anyOf: - type: string - type: 'null' description: Key of the finding this one duplicates. assignee: anyOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' required: - username - email additionalProperties: false - type: 'null' steer: anyOf: - type: object properties: slug: type: string title: type: string required: - slug - title additionalProperties: false - type: 'null' firstObservedAt: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ reportCount: type: integer minimum: 0 maximum: 9007199254740991 sources: type: array items: type: string enum: - agent - user - integration runs: type: array items: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 repositories: type: array items: type: object properties: repository: type: object properties: slug: type: string fullName: type: string required: - slug - fullName additionalProperties: false position: type: object properties: at: type: string description: Pinned position; send it back to stay on this commit. kind: type: string enum: - branch - pull-request - commit branch: anyOf: - type: string - type: 'null' pullRequest: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' sha: type: string isDefault: type: boolean required: - at - kind - branch - pullRequest - sha - isDefault additionalProperties: false codeState: type: string enum: - present - needs-check - absent - conflicting - false-positive paths: anyOf: - type: array items: type: string - type: 'null' comparison: anyOf: - type: string enum: - not-compared - introduced-here - inherited-from-base - type: 'null' required: - repository - position - codeState - paths - comparison additionalProperties: false webUrl: type: string required: - number - key - title - severity - status - investigating - decision - duplicateOf - assignee - steer - firstObservedAt - reportCount - sources - runs - repositories - webUrl additionalProperties: false counts: type: object properties: byStatus: type: object propertyNames: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate additionalProperties: type: integer minimum: 0 maximum: 9007199254740991 required: - open - investigating - fixed - wont-fix - false-positive - duplicate bySeverity: type: object propertyNames: type: string enum: - info - low - medium - high - critical additionalProperties: type: integer minimum: 0 maximum: 9007199254740991 required: - info - low - medium - high - critical required: - byStatus - bySeverity additionalProperties: false total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 asOf: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' unavailableRepositories: type: array items: type: string description: Slugs of registered repositories whose default branch V12 cannot read. required: - nextCursor - items - counts - total - asOf - unavailableRepositories additionalProperties: false '400': description: The request is invalid content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '401': description: Missing or invalid bearer token content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '403': description: The token lacks a scope, or its user lacks a permission content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '404': description: Not found in the token organization content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '409': description: The request conflicts with the current state content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '429': description: Rate limited; see Retry-After content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '503': description: Temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' patch: operationId: updateFindings summary: Change findings description: 'Apply one change to up to 100 findings: status (with reason), severity, or assignee. fixed and open are recorded at a commit (the default branch head unless repository/at say otherwise) and carry forward to later commits while the affected files are unchanged; false-positive marks the finding''s reports and shows at every commit that has them; investigating and wont-fix apply everywhere. Findings already in the requested state are left unchanged and listed in skipped.' tags: - Findings security: - bearer: [] - oauth2: - findings:write x-mcp-tool: update_findings parameters: - name: org in: path required: true description: Organization slug; must be the token's organization. schema: type: string - name: repository in: query required: false schema: description: Needed with `at` when a finding spans several repositories. type: string pattern: ^[^/\s]+\/[^/\s]+$ - name: at in: query required: false schema: type: string maxLength: 512 description: 'Repository position: "default", "branch:[@]", "pr:[@]" or "commit:". Omitted means "default".' requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: findings: minItems: 1 maxItems: 100 type: array items: type: string pattern: ^(?:[Ff]-)?[1-9][0-9]{0,15}$ description: Finding key such as "F-42", or its number. status: description: fixed and open apply at a commit and carry forward; false-positive marks the finding's reports; investigating and wont-fix apply everywhere. type: string enum: - open - investigating - fixed - wont-fix - false-positive reason: description: Required with status. type: string minLength: 1 maxLength: 5000 severity: type: string enum: - info - low - medium - high - critical assignee: description: '"me", a member email, a member username, or null or "none" to unassign. A username several members share is refused; use the email.' anyOf: - type: string minLength: 1 maxLength: 320 - type: 'null' required: - findings responses: '200': description: Change findings content: application/json: schema: type: object properties: findings: type: array items: type: object properties: number: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Number within the organization, e.g. 42. key: type: string description: Display key, e.g. "F-42". title: type: string severity: type: string enum: - info - low - medium - high - critical status: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate investigating: type: boolean decision: anyOf: - type: object properties: kind: type: string enum: - wont-fix - risk-accepted reason: type: string required: - kind - reason additionalProperties: false - type: 'null' duplicateOf: anyOf: - type: string - type: 'null' description: Key of the finding this one duplicates. assignee: anyOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' required: - username - email additionalProperties: false - type: 'null' steer: anyOf: - type: object properties: slug: type: string title: type: string required: - slug - title additionalProperties: false - type: 'null' firstObservedAt: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ reportCount: type: integer minimum: 0 maximum: 9007199254740991 sources: type: array items: type: string enum: - agent - user - integration runs: type: array items: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 repositories: type: array items: type: object properties: repository: type: object properties: slug: type: string fullName: type: string required: - slug - fullName additionalProperties: false position: type: object properties: at: type: string description: Pinned position; send it back to stay on this commit. kind: type: string enum: - branch - pull-request - commit branch: anyOf: - type: string - type: 'null' pullRequest: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' sha: type: string isDefault: type: boolean required: - at - kind - branch - pullRequest - sha - isDefault additionalProperties: false codeState: type: string enum: - present - needs-check - absent - conflicting - false-positive paths: anyOf: - type: array items: type: string - type: 'null' comparison: anyOf: - type: string enum: - not-compared - introduced-here - inherited-from-base - type: 'null' required: - repository - position - codeState - paths - comparison additionalProperties: false webUrl: type: string required: - number - key - title - severity - status - investigating - decision - duplicateOf - assignee - steer - firstObservedAt - reportCount - sources - runs - repositories - webUrl additionalProperties: false skipped: type: array items: type: string description: 'Keys of requested findings already in the requested state: left unchanged, still listed in findings.' asOf: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - findings - skipped - asOf additionalProperties: false '400': description: The request is invalid content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '401': description: Missing or invalid bearer token content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '403': description: The token lacks a scope, or its user lacks a permission content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '404': description: Not found in the token organization content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '409': description: The request conflicts with the current state content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '413': description: The body exceeds 1 MiB content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '415': description: The body is not application/json content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '429': description: Rate limited; see Retry-After content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '503': description: Temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' /orgs/{org}/findings/{finding}: get: operationId: getFinding summary: Get a finding description: One finding with its reports (each report's analysis, proof of concept and fix are in reports[].analysis), evidence and activity. Comments are activity entries of kind "comment"; their id is the replyTo for comment_on_finding. A false-positive change shows in status, not in activity. With at, code state and status are read at that commit. Send a returned position.at with its repositories[i].repository; without repository, inference reports repository_required if several registered repositories hold the finding at that position. tags: - Findings security: - bearer: [] - oauth2: - findings:read x-mcp-tool: get_finding parameters: - name: org in: path required: true description: Organization slug; must be the token's organization. schema: type: string - name: finding in: path required: true schema: type: string pattern: ^(?:[Ff]-)?[1-9][0-9]{0,15}$ description: Finding key such as "F-42", or its number. - name: repository in: query required: false schema: type: string pattern: ^[^/\s]+\/[^/\s]+$ description: Repository slug or full name, "owner/name". - name: at in: query required: false schema: type: string maxLength: 512 description: 'Repository position: "default", "branch:[@]", "pr:[@]" or "commit:". Omitted means "default".' responses: '200': description: Get a finding content: application/json: schema: type: object properties: number: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Number within the organization, e.g. 42. key: type: string description: Display key, e.g. "F-42". title: type: string severity: type: string enum: - info - low - medium - high - critical status: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate investigating: type: boolean decision: anyOf: - type: object properties: kind: type: string enum: - wont-fix - risk-accepted reason: type: string required: - kind - reason additionalProperties: false - type: 'null' duplicateOf: anyOf: - type: string - type: 'null' description: Key of the finding this one duplicates. assignee: anyOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' required: - username - email additionalProperties: false - type: 'null' steer: anyOf: - type: object properties: slug: type: string title: type: string required: - slug - title additionalProperties: false - type: 'null' firstObservedAt: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ reportCount: type: integer minimum: 0 maximum: 9007199254740991 sources: type: array items: type: string enum: - agent - user - integration runs: type: array items: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 repositories: type: array items: type: object properties: repository: type: object properties: slug: type: string fullName: type: string required: - slug - fullName additionalProperties: false position: type: object properties: at: type: string description: Pinned position; send it back to stay on this commit. kind: type: string enum: - branch - pull-request - commit branch: anyOf: - type: string - type: 'null' pullRequest: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' sha: type: string isDefault: type: boolean required: - at - kind - branch - pullRequest - sha - isDefault additionalProperties: false codeState: type: string enum: - present - needs-check - absent - conflicting - false-positive paths: anyOf: - type: array items: type: string - type: 'null' comparison: anyOf: - type: string enum: - not-compared - introduced-here - inherited-from-base - type: 'null' required: - repository - position - codeState - paths - comparison additionalProperties: false webUrl: type: string description: type: string reports: type: array items: type: object properties: id: type: string title: type: string description: type: string analysis: anyOf: - type: object properties: impact: anyOf: - type: string - type: 'null' rootCause: anyOf: - type: string - type: 'null' reasoning: anyOf: - type: string - type: 'null' triage: anyOf: - type: object properties: verdict: type: string enum: - valid - irrelevant - invalid category: type: string reasoning: type: string required: - verdict - category - reasoning additionalProperties: false - type: 'null' proofOfConcept: anyOf: - type: object properties: status: type: string classification: anyOf: - type: string enum: - in-scope - out-of-scope - type: 'null' verdict: anyOf: - type: string enum: - confirmed - failed - invalid - error - harness-unavailable - type: 'null' reproductionSteps: type: array items: type: string preconditions: type: array items: type: string testFile: anyOf: - type: string - type: 'null' testCase: anyOf: - type: string - type: 'null' testCommand: anyOf: - type: string - type: 'null' limitations: anyOf: - type: string - type: 'null' required: - status - classification - verdict - reproductionSteps - preconditions - testFile - testCase - testCommand - limitations additionalProperties: false - type: 'null' fix: anyOf: - type: object properties: status: type: string explanation: anyOf: - type: string - type: 'null' patch: anyOf: - type: string - type: 'null' affectedFiles: type: array items: type: string required: - status - explanation - patch - affectedFiles additionalProperties: false - type: 'null' required: - impact - rootCause - reasoning - triage - proofOfConcept - fix additionalProperties: false - type: 'null' required: - id - title - description - analysis additionalProperties: false evidence: type: array items: type: object properties: report: type: string repository: type: string sha: type: string path: type: string startLine: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' endLine: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' note: anyOf: - type: string - type: 'null' snippet: anyOf: - type: string - type: 'null' required: - report - repository - sha - path - startLine - endLine - note - snippet additionalProperties: false activity: type: array items: oneOf: - type: object properties: id: type: string at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ actor: anyOf: - oneOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' kind: type: string const: user required: - username - email - kind additionalProperties: false - type: object properties: kind: type: string const: agent name: type: string run: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' required: - kind - name - run additionalProperties: false - type: object properties: kind: type: string const: service name: type: string required: - kind - name additionalProperties: false - type: 'null' kind: type: string const: created required: - id - at - actor - kind additionalProperties: false - type: object properties: id: type: string at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ actor: anyOf: - oneOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' kind: type: string const: user required: - username - email - kind additionalProperties: false - type: object properties: kind: type: string const: agent name: type: string run: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' required: - kind - name - run additionalProperties: false - type: object properties: kind: type: string const: service name: type: string required: - kind - name additionalProperties: false - type: 'null' kind: type: string const: report-added report: type: string required: - id - at - actor - kind - report additionalProperties: false - type: object properties: id: type: string at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ actor: anyOf: - oneOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' kind: type: string const: user required: - username - email - kind additionalProperties: false - type: object properties: kind: type: string const: agent name: type: string run: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' required: - kind - name - run additionalProperties: false - type: object properties: kind: type: string const: service name: type: string required: - kind - name additionalProperties: false - type: 'null' kind: type: string const: assessed result: type: string enum: - present - absent - inconclusive reason: anyOf: - type: string - type: 'null' required: - id - at - actor - kind - result - reason additionalProperties: false - type: object properties: id: type: string at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ actor: anyOf: - oneOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' kind: type: string const: user required: - username - email - kind additionalProperties: false - type: object properties: kind: type: string const: agent name: type: string run: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' required: - kind - name - run additionalProperties: false - type: object properties: kind: type: string const: service name: type: string required: - kind - name additionalProperties: false - type: 'null' kind: type: string enum: - marked-fixed - marked-present repositories: type: array items: type: object properties: repository: type: string sha: type: string required: - repository - sha additionalProperties: false reason: type: string required: - id - at - actor - kind - repositories - reason additionalProperties: false - type: object properties: id: type: string at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ actor: anyOf: - oneOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' kind: type: string const: user required: - username - email - kind additionalProperties: false - type: object properties: kind: type: string const: agent name: type: string run: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' required: - kind - name - run additionalProperties: false - type: object properties: kind: type: string const: service name: type: string required: - kind - name additionalProperties: false - type: 'null' kind: type: string const: assessment-undone required: - id - at - actor - kind additionalProperties: false - type: object properties: id: type: string at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ actor: anyOf: - oneOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' kind: type: string const: user required: - username - email - kind additionalProperties: false - type: object properties: kind: type: string const: agent name: type: string run: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' required: - kind - name - run additionalProperties: false - type: object properties: kind: type: string const: service name: type: string required: - kind - name additionalProperties: false - type: 'null' kind: type: string const: changed field: type: string enum: - severity - assignee - investigation - steer - decision - duplicate value: anyOf: - type: string - type: 'null' required: - id - at - actor - kind - field - value additionalProperties: false - type: object properties: id: type: string at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ actor: anyOf: - oneOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' kind: type: string const: user required: - username - email - kind additionalProperties: false - type: object properties: kind: type: string const: agent name: type: string run: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' required: - kind - name - run additionalProperties: false - type: object properties: kind: type: string const: service name: type: string required: - kind - name additionalProperties: false - type: 'null' kind: type: string const: comment body: type: string replyTo: anyOf: - type: string - type: 'null' required: - id - at - actor - kind - body - replyTo additionalProperties: false related: type: array items: type: object properties: key: type: string title: type: string relationship: type: string const: duplicate required: - key - title - relationship additionalProperties: false asOf: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - number - key - title - severity - status - investigating - decision - duplicateOf - assignee - steer - firstObservedAt - reportCount - sources - runs - repositories - webUrl - description - reports - evidence - activity - related - asOf additionalProperties: false '400': description: The request is invalid content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '401': description: Missing or invalid bearer token content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '403': description: The token lacks a scope, or its user lacks a permission content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '404': description: Not found in the token organization content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '409': description: The request conflicts with the current state content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '429': description: Rate limited; see Retry-After content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '503': description: Temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' patch: operationId: updateFinding summary: Change a finding description: 'Apply one change to a finding: status (with reason), severity, or assignee. A change that would not alter the finding leaves it unchanged and lists it in skipped.' tags: - Findings security: - bearer: [] - oauth2: - findings:write parameters: - name: org in: path required: true description: Organization slug; must be the token's organization. schema: type: string - name: finding in: path required: true schema: type: string pattern: ^(?:[Ff]-)?[1-9][0-9]{0,15}$ description: Finding key such as "F-42", or its number. - name: repository in: query required: false schema: description: Needed with `at` when a finding spans several repositories. type: string pattern: ^[^/\s]+\/[^/\s]+$ - name: at in: query required: false schema: type: string maxLength: 512 description: 'Repository position: "default", "branch:[@]", "pr:[@]" or "commit:". Omitted means "default".' requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: status: description: fixed and open apply at a commit and carry forward; false-positive marks the finding's reports; investigating and wont-fix apply everywhere. type: string enum: - open - investigating - fixed - wont-fix - false-positive reason: description: Required with status. type: string minLength: 1 maxLength: 5000 severity: type: string enum: - info - low - medium - high - critical assignee: description: '"me", a member email, a member username, or null or "none" to unassign. A username several members share is refused; use the email.' anyOf: - type: string minLength: 1 maxLength: 320 - type: 'null' required: [] responses: '200': description: Change a finding content: application/json: schema: type: object properties: findings: type: array items: type: object properties: number: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Number within the organization, e.g. 42. key: type: string description: Display key, e.g. "F-42". title: type: string severity: type: string enum: - info - low - medium - high - critical status: type: string enum: - open - investigating - fixed - wont-fix - false-positive - duplicate investigating: type: boolean decision: anyOf: - type: object properties: kind: type: string enum: - wont-fix - risk-accepted reason: type: string required: - kind - reason additionalProperties: false - type: 'null' duplicateOf: anyOf: - type: string - type: 'null' description: Key of the finding this one duplicates. assignee: anyOf: - type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' required: - username - email additionalProperties: false - type: 'null' steer: anyOf: - type: object properties: slug: type: string title: type: string required: - slug - title additionalProperties: false - type: 'null' firstObservedAt: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ reportCount: type: integer minimum: 0 maximum: 9007199254740991 sources: type: array items: type: string enum: - agent - user - integration runs: type: array items: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 repositories: type: array items: type: object properties: repository: type: object properties: slug: type: string fullName: type: string required: - slug - fullName additionalProperties: false position: type: object properties: at: type: string description: Pinned position; send it back to stay on this commit. kind: type: string enum: - branch - pull-request - commit branch: anyOf: - type: string - type: 'null' pullRequest: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' sha: type: string isDefault: type: boolean required: - at - kind - branch - pullRequest - sha - isDefault additionalProperties: false codeState: type: string enum: - present - needs-check - absent - conflicting - false-positive paths: anyOf: - type: array items: type: string - type: 'null' comparison: anyOf: - type: string enum: - not-compared - introduced-here - inherited-from-base - type: 'null' required: - repository - position - codeState - paths - comparison additionalProperties: false webUrl: type: string required: - number - key - title - severity - status - investigating - decision - duplicateOf - assignee - steer - firstObservedAt - reportCount - sources - runs - repositories - webUrl additionalProperties: false skipped: type: array items: type: string description: 'Keys of requested findings already in the requested state: left unchanged, still listed in findings.' asOf: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - findings - skipped - asOf additionalProperties: false '400': description: The request is invalid content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '401': description: Missing or invalid bearer token content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '403': description: The token lacks a scope, or its user lacks a permission content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '404': description: Not found in the token organization content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '409': description: The request conflicts with the current state content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '413': description: The body exceeds 1 MiB content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '415': description: The body is not application/json content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '429': description: Rate limited; see Retry-After content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '503': description: Temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' /orgs/{org}/findings/{finding}/comments: post: operationId: commentOnFinding summary: Comment on a finding description: Add a comment, or a reply to one, to a finding. tags: - Findings security: - bearer: [] - oauth2: - findings:write x-mcp-tool: comment_on_finding parameters: - name: org in: path required: true description: Organization slug; must be the token's organization. schema: type: string - name: finding in: path required: true schema: type: string pattern: ^(?:[Ff]-)?[1-9][0-9]{0,15}$ description: Finding key such as "F-42", or its number. - name: Idempotency-Key in: header required: false description: 'Repeat a request safely: the same key and body return the original result.' schema: type: string minLength: 1 maxLength: 255 requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: body: type: string minLength: 1 maxLength: 20000 replyTo: description: Comment id to reply to. type: string minLength: 1 maxLength: 255 required: - body responses: '201': description: Comment on a finding content: application/json: schema: type: object properties: comment: type: object properties: id: type: string author: type: object properties: username: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' required: - username - email additionalProperties: false body: type: string replyTo: anyOf: - type: string - type: 'null' createdAt: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ required: - id - author - body - replyTo - createdAt additionalProperties: false required: - comment additionalProperties: false '400': description: The request is invalid content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '401': description: Missing or invalid bearer token content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '403': description: The token lacks a scope, or its user lacks a permission content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '404': description: Not found in the token organization content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '409': description: The request conflicts with the current state content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '413': description: The body exceeds 1 MiB content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '415': description: The body is not application/json content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '429': description: Rate limited; see Retry-After content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '503': description: Temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' components: schemas: ApiErrorEnvelope: type: object properties: error: type: object properties: code: type: string enum: - invalid_request - repository_required - unauthenticated - insufficient_credits - spend_cap_reached - insufficient_scope - forbidden - not_found - repository_not_visible - repository_not_added - method_not_allowed - position_unavailable - decision_active - conflict - price_exceeds_max - quote_stale - change_refused - nothing_to_review - repository_not_runnable - idempotency_key_reused - api_version_retired - payload_too_large - unsupported_media_type - rate_limited - internal_error - upstream_error - platform_unavailable - repository_access_unavailable - rate_limit_unavailable - public_api_disabled message: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false requestId: type: string required: - error - requestId additionalProperties: false securitySchemes: bearer: type: http scheme: bearer description: A personal access token (v12p_…) or an OAuth access token (v12a_…). oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://v12.sh/oauth/authorize tokenUrl: https://v12.sh/api/oauth/token refreshUrl: https://v12.sh/api/oauth/token scopes: user:read: 'The member directory: usernames, emails and roles. Any key reads its own account, organization and credit balance without it.' repos:read: Repositories, branches, pull requests, tags and Steer instructions. repos:write: Add public repositories to the workspace; owners can also add private repositories granted by GitHub, create repositories V12 hosts and push code to them. steers:write: Create, edit, archive and restore Steers. Archiving detaches them from Autopilot rules; finding tags and run history are kept. runs:read: Runs, their progress and context documents. runs:write: Estimate and start runs; add or archive context documents. runs:manage: Cancel runs. runs:share: Create, change and revoke guest links that open a run to people outside the organization. findings:read: 'The inbox: findings, their status, reports and comments.' findings:write: Change status, comment and update triage decisions.