openapi: 3.1.0
info:
  title: zkao Project API
  version: "1.0.0"
  description: |
    Project-scoped REST API for programmatically controlling a single zkao
    project with a bearer **API token** (created under Project Settings →
    Integrations, or approved through the CLI's `zkao login`).

    ## Authentication
    Send the token in the `Authorization` header: `Authorization: Bearer zkao_proj_<keyId>_<secret>`.
    The token is shown once at creation and never again. Passing the token in the
    query string is rejected.

    ## Scoping (what a token can do)
    Every token belongs to exactly one project and carries a subset of these
    **scopes**:
      - `read` — list/show repositories, scans, findings, presets
      - `findings:write` — comment, change severity, change resolution, pin a note
      - `guidance:write` — read and update a repository's guidance, and manage its audit areas
      - `scans:launch` — start a scan
      - `regression-tests:write`: generate regression tests and create their pull requests
      - `publish` — publish a finding or a scan
      - `advisories:write` — record which versions an advisory affects
      - `contacts:read` — read the advisory contact list
      - `contacts:write` — add an advisory contact
      - `automations:write` controls Continuous Security schedules, analyses, and budgets
      - `reports:write` — submit a vulnerability report to the programme

    `GET /token` tells a token which project, and which organization, it
    belongs to.

    A token may also be restricted to a subset of the project's repositories
    (a repo allowlist). Any resource outside the token's project or repo
    allowlist responds `404` (never confirmed to exist). Launching a scan
    requires the project's organization to have prepaid credits.

    ## Organizations
    Every project belongs to an **organization**, which holds the prepaid credit
    balance shared by all of its projects. Tokens stay project-scoped: the
    billing endpoints report the organization's balance as seen from this
    project, and usage attributed to this project. Projects and repositories
    also carry a `slug`, the readable segment used in app URLs
    (`/orgs/<org>/projects/<project>/repos/<repo>`).

    ## Errors
    All errors share the envelope `{ "error": { "code": "...", "message": "..." } }`.
    Identity failures (bad/expired/revoked token) collapse to a generic `401`.

    ## Polling and rate limits
    When polling a scan, honor the advisory `Retry-After` header on the scan
    response rather than polling in a tight loop. A token that sends too many
    requests receives `429` with a `Retry-After` header; back off until then.
    The official SDK's `waitForScan` does this for you.
servers:
  - url: https://zkao.io/api/v1
    description: Production
  - url: https://staging.zkao.io/api/v1
    description: Staging
security:
  - bearerAuth: []
tags:
  - name: Token
    description: The calling token and the project it belongs to
  - name: Repositories
    description: Project repositories
  - name: Scans
    description: Launch, list, and poll scans
  - name: Findings
    description: Read and triage findings
  - name: Publishing
    description: Publish findings and scans as public artifacts
  - name: Discovery
    description: Scan presets for launching
  - name: Billing
    description: The organization's prepaid credit balance, and this project's usage
  - name: Reports
    description: Incoming vulnerability reports, and investigating them
  - name: Advisories
    description: Coordinated disclosure advisories and their notification plan

paths:
  /token:
    get:
      tags: [Token]
      operationId: getTokenInfo
      summary: The calling token and its project
      description: "Any valid token may call this, whatever its scopes. Use it to learn which project (and organization) a token belongs to."
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TokenInfo" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /projects/{projectId}/repositories:
    get:
      tags: [Repositories]
      operationId: listRepositories
      summary: List repositories in the project
      description: "Requires scope: `read`. Limited to the token's repo allowlist when set."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [repositories]
                properties:
                  repositories:
                    type: array
                    items: { $ref: "#/components/schemas/Repository" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/repositories/{repositoryId}/guidance:
    get:
      tags: [Repositories]
      operationId: getRepositoryGuidance
      summary: Get a repository's guidance
      description: >-
        Requires scope: `read`. Returns the per-repo guidance configured for
        this repository. Guidance is layered on top of any `zkao.md` committed
        in the repo at scan time; a per-scan `guidance` on launch replaces this
        layer for that one scan only.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RepositoryGuidance" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
    put:
      tags: [Repositories]
      operationId: setRepositoryGuidance
      summary: Set or clear a repository's guidance
      description: >-
        Requires scope: `guidance:write`. Sets `content` as the repository's
        guidance (or clears it with `null`), recording a revision. Writing the
        same content that is already stored is a no-op (`unchanged: true`, no
        revision). Pass `expectedContent` for an optimistic compare-and-set:
        omit it for last-writer-wins, or send the content you last read (or
        `null` for "currently cleared") to get a `409` instead of clobbering a
        concurrent change.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SetGuidanceRequest" }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SetGuidanceResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/repositories/{repositoryId}/audit-areas:
    get:
      tags: [Repositories]
      operationId: listAuditAreas
      summary: List a repository's audit areas
      description: >-
        Requires scope: `read`. Audit areas are the named subsystems a scan can
        be scoped to (`auditAreaKeys` on launch). Each scan that maps the
        repository keeps the list current; sizes come from one branch's map, so
        an area that map no longer names is returned without one.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
        - name: branch
          in: query
          required: false
          schema: { type: string }
          description: Branch whose map the sizes come from. Defaults to the repository's default branch.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AuditAreaList" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
    post:
      tags: [Repositories]
      operationId: createAuditArea
      summary: Add a custom audit area
      description: >-
        Requires scope: `guidance:write`. An area is a name and a description,
        never a file list: a scan resolves it against the code at the commit it
        runs on. The `key` is derived from the name and disambiguated on
        collision.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateAuditAreaRequest" }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                required: [area]
                properties:
                  area: { $ref: "#/components/schemas/AuditArea" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/repositories/{repositoryId}/audit-areas/{areaKey}:
    delete:
      tags: [Repositories]
      operationId: deleteAuditArea
      summary: Delete a custom audit area
      description: >-
        Requires scope: `guidance:write`. Only an area with `source: custom` can
        be deleted; a discovered one is the map's own account of the repository
        and is refused with `409`. Scans that already ran keep the scope they ran
        with.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
        - name: areaKey
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DeleteAuditAreaResult" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/repositories/{repositoryId}/continuous-testing:
    get:
      tags: [Repositories]
      operationId: getContinuousTesting
      summary: Get a repository's Continuous Security schedule
      description: >-
        Requires scope: `read`. Continuous Security scans one branch on a
        schedule paid from a monthly budget. With no schedule on the branch,
        `enabled` is false and the schedule fields are null. The recommended
        monthly budget supports ongoing analysis. The minimum funds one useful analysis
        step. `availableFeatures` lists the analyses this branch offers.
        `enabledFeatures` lists the branch's selected analyses, including while paused.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
        - $ref: "#/components/parameters/ContinuousTestingBranch"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ContinuousTesting" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
    put:
      tags: [Repositories]
      operationId: setContinuousTesting
      summary: Turn Continuous Security on, change it, or pause it
      description: >-
        Requires scope: `automations:write`. Every field is optional. To start
        a schedule, send `enabled: true` with the branch and its authorized
        monthly budget. A new schedule uses `defaultMonthlyCredits` when no
        budget is given. The default is a low limit that
        funds at least one analysis step. When a month's budget is used,
        automatic analysis waits until the budget is raised or the month resets.
        The budget sets the interval smoothly from once a month to twice a day.
        A budget outside the returned minimum and maximum is refused with
        `400`. Administrators can raise the maximum monthly budget.
        `areaKeys` replaces the audit areas runs rotate through, one per run.
        Use `enableFeatures` to add analyses or `enabledFeatures` to replace
        the selection. Omit both to keep it. A selection sent without
        `enabled` or `monthlyBudgetCredits` requires an existing schedule
        and returns `409` if none exists. The resulting selection must include
        at least one analysis that can run on its own.
        `enabled: false` pauses the schedule and keeps it. A change re-arms a
        schedule that had stopped. Each run still needs spendable credits when
        it launches.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SetContinuousTestingRequest" }
            examples:
              addFormalVerification:
                summary: Add formal verification to an existing schedule
                value: { branch: main, enableFeatures: [formal-verification] }
              formalVerificationOnly:
                summary: Start or resume formal verification alone with an approved monthly budget
                value: { branch: main, enabled: true, monthlyBudgetCredits: 50000, enabledFeatures: [formal-verification] }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ContinuousTesting" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
    delete:
      tags: [Repositories]
      operationId: removeContinuousTesting
      summary: Remove a repository's Continuous Security schedule
      description: >-
        Requires scope: `automations:write`. Scans the schedule already ran
        stay. Responds `404` when the branch has no schedule.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
        - $ref: "#/components/parameters/ContinuousTestingBranch"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RemoveContinuousTestingResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/repositories/{repositoryId}/continuous-testing/prepare:
    post:
      tags: [Repositories]
      operationId: prepareContinuousTesting
      summary: Prepare a branch's next Continuous Security analysis
      description: >-
        Requires scope: `automations:write`. Plans the branch's next analysis
        without running it. It works whether automatic analysis is on or off.
        Preparing spends no credits. A preparation already in progress on the
        branch is reused. When nothing has changed since the plan was last
        prepared, the branch's conversation with zkao says so and the plan
        stays as it is.
        Responds `400` when the branch does not exist or has no active
        Continuous Security, and `409` while the repository is still being
        prepared.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [branch]
              properties:
                branch: { type: string, maxLength: 255 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [preparing]
                properties:
                  preparing: { type: boolean, enum: [true] }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/repositories/{repositoryId}/reports:
    post:
      tags: [Reports]
      operationId: submitReport
      summary: File a vulnerability report against a repository
      description: >-
        Requires scope: `reports:write`. Files a report into this project's
        security programme for an active repository belonging to the project.
        GitHub private-report intake setup and repository admin access are not
        required. The report arrives as prose and is read and split into claims
        by the same step as an imported GitHub report.


        Returns with `intakeState: PENDING`. `investigateReport` refuses a
        report until that reaches `COMPLETE`, so poll
        `/projects/{projectId}/reports` before asking for an investigation.


        Idempotent on content: the same title and body against the same
        repository name the same report, so a retried call returns the
        original with `200` rather than filing a second copy.


        Free. The reading that follows is charged to the project, and the
        investigation is charged when someone asks for it.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/RepositoryId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SubmitReportRequest" }
      responses:
        "201":
          description: Filed
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SubmitReportResult" }
        "200":
          description: Already filed, by an identical earlier call
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SubmitReportResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/scans:
    get:
      tags: [Scans]
      operationId: listScans
      summary: List scans (most recent first)
      description: "Requires scope: `read`."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PaginatedScans" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
    post:
      tags: [Scans]
      operationId: launchScan
      summary: Launch a scan
      description: |
        Requires scope: `scans:launch`. Reserves `creditBudget` credits from the
        project balance. The repo must be in the token's allowlist (when set) and
        ACTIVE. Discover valid `presetRef` values via `/scan-presets`. Each scan
        type runs a fixed set of flows. Per-token spend limits are enforced, and
        the project must have enough prepaid credits to cover the budget
        (otherwise `402`).

        A repository added moments ago may still be analyzing, in which case
        this returns `409 repository_initializing`. Wait for its `readiness` to
        be `ready` in `GET /repositories` and launch again.

        A diff scan preset audits only the change from `baseCommit` to the
        scanned commit, and requires `baseCommit`. Every other preset refuses
        it. A malformed, unknown, or misplaced base is a `400` with code
        `diff_base_required`, `diff_base_not_allowed`, or `diff_base_invalid`.
        A diff scan also needs a change to audit (otherwise `422`).

        The builtin presets come in two tiers. Flash runs one focused
        analysis, led by a flagship model when it audits the code or a change.
        Max runs every technique on flagship models. Each tier
        has a preset for the code (`builtin:Flash`, `builtin:Max`), a change
        (`builtin:Flash Diff`, `builtin:Max Diff`), open findings
        (`builtin:Flash Retriage`, `builtin:Max Retriage`) and resolved
        findings (`builtin:Flash Regression Check`,
        `builtin:Max Regression Check`). Earlier names, such as
        `builtin:Rapid Review`, `builtin:Deep Audit` and `builtin:Diff Scan`,
        still resolve.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/LaunchScanRequest" }
      responses:
        "202":
          description: Scan accepted (queued)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/LaunchScanResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/RepositoryInitializing" }
        "422": { $ref: "#/components/responses/DiffUnavailable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/scans/{scanId}:
    get:
      tags: [Scans]
      operationId: getScan
      summary: Get a single scan's status and detail
      description: >-
        Requires scope: `read`. Use for polling a launched scan. While the scan
        is not yet terminal the response carries an advisory `Retry-After`
        header telling you how long to wait before polling again; respect it
        (and back off on `429`) instead of polling in a tight loop.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/ScanId"
      responses:
        "200":
          description: OK
          headers:
            Retry-After:
              description: >-
                Advisory seconds to wait before polling again. Present only
                while the scan is still running (not for terminal scans).
              required: false
              schema: { type: integer }
          content:
            application/json:
              schema:
                type: object
                required: [scan]
                properties:
                  scan: { $ref: "#/components/schemas/ScanDetail" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/scans/{scanId}/cancel:
    post:
      tags: [Scans]
      operationId: cancelScan
      summary: Cancel a running or queued scan
      description: >-
        Requires scope: `scans:launch`. Signals any in-flight jobs to stop,
        marks the scan CANCELLED, and releases its reserved credits (in-flight
        jobs settle their actual spend as they wind down). A scan that already
        reached COMPLETED or FAILED cannot be cancelled (`400`).
        Cancellation remains available when the organization has no available credits.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/ScanId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CancelScanResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/scans/{scanId}/triage/resume:
    post:
      tags: [Scans]
      operationId: resumeTriage
      summary: Resume triage after a budget stop
      description: >-
        Requires scope: `scans:launch`. The scan must be completed and settled,
        with unfinished findings and a latest triage run that stopped on budget.
        Uses the scan's settings and reserves the explicit budget in credits.
        The token's repository restrictions and spend allowance apply.
        Reusing the same idempotency key and budget returns the original run,
        including after it finishes, without reserving or spending again.
        A different budget with the same key returns 409. A new attempt requires
        a new key. Poll getTriageRun because the parent scan remains COMPLETED.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/ScanId"
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, minLength: 1, maxLength: 128, pattern: '^[!-~]+$' }
          description: Stable request key. Reuse it with the same budget when retrying.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [creditBudget]
              properties:
                creditBudget: { type: integer, minimum: 1 }
      responses:
        "200":
          description: The new or previously created triage run.
          content:
            application/json:
              schema:
                type: object
                required: [run, replayed]
                properties:
                  run: { $ref: "#/components/schemas/TriageRun" }
                  replayed: { type: boolean }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/scans/{scanId}/triage/runs/{runId}:
    get:
      tags: [Scans]
      operationId: getTriageRun
      summary: Get one triage run
      description: >-
        Requires scope: `read`. Follows this run independently of the scan status.
        A COMPLETED run can still leave findings unfinished. Check scan.triage
        after it ends. Failed attempts awaiting retry remain QUEUED.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/ScanId"
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          headers:
            Retry-After:
              description: Advisory seconds before polling an active run again.
              schema: { type: integer, minimum: 1 }
          content:
            application/json:
              schema:
                type: object
                required: [run]
                properties:
                  run: { $ref: "#/components/schemas/TriageRun" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/reports:
    get:
      tags: [Reports]
      operationId: listReports
      summary: List incoming reports
      description: >-
        Requires scope: `read`. Vulnerability reports the programme has
        received, newest first. Optionally filter by `status`.


        `publicId` is what `investigateReport` takes. `intakeState` says
        whether the report has been read and split into claims yet: an
        investigation waits for `COMPLETE`, so a `PENDING` or `RUNNING` report
        is one to come back to rather than one to retry.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Limit"
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [NEW, TRIAGING, NEEDS_INFO, ACCEPTED, DUPLICATE, REJECTED]
          description: Only reports in this triage status.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PaginatedReports" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/reports/{publicId}/investigate:
    post:
      tags: [Reports]
      operationId: investigateReport
      summary: Investigate an incoming report against the code
      description: >-
        Requires scope: `scans:launch`. Runs the triage flow over the report's
        claims: each is checked against the repository, deduplicated against the
        findings already confirmed there, and given a proof of concept where one
        can be written. Returns immediately with the scan doing the work; poll
        `/projects/{projectId}/scans/{scanId}` and then read its findings.


        Idempotent. A report already under investigation returns the existing
        scan with `claimsQueued: null`, so a retry costs nothing.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: publicId
          in: path
          required: true
          schema: { type: string }
          description: The report's public identifier.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                { $ref: "#/components/schemas/InvestigateReportResult" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/advisories:
    get:
      tags: [Advisories]
      operationId: listAdvisories
      summary: List advisories
      description: >-
        Requires scope: `read`. The project's coordinated-disclosure
        advisories, newest first. Optionally filter by `status`.
        A repository-restricted token sees an advisory only when every
        associated repository is in its allowlist.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Limit"
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [DRAFT, SCHEDULED, UNDER_EMBARGO, PUBLISHED, WITHDRAWN]
          description: Only advisories in this status.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PaginatedAdvisories" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/advisories/{publicId}:
    get:
      tags: [Advisories]
      operationId: getAdvisory
      summary: Get an advisory
      description: >-
        Requires scope: `read`. The advisory, the software it concerns, the
        versions it affects, and the notices planned for it.
        Every associated repository must be in the token's allowlist.


        `software` is what decides the audience: a contact is notified about an
        advisory only when they run some of it. `affected` is a separate
        statement about versions, and is often empty.


        A notice the plan is holding back carries `blockedReason`. The commonest
        one is that no affected range names a fixed version, which only the
        people who shipped the release can supply; record it in the app and the
        notice becomes schedulable.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: publicId
          in: path
          required: true
          schema: { type: string }
          description: The advisory's readable identifier.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [advisory]
                properties:
                  advisory: { $ref: "#/components/schemas/AdvisoryDetail" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/advisories/{publicId}/affected:
    put:
      tags: [Advisories]
      operationId: replaceAdvisoryAffected
      summary: Record which versions an advisory affects
      description: >-
        Requires scope: `advisories:write`. Replaces the whole set of affected
        ranges, so send what is affected now rather than a patch.
        Every existing and requested repository must be in the token's
        allowlist. This check also applies to an empty replacement.


        `fixedIn` is the point of this endpoint. A patch notice stays blocked
        until some range names a fixed version, and only the people who shipped
        the release know it.


        Versions only. A range may name only software already on the
        advisory's `software`, and anything else is a `400`. Which software an
        advisory concerns decides who hears about it, and that is its own
        statement, made in the app: a call about versions does not change it in
        either direction.


        This call never sends anything. It records versions and recomputes the
        disclosure plan: a notice blocked for want of a fix becomes eligible to
        go, and one that loses its fix is blocked again, dropping any approval
        it was carrying so nobody approves wording a later fix rewrites. When
        an eligible notice is actually sent is governed by the programme's own
        settings, not by this call.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: publicId
          in: path
          required: true
          schema: { type: string }
          description: The advisory's readable identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [affected]
              properties:
                affected:
                  type: array
                  items:
                    type: object
                    required: [repository, introducedIn]
                    properties:
                      repository:
                        type: object
                        required: [owner, name]
                        properties:
                          owner: { type: string }
                          name: { type: string }
                      introducedIn:
                        type: string
                        description: First version carrying the defect.
                      fixedIn:
                        type: [string, "null"]
                        description: Version that closes the range, or null.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [advisory]
                properties:
                  advisory: { $ref: "#/components/schemas/AdvisoryDetail" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/advisory-contacts:
    get:
      tags: [Advisories]
      operationId: listAdvisoryContacts
      summary: List the advisory contacts
      description: >-
        Requires scope: `contacts:read`. The programme's contact list, oldest
        first, which is the order to read it in when reconciling against a
        record kept elsewhere.


        Its own scope, not `read`: this list is other people's work addresses
        and the record of who learns about a vulnerability before the public
        does, so a routine pipeline token does not reach it.


        `software` on each row is what notices are matched on. A project with no
        security programme reads as an empty list.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Limit"
        - name: tier
          in: query
          schema: { type: string, enum: [EMBARGO, DOWNSTREAM, ANNOUNCE] }
        - name: status
          in: query
          schema:
            type: string
            enum: [ACTIVE, PENDING_VERIFICATION, BOUNCED, UNSUBSCRIBED]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PaginatedAdvisoryContacts" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [Advisories]
      operationId: addAdvisoryContact
      summary: Add an advisory contact
      description: >-
        Requires scope: `contacts:write`. Puts one address on the programme's
        contact list.


        `software` says which of the project's repositories this contact runs,
        and is required. It is what every notice is matched on: a contact who
        runs nothing is told nothing.


        The contact starts `PENDING_VERIFICATION`, and an unconfirmed address
        receives nothing embargoed. The confirmation mail is sent from the app,
        not by this call, so nothing is emailed to the address you send here.


        There is no endpoint that reads the contact list back. It is other
        people's work addresses and the record of who hears about a
        vulnerability early.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, organization, tier, software]
              properties:
                email: { type: string }
                organization:
                  description: The organisation this contact speaks for.
                  type: string
                tier:
                  description: >-
                    How early this contact is told. `EMBARGO` hears first and
                    alone, `DOWNSTREAM` joins once a patch exists, `ANNOUNCE`
                    learns at public disclosure.
                  type: string
                  enum: [EMBARGO, DOWNSTREAM, ANNOUNCE]
                software:
                  description: The repositories this contact runs. At least one.
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required: [owner, name]
                    properties:
                      owner: { type: string }
                      name: { type: string }
                name: { type: [string, "null"] }
                title: { type: [string, "null"] }
                notes: { type: [string, "null"] }
                tags:
                  type: array
                  items: { type: string }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                required: [contact]
                properties:
                  contact: { $ref: "#/components/schemas/AdvisoryContact" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: That address is already on the programme's contact list.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

  /projects/{projectId}/findings:
    get:
      tags: [Findings]
      operationId: listFindings
      summary: List findings
      description: "Requires scope: `read`. Optionally filter by `scanId`."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Limit"
        - name: scanId
          in: query
          required: false
          schema: { type: string }
          description: Only findings belonging to this scan.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PaginatedFindings" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/findings/details:
    get:
      tags: [Findings]
      operationId: listFindingDetails
      summary: Get many findings (full detail)
      description: "Requires scope: `read`. The full detail of a scan's findings, of a set of findings, or both, in one call. Returns the findings shown in the app: confirmed or inconclusive, on scans the project can see."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/Page"
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 50, default: 25 }
        - name: scanId
          in: query
          required: false
          schema: { type: string }
          description: Only findings belonging to this scan.
        - name: ids
          in: query
          required: false
          schema: { type: string }
          description: "Comma-separated finding ids or `ZK-` labels, at most 50. Ids that match nothing are listed in `missing`."
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PaginatedFindingDetails" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/findings/{findingId}:
    get:
      tags: [Findings]
      operationId: getFinding
      summary: Get a single finding (full detail)
      description: "Requires scope: `read`. Includes description, PoC, recommended fix, and notes."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [finding]
                properties:
                  finding: { $ref: "#/components/schemas/FindingDetail" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/findings/{findingId}/notes:
    post:
      tags: [Findings]
      operationId: addFindingNote
      summary: Add a comment (note) to a finding
      description: "Requires scope: `findings:write`."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
                  minLength: 1
                  description: The comment body (markdown).
      responses:
        "201":
          description: Note created
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FindingNoteResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/findings/{findingId}/regression-tests:
    get:
      tags: [Findings]
      operationId: listRegressionTests
      summary: List regression test attempts for a finding
      description: "Requires scope: `read`. Returns the latest 20 attempts."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [runs]
                properties:
                  runs:
                    type: array
                    items: { $ref: "#/components/schemas/RegressionTestRun" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Findings]
      operationId: createRegressionTest
      summary: Generate a regression test and create its draft pull request
      description: >-
        Requires scope: `regression-tests:write`. The finding must be confirmed.
        The token creator must remain an approved project admin with verified
        GitHub write access. The GitHub App must have Contents and Pull requests
        write permissions for this repository. The explicit credit budget is
        reserved and counts against project and token spending limits.
        Reuse the idempotency key with the same budget and target branch to
        retrieve the original attempt without another charge.
        The generated test uses a fixed counterexample and the repository's
        existing test framework. A draft pull request is opened after validation.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, minLength: 1, maxLength: 128, pattern: '^[!-~]+$' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [creditBudget]
              properties:
                creditBudget: { type: integer, minimum: 1, maximum: 100000 }
                targetBranch:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Defaults to the repository's default branch. Resolved to a commit at launch.
      responses:
        "202":
          description: The new or previously created attempt.
          content:
            application/json:
              schema:
                type: object
                required: [run, replayed]
                properties:
                  run: { $ref: "#/components/schemas/RegressionTestRun" }
                  replayed: { type: boolean }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/findings/{findingId}/regression-tests/readiness:
    get:
      tags: [Findings]
      operationId: getRegressionTestReadiness
      summary: Check GitHub readiness for a regression test pull request
      description: >-
        Requires scope: `read`. Reports missing installation, repository access,
        pending write permissions, or requester authorization. Installation
        settings links let repository owners enable the feature.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RegressionTestReadiness" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/findings/{findingId}/regression-tests/{runId}:
    get:
      tags: [Findings]
      operationId: getRegressionTest
      summary: Get a regression test attempt
      description: "Requires scope: `read`. Poll this run independently of the original scan."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RegressionTestRun" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/findings/{findingId}/regression-tests/{runId}/retry-publication:
    post:
      tags: [Findings]
      operationId: retryRegressionTestPublication
      summary: Retry opening a generated regression test pull request
      description: >-
        Requires scope: `regression-tests:write` and current GitHub write access.
        Retries a failed publication using the saved test. Does not rerun the
        agent or reserve another generation budget. Generation failures require
        a new paid attempt.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        "202":
          description: Publication queued.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RegressionTestRun" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /projects/{projectId}/findings/{findingId}/notes/{noteId}/pin:
    post:
      tags: [Findings]
      operationId: pinFindingNote
      summary: Pin a note as the resolution note
      description: "Requires scope: `findings:write`."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
        - name: noteId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [kind]
              properties:
                kind:
                  type: string
                  enum: [resolution]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FindingPinResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/findings/{findingId}/severity:
    patch:
      tags: [Findings]
      operationId: updateFindingSeverity
      summary: Override (or clear) a finding's severity
      description: "Requires scope: `findings:write`. Set `severity` to null to clear the override."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [severity]
              properties:
                severity:
                  oneOf:
                    - { $ref: "#/components/schemas/Severity" }
                    - { type: "null" }
                  description: New severity override, or null to clear.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FindingSeverityResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/findings/{findingId}/resolution:
    patch:
      tags: [Findings]
      operationId: updateFindingResolution
      summary: Change a finding's resolution status
      description: >
        Requires scope: `findings:write`.


        On a finding triage dismissed (`triageStatus` `FALSE_POSITIVE`), any
        status other than `FALSE_POSITIVE` or `DUPLICATE` reopens it: its
        `triageStatus` becomes `CONFIRMED` and the override fields record who
        did it. `NOT_STARTED` reopens it even when that is already its
        resolution. Setting `FALSE_POSITIVE` on a reopened finding undoes the
        reopen: the triage verdict comes back, the override is cleared, and the
        resolution returns to `NOT_STARTED`. The response carries the stored
        statuses.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [resolutionStatus]
              properties:
                resolutionStatus: { $ref: "#/components/schemas/ResolutionStatus" }
                note: { $ref: "#/components/schemas/ChangeNote" }
                reason: { $ref: "#/components/schemas/ResolutionReason" }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FindingResolutionResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/findings/{findingId}/triage:
    patch:
      tags: [Findings]
      operationId: overrideFindingTriage
      summary: Override a finding's triage verdict
      description: >
        Requires scope: `findings:write`.


        Replaces the AI triage verdict with `CONFIRMED` or `FALSE_POSITIVE`.
        The override keeps the first AI verdict it replaced. Setting that
        verdict again clears the override. A `note` is added to the finding as
        a comment from the member who created the token.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [triageStatus]
              properties:
                triageStatus: { type: string, enum: [CONFIRMED, FALSE_POSITIVE] }
                note: { type: string, minLength: 1 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FindingTriageResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/agent-questions:
    get:
      tags: [Findings]
      operationId: listAgentQuestions
      summary: List the open questions Continuous Security analyses asked
      description: >-
        Requires scope: `read`. The open questions the project's continuous
        analyses asked its members, oldest first, at most 200.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [questions]
                properties:
                  questions:
                    type: array
                    items: { $ref: "#/components/schemas/AgentQuestion" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/agent-questions/{questionId}/answer:
    post:
      tags: [Findings]
      operationId: answerAgentQuestion
      summary: Answer a Continuous Security analysis's question
      description: >-
        Requires scope: `guidance:write`. Answers with one of the question's
        options, a note, or both. The answer reaches the analysis's next
        session. It is recorded as the answer of the member who created the
        token, who needs a project role of their own. Responds `409` when the
        question was already answered or dismissed.
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: questionId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                selectedOption:
                  type: [string, "null"]
                  description: The label of one of the question's options.
                note: { type: [string, "null"] }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [questionId, status]
                properties:
                  questionId: { type: string }
                  status: { type: string, enum: [ANSWERED] }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/findings/{findingId}/publish:
    post:
      tags: [Publishing]
      operationId: publishFinding
      summary: Publish a finding as a public artifact
      description: "Requires scope: `publish`. Pin a note as the published note via `noteId`. An omitted body uses defaults. A nonempty body must be valid JSON or the request returns 400 without publishing."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/FindingId"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PublishFindingRequest" }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PublishArtifactResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }

  /projects/{projectId}/scans/{scanId}/publish:
    post:
      tags: [Publishing]
      operationId: publishScan
      summary: Publish a scan as a public artifact
      description: "Requires scope: `publish`. The scan must be COMPLETED. An omitted body uses defaults. A nonempty body must be valid JSON or the request returns 400 without publishing."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/ScanId"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PublishScanRequest" }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PublishArtifactResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/scan-presets:
    get:
      tags: [Discovery]
      operationId: listScanPresets
      summary: List the scan presets (scan types) the project can launch
      description: "Requires scope: `read`. Use a preset's `ref` as `presetRef` when launching."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [presets]
                properties:
                  presets:
                    type: array
                    items: { $ref: "#/components/schemas/ScanPreset" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/billing/balance:
    get:
      tags: [Billing]
      operationId: getBillingBalance
      summary: Credits available to this project
      description: "Requires scope: `read`. The organization's shared prepaid balance, available to this project and to the organization's other projects. All amounts are in credits."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BillingBalance" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/billing/usage:
    get:
      tags: [Billing]
      operationId: getBillingUsage
      summary: Credit usage events attributed to this project
      description: "Requires scope: `read`. Signed credit delta per ledger event attributed to this project; organization-wide movements such as a top-up made outside any project are not included. Defaults to the last 30 days; newest first; max 1000 rows."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: from
          in: query
          required: false
          schema: { type: string, format: date-time }
        - name: to
          in: query
          required: false
          schema: { type: string, format: date-time }
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 1000 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BillingUsage" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

  /projects/{projectId}/billing/summary:
    get:
      tags: [Billing]
      operationId: getBillingSummary
      summary: Monthly spend and purchase summary for this project
      description: "Requires scope: `read`. Per-month net scan spend and net purchases attributed to this project, in credits, newest first. Purchases land in the organization's shared balance."
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: months
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 24 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BillingSummary" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Project API token: `zkao_proj_<keyId>_<secret>`."

  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      schema: { type: string }
    ScanId:
      name: scanId
      in: path
      required: true
      schema: { type: string }
    FindingId:
      name: findingId
      in: path
      required: true
      description: "The finding id, or the `ZK-` label shown on the finding page (the id's last eight characters, prefix optional). A label that matches more than one finding in the project is refused with `409 conflict`; use the full id."
      schema: { type: string }
    RepositoryId:
      name: repositoryId
      in: path
      required: true
      schema: { type: string }
    ContinuousTestingBranch:
      name: branch
      in: query
      required: false
      schema: { type: string }
      description: The scheduled branch. Defaults to the repository's default branch.
    Page:
      name: page
      in: query
      required: false
      schema: { type: integer, minimum: 1, default: 1 }
    Limit:
      name: limit
      in: query
      required: false
      schema: { type: integer, minimum: 1, maximum: 100, default: 50 }

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Unauthorized:
      description: Missing, malformed, expired, or revoked token
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    InsufficientCredits:
      description: >-
        The project does not have enough prepaid credits to cover the scan
        budget. Top up credits and retry. (code `insufficient_credits`)
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    RepositoryInitializing:
      description: >-
        The repository is still being analyzed and cannot be scanned yet. The
        same request succeeds once `GET /repositories` reports its `readiness`
        as `ready`. (code `repository_initializing`)
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    DiffUnavailable:
      description: >-
        The diff scan has nothing to audit. Code `diff_empty`: the base and the
        scanned commit have no change between them.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Forbidden:
      description: The token lacks the required scope
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    NotFound:
      description: Resource not in this token's project or repo allowlist
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Conflict:
      description: >-
        A compare-and-set (`expectedContent`) missed: the guidance changed
        since it was read. Re-read the current guidance and retry.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    RateLimited:
      description: >-
        Rate limited. Either the token's spend limit for the current period is
        reached (on launch), or the token is sending too many requests. Wait the
        number of seconds in the `Retry-After` header before retrying.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }

  schemas:
    Organization:
      type: object
      description: The organization a project belongs to. Credits are held and billed at this level and shared by every project in it.
      required: [id, slug, name]
      properties:
        id: { type: string }
        slug: { type: string, description: "URL segment of the organization (`/orgs/<slug>`), unique across zkao." }
        name: { type: string }
    TokenInfo:
      type: object
      required: [id, name, scopes, repositoryIds, expiresAt, spendLimitCredits, project]
      properties:
        id: { type: string }
        name: { type: string }
        scopes:
          type: array
          items: { type: string }
        repositoryIds:
          type: array
          items: { type: string }
          description: Repositories the token is restricted to. Empty means every repository of the project.
        expiresAt: { type: [string, "null"], format: date-time }
        spendLimitCredits: { type: [integer, "null"], description: "Credits this token may spend. Null means no limit." }
        project:
          type: object
          required: [id, slug, name, organization]
          properties:
            id: { type: string }
            slug: { type: string }
            name: { type: string }
            organization: { $ref: "#/components/schemas/Organization" }
    BillingBalance:
      type: object
      required: [organization, balanceCredits, availableCredits, reservedCredits]
      properties:
        organization:
          $ref: "#/components/schemas/Organization"
          description: The organization whose shared balance this is.
        balanceCredits: { type: integer, description: "The organization's total prepaid credit balance, shared by all of its projects." }
        availableCredits: { type: integer, description: "Balance minus credits reserved by the organization's in-flight scans." }
        reservedCredits: { type: integer, description: "Credits held by the organization's queued/running scans." }
    UsageEventType:
      type: string
      enum: [SCAN_DEDUCTION, SCAN_REFUND, PURCHASE, STRIPE_REFUND, ADMIN_ADJUSTMENT]
    UsageEvent:
      type: object
      required: [id, at, type, credits, scanId, description]
      properties:
        id: { type: string }
        at: { type: string, format: date-time }
        type: { $ref: "#/components/schemas/UsageEventType" }
        credits: { type: integer, description: "Signed credit delta: negative = spent/clawed back, positive = added/refunded." }
        scanId: { type: [string, "null"] }
        description: { type: string }
    BillingUsage:
      type: object
      required: [from, to, events]
      properties:
        from: { type: string, format: date-time }
        to: { type: string, format: date-time }
        events:
          type: array
          items: { $ref: "#/components/schemas/UsageEvent" }
    UsageMonthSummary:
      type: object
      required: [month, spentCredits, purchasedCredits]
      properties:
        month: { type: string, description: "YYYY-MM (UTC)." }
        spentCredits: { type: integer, description: "Net scan spend (deductions less refunds), in credits." }
        purchasedCredits: { type: integer, description: "Net purchases (purchases less clawbacks), in credits." }
    BillingSummary:
      type: object
      required: [organization, months]
      properties:
        organization:
          $ref: "#/components/schemas/Organization"
          description: The organization whose shared balance the purchases were made into.
        months:
          type: array
          items: { $ref: "#/components/schemas/UsageMonthSummary" }
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              enum: [unauthorized, forbidden, not_found, bad_request, conflict, insufficient_credits, budget_below_minimum, repository_initializing, diff_base_required, diff_base_not_allowed, diff_base_invalid, diff_empty, rate_limited, internal]
            message: { type: string }
            minimumCredits:
              type: integer
              description: >-
                budget_below_minimum only: the least the launch could have
                reserved, in credits. A diff scan's first scan of a repository
                also builds its overview, so its minimum is higher.

    Severity:
      type: string
      enum: [CRITICAL, HIGH, MEDIUM, LOW, INFO]
    ResolutionStatus:
      type: string
      enum: [NOT_STARTED, IN_PROGRESS, RESOLVED, WONT_FIX, MITIGATED, FALSE_POSITIVE, DUPLICATE]
    TriageStatus:
      type: string
      enum: [PENDING, NEW, DUPLICATE, RECURRING, CONFIRMED, FALSE_POSITIVE, INCONCLUSIVE]
    ScanStatus:
      type: string
      enum: [QUEUED, PROCESSING, COMPLETED, FAILED, CANCELLED]

    Repository:
      type: object
      required: [id, slug, owner, name, url, status, readiness]
      properties:
        id: { type: string }
        slug: { type: string, description: "URL segment of the repository inside its project (`/orgs/<org>/projects/<project>/repos/<slug>`). Unique per project." }
        owner: { type: string }
        name: { type: string }
        url: { type: string }
        defaultBranch: { type: [string, "null"] }
        status: { type: string, description: "ACTIVE | MARKED_FOR_DELETION" }
        readiness:
          type: string
          enum: [ready, analyzing]
          description: >
            Whether a scan can start on this repository. A newly added
            repository is `analyzing` until a one-time pass over it finishes;
            launching a scan meanwhile fails with `repository_initializing`.
            Poll this endpoint rather than retrying the launch blind.

    Scan:
      type: object
      required: [id, status, repositoryId, createdAt]
      properties:
        id: { type: string }
        status: { $ref: "#/components/schemas/ScanStatus" }
        failureCode:
          type: [string, "null"]
          enum: [NO_MEMBER_REPO_ACCESS, GITHUB_APP_PERMISSIONS_PENDING, null]
          description: >-
            An actionable setup failure for a failed scan. Null for other
            statuses and internal failures. Restore a project member's GitHub
            access or approve the App permissions before launching again.
        repositoryId: { type: string }
        commitHash: { type: [string, "null"] }
        baseCommit:
          type: [string, "null"]
          description: A diff scan's base, as the merge base SHA its change is measured from. Null for other scans.
        commitMessage: { type: [string, "null"] }
        presetName: { type: [string, "null"] }
        effort:
          type: [string, "null"]
          enum: [medium, high, extra-high, deep, null]
          readOnly: true
          description: >-
            The scan's budget measured against the levels sized for its scope
            at launch. `high` starts at the recommended baseline, `extra-high`
            at the next level, and `deep` at the highest level. The server
            accounts for the scan limit and any fixed setup cost when sizing
            these levels. `medium` records a custom budget below High or a
            historical scan at that level. Null for a Flash scan and for a
            scan with no recorded effort.
        createdAt: { type: string, format: date-time }
        startedAt: { type: [string, "null"], format: date-time }
        completedAt: { type: [string, "null"], format: date-time }
        progress:
          oneOf:
            - $ref: "#/components/schemas/ScanProgress"
            - type: "null"
          description: >
            Phase progress while the scan is in flight. Null once the scan
            reaches a terminal state, and null before it has been dispatched
            (no phases exist yet).
        budget:
          oneOf:
            - $ref: "#/components/schemas/ScanBudget"
            - type: "null"
          description: Null for a scan launched without a budget.

    ScanTrigger:
      type: object
      required: [kind]
      description: >-
        Where a launch came from. References only: no URL is accepted, and the
        link the scan page shows is built from the scanned repository, so a
        token can never point that page somewhere of its own choosing.
      properties:
        kind:
          type: string
          enum: [github_action, pr_comment, agent, api]
          description: What asked for the scan.
        pullRequest:
          type: [integer, "null"]
          minimum: 1
          description: >-
            Pull request number in the scanned repository. Its existence is not
            checked: a wrong number only yields a dead link in your own
            repository.
        commentId:
          type: [string, "null"]
          pattern: "^[0-9]{1,32}$"
          description: >-
            The comment that asked for the scan, so the link lands on it.
            Requires pullRequest.

    ScanBudget:
      type: object
      required: [limitCredits, spentCredits, nextBudgetRecommendation]
      description: >
        What a scan was allowed to spend, what it was charged, and whether the
        next scan of its type and scope should get more. Check the last scan of
        a type before choosing the next one's budget.
      properties:
        limitCredits:
          type: integer
          description: The most the scan could spend, in credits.
        spentCredits:
          type: [integer, "null"]
          description: Credits charged for the scan. Null until it finishes.
        nextBudgetRecommendation:
          type: [string, "null"]
          enum: [keep, raise, null]
          description: >
            Whether the next scan of this type and scope should keep this
            budget or raise it. A raise is half again, never above twice the
            scan type's minimum. A raise can follow a scan that spent well
            under its limit: the limit is divided between the parts of the
            analysis, and one part cannot use another's unspent share. Null
            until the scan completes.

    ScanProgress:
      type: object
      required: [phasesCompleted, phasesTotal, percent]
      description: >
        How far a running scan has got through its phases. Deliberately not a
        time estimate: a phase's duration moves with the guidance it was given,
        the repository, and the model that ran it.
      properties:
        phasesCompleted:
          type: integer
          description: Phases that reached a terminal state (completed, failed, or skipped).
        phasesTotal:
          type: integer
          description: Phases this scan will run, fixed when it was dispatched.
        percent:
          type: integer
          minimum: 0
          maximum: 100
          description: >
            Weighted completion. Each phase counts for its share of the scan
            budget, so this does not simply equal phasesCompleted / phasesTotal.

    TriageResumeBudget:
      type: object
      required: [minCredits, recommendedCredits, maxCredits]
      properties:
        minCredits: { type: integer }
        recommendedCredits: { type: integer }
        maxCredits: { type: integer }
    RegressionTestReadiness:
      type: object
      required: [status, settingsUrl, message, defaultBranch]
      properties:
        status: { type: string, enum: [ready, missing, unselected, pending, forbidden, unavailable] }
        settingsUrl: { type: [string, "null"], format: uri }
        message: { type: string }
        defaultBranch: { type: string }
    RegressionTestValidation:
      type: object
      required: [commit, outcome, command, summary]
      properties:
        commit: { type: string, pattern: '^[a-f0-9]{40}$' }
        outcome: { type: string, enum: [assertion_failed, passed, blocked, not_run] }
        command: { type: string }
        summary: { type: string }
    RegressionTestRun:
      type: object
      required: [id, findingId, status, creditBudget, targetBranch, targetCommit, auditedCommit, summary, pullRequestUrl, audited, target, createdAt, completedAt]
      properties:
        id: { type: string }
        findingId: { type: string }
        status: { type: string, enum: [QUEUED, RUNNING, BLOCKED, READY, PUBLISHED, PUBLICATION_FAILED, FAILED, CANCELLED] }
        creditBudget: { type: integer, minimum: 1 }
        targetBranch: { type: string }
        targetCommit: { type: string }
        auditedCommit: { type: string }
        summary: { type: [string, "null"] }
        pullRequestUrl: { type: [string, "null"], format: uri }
        audited:
          anyOf:
            - $ref: "#/components/schemas/RegressionTestValidation"
            - type: "null"
        target:
          anyOf:
            - $ref: "#/components/schemas/RegressionTestValidation"
            - type: "null"
        createdAt: { type: string, format: date-time }
        completedAt: { type: [string, "null"], format: date-time }
    ScanTriage:
      type: object
      description: Completeness of triage, independent of whether the scan succeeded.
      required: [status, untriagedCount, activeRunId, resume]
      properties:
        status:
          type: string
          enum: [pending, running, complete, budget_exhausted, blocked]
        untriagedCount: { type: integer, minimum: 0 }
        activeRunId: { type: [string, "null"] }
        resume:
          anyOf:
            - $ref: "#/components/schemas/TriageResumeBudget"
            - type: "null"
    TriageRun:
      type: object
      required: [id, scanId, status, findingCount, createdAt, completedAt, budgetExhausted]
      properties:
        id: { type: string }
        scanId: { type: string }
        status: { type: string, enum: [QUEUED, RUNNING, COMPLETED, FAILED, CANCELLED] }
        findingCount:
          type: integer
          description: Number of findings selected when this run started.
        createdAt: { type: string, format: date-time }
        completedAt: { type: [string, "null"], format: date-time }
        budgetExhausted:
          type: boolean
          description: Whether this run reached its budget cap. Check scan.triage for remaining work.
    ScanDetail:
      allOf:
        - $ref: "#/components/schemas/Scan"
        - type: object
          required: [triage]
          properties:
            triage: { $ref: "#/components/schemas/ScanTriage" }
            branch: { type: [string, "null"] }
            creditBudget:
              type: [integer, "null"]
              description: Reserved budget for the scan, in credits.
            findingsSummary:
              type: [object, "null"]
              properties:
                total: { type: integer }
                bySeverity:
                  type: object
                  additionalProperties: { type: integer }

    FindingSource:
      type: object
      description: Where the finding was found.
      required: [kind, branch]
      properties:
        kind:
          type: string
          description: The kind of scan that found it. One of continuous-security, pr-review, flash, max, flash-diff, max-diff, supply-chain, flash-retriage, max-retriage, flash-regression-check, max-regression-check, manual-audit, report-investigation or other. New kinds may be added, so treat an unknown kind like other.
        branch:
          type: [string, "null"]
          description: The branch the scan ran on. Null when the scan recorded none, such as a scan of a pinned commit.

    Finding:
      type: object
      required: [id, displayId, title, location, severity, category, triageStatus, resolutionStatus, notesCount, source, dismissalReason, triageOverriddenFrom, triageOverriddenAt, triageOverriddenByName]
      properties:
        id: { type: string }
        displayId: { type: integer }
        title: { type: string }
        location: { type: string }
        severity:
          $ref: "#/components/schemas/Severity"
          description: Effective severity (user override if set, else AI severity).
        category: { type: string }
        triageStatus: { $ref: "#/components/schemas/TriageStatus" }
        confirmationEvidence:
          type: [string, "null"]
          enum: [POC, ANALYSIS, null]
          description: What backs a CONFIRMED verdict. POC means a proof of concept ran and demonstrated the issue. ANALYSIS means it was confirmed by code analysis alone. Null for other statuses or when not recorded.
        resolutionStatus: { $ref: "#/components/schemas/ResolutionStatus" }
        notesCount: { type: integer }
        source: { $ref: "#/components/schemas/FindingSource" }
        dismissalReason:
          type: [string, "null"]
          description: Why triage dismissed the finding as a false positive. Null when triage did not dismiss it or gave no reason.
        triageOverriddenFrom:
          description: The triage verdict a member replaced, kept from the first override. Null when nobody overrode triage.
          oneOf:
            - { $ref: "#/components/schemas/TriageStatus" }
            - { type: "null" }
        triageOverriddenAt: { type: [string, "null"], format: date-time }
        triageOverriddenByName:
          type: [string, "null"]
          description: Name, or email when there is no name, of the member who overrode triage.

    FindingNote:
      type: object
      required: [id, body, createdAt]
      properties:
        id: { type: string }
        body: { type: string, description: Markdown. A page of the app the assistant names is an absolute link. }
        createdAt: { type: string, format: date-time }
        author:
          type: [object, "null"]
          properties:
            id: { type: string }
            name: { type: [string, "null"] }
            email: { type: string }

    FindingDetail:
      allOf:
        - $ref: "#/components/schemas/Finding"
        - type: object
          required: [description, impact, recommendation, assumptions, scanId, createdAt, notes]
          properties:
            description: { type: string }
            impact: { type: string }
            recommendation: { type: string }
            assumptions:
              type: array
              items: { type: string }
            pocReport: { type: [string, "null"] }
            recommendedFix: { type: [string, "null"] }
            scanId: { type: string }
            commitHash: { type: [string, "null"] }
            repo:
              type: [object, "null"]
              properties:
                owner: { type: string }
                name: { type: string }
                url: { type: string }
            createdAt: { type: string, format: date-time }
            notes:
              type: array
              items: { $ref: "#/components/schemas/FindingNote" }

    PaginatedScans:
      type: object
      required: [items, page, limit, total]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/Scan" }
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }

    Report:
      type: object
      required:
        [publicId, title, source, status, intakeState, createdAt]
      properties:
        publicId:
          type: string
          description: The identifier `investigateReport` takes.
        title: { type: string }
        source:
          type: string
          description: How it arrived, including GitHub private reports, API submissions, and file imports.
        claimedSeverity:
          oneOf:
            - $ref: "#/components/schemas/Severity"
            - type: "null"
          description: What the reporter claimed, which is not an assessment.
        status:
          type: string
          enum: [NEW, TRIAGING, NEEDS_INFO, ACCEPTED, DUPLICATE, REJECTED]
        intakeState:
          type: string
          enum: [PENDING, RUNNING, REVIEW, COMPLETE, FAILED]
          description: >-
            Whether the report has been read and split into claims. An
            investigation waits for COMPLETE.
        evaluationState:
          type: [string, "null"]
          enum: [QUEUED, RUNNING, COMPLETE, FAILED, null]
          description: How the investigation is going, or null if none has run.
        reporterName: { type: [string, "null"] }
        reporterGithubLogin: { type: [string, "null"] }
        githubUrl:
          type: [string, "null"]
          description: The GitHub advisory it arrived as.
        acknowledgedAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }

    PaginatedReports:
      type: object
      required: [items, page, limit, total]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/Report" }
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }

    Advisory:
      type: object
      required:
        [publicId, title, severity, status, ghsaState, createdAt]
      properties:
        publicId:
          type: string
          description: Readable identifier, e.g. `ADVISORY-ADV-2026-0045`.
        title: { type: string }
        severity:
          type: string
          enum: [CRITICAL, HIGH, MEDIUM, LOW, INFO]
        status:
          type: string
          enum: [DRAFT, SCHEDULED, UNDER_EMBARGO, PUBLISHED, WITHDRAWN]
        disclosureAt:
          type: [string, "null"]
          format: date-time
          description: When the embargo lifts. Null until a date is set.
        publishedAt: { type: [string, "null"], format: date-time }
        cveId: { type: [string, "null"] }
        ghsaId:
          type: [string, "null"]
          description: The GitHub advisory, once one has been filed.
        ghsaUrl: { type: [string, "null"] }
        ghsaState:
          type: string
          description: >-
            What GitHub reports. A created entry is a DRAFT, which is private
            and reaches no scanner; only a published one is public.
        createdAt: { type: string, format: date-time }

    AdvisoryAffected:
      type: object
      required: [id, repository, introducedIn, fixedIn]
      properties:
        id: { type: string }
        repository:
          type: object
          required: [owner, name]
          properties:
            owner: { type: string }
            name: { type: string }
        introducedIn:
          type: string
          description: First version carrying the defect.
        fixedIn:
          type: [string, "null"]
          description: >-
            Version that closes the range. Null while no patch exists, which is
            what holds a patch notice back.

    AdvisoryNotice:
      type: object
      required:
        [label, offsetDays, scheduledFor, status, blockedReason, sentAt, recipientCount]
      properties:
        label: { type: string }
        offsetDays:
          type: integer
          description: >-
            Days relative to disclosure. Negative is before it, 0 is the day
            itself.
        scheduledFor: { type: string, format: date-time }
        status:
          type: string
          enum: [DRAFT, SCHEDULED, BLOCKED, SENDING, SENT, CANCELLED]
        blockedReason:
          type: [string, "null"]
          description: Why the plan is holding this notice back, if it is.
        sentAt: { type: [string, "null"], format: date-time }
        recipientCount:
          type: integer
          description: Contacts written to, as recorded when it went.

    AdvisoryDetail:
      allOf:
        - $ref: "#/components/schemas/Advisory"
        - type: object
          required: [summary, description, impact, software, affected, notices]
          properties:
            summary: { type: string }
            description: { type: string }
            impact: { type: string }
            cwe: { type: [string, "null"] }
            software:
              description: >-
                The software the advisory is about. A contact hears about it
                only when they run some of it.
              type: array
              items:
                type: object
                required: [owner, name]
                properties:
                  owner: { type: string }
                  name: { type: string }
            affected:
              type: array
              items: { $ref: "#/components/schemas/AdvisoryAffected" }
            notices:
              type: array
              items: { $ref: "#/components/schemas/AdvisoryNotice" }

    AdvisoryContact:
      type: object
      required: [id, email, organization, tier, status, software, createdAt]
      properties:
        id: { type: string }
        email: { type: string }
        organization: { type: string }
        tier: { type: string }
        status:
          description: >-
            `PENDING_VERIFICATION` until the contact confirms the address. An
            unconfirmed address receives nothing embargoed.
          type: string
        software:
          description: The software this contact runs, which notices are matched on.
          type: array
          items:
            type: object
            required: [owner, name]
            properties:
              owner: { type: string }
              name: { type: string }
        createdAt: { type: string, format: date-time }

    PaginatedAdvisoryContacts:
      type: object
      required: [items, page, limit, total]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/AdvisoryContact" }
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }

    PaginatedAdvisories:
      type: object
      required: [items, page, limit, total]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/Advisory" }
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }

    PaginatedFindings:
      type: object
      required: [items, page, limit, total]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/Finding" }
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }

    PaginatedFindingDetails:
      type: object
      required: [items, page, limit, total, missing]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/FindingDetail" }
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }
        missing:
          type: array
          items: { type: string }
          description: The requested `ids` that matched no finding.

    ScanPreset:
      type: object
      required: [ref, name, minCredits, modelTier]
      properties:
        ref: { type: string, description: "Pass as `presetRef` when launching." }
        name: { type: string }
        description: { type: [string, "null"] }
        minCredits:
          type: integer
          description: "Minimum budget for a launch. 0 = use the default floor."
        modelTier: { type: string }

    LaunchScanRequest:
      type: object
      required: [repositoryId]
      properties:
        repositoryId: { type: string }
        creditBudget:
          type: integer
          minimum: 1
          description: >-
            Max budget for the scan, in credits. Reserved at launch. Omit it to
            launch at the budget zkao recommends for this scan type and scope
            on this repository. A Flash or Max scan of the code is sized from
            the audit areas it reads: the selected areas, or every area in the
            repository map. One area gets the minimum, and the budget grows
            with the square root of the area count. With no map, or with
            `auditScope`, it is twice the minimum. It is half again the last
            budget when the last scan of the same scope ran short of it. A diff
            scan is sized from its change instead: the minimum for up to 500
            changed lines, then in proportion, up to three times the minimum.
            Other scan types use the last such scan's budget, or half again
            when that scan ran short of it, and a first scan starts at twice
            the minimum. Except for a diff, the recommendation never exceeds
            twice the minimum. A budget below the minimum is refused with `400`
            `budget_below_minimum`, whose `minimumCredits` names it.
        presetRef:
          type: string
          description: A preset ref from /scan-presets. Defaults to the first active preset.
        branch:
          type: [string, "null"]
          description: Branch to scan (resolved to its head commit server-side). Ignored if commitHash is set.
        commitHash:
          type: [string, "null"]
          description: Pin a specific commit SHA (7-40 hex chars).
        commitMessage: { type: [string, "null"] }
        baseCommit:
          type: [string, "null"]
          description: >-
            What a diff scan's change is measured from: a commit SHA, branch, or
            tag. Required by a diff scan preset and refused by every other. The
            scan records the merge base of this and the scanned commit. When no
            earlier scan of the repository built its overview, the diff scan
            builds one first, and its minimum and recommended budgets rise.
        backlogRecheck:
          type: object
          additionalProperties: false
          not:
            required: [findingIds, resumeScanId]
            properties:
              findingIds: {}
              resumeScanId: {}
          description: >-
            Options for Recheck open findings. Omit to reassess eligible Not
            started findings on the selected branch. Fresh rechecks require
            the branch's latest commit and reject a pinned commit or audit scope.
          properties:
            includeInProgress:
              type: boolean
              description: Also include In progress findings. Defaults to false.
            findingIds:
              type: array
              minItems: 1
              maxItems: 500
              items:
                type: string
                minLength: 1
              description: >-
                Restrict the recheck to these findings. Eligibility is still
                checked against the selected repository and branch. Omit to
                include all eligible findings. Cannot be combined with resumeScanId.
            resumeScanId:
              type: string
              minLength: 1
              description: >-
                Continue a finished recheck's unassessed findings on the same
                repository. Uses that scan's branch, commit, and status selection.
        trigger:
          oneOf:
            - $ref: "#/components/schemas/ScanTrigger"
            - type: "null"
          description: >-
            Where this launch came from, shown on the scan page. Optional, and
            display only: nothing in the pipeline reads it.
        auditAreaKeys:
          type: array
          items: { type: string }
          description: >-
            Area keys from /audit-areas to scope this scan to. Omit or send an
            empty array to scan the whole repository. A key the
            repository's current map no longer names fails the launch rather
            than being dropped, so a scan budgeted for one subsystem never
            silently runs against everything.
        auditScope:
          type: [string, "null"]
          maxLength: 10000
          description: >-
            The code to audit, described in your own words, instead of
            `auditAreaKeys`. Send one or the other, not both.
        guidance:
          type: [string, "null"]
          maxLength: 100000
          description: >-
            Guidance for this scan only, replacing the repository's configured
            guidance layer (it is still layered over any committed zkao.md).
            Omit the field to inherit the repository's guidance; send null to
            scan with no guidance layer.

    LaunchScanResult:
      type: object
      required: [scanId, queued, creditBudget, buildsOverview]
      properties:
        scanId: { type: string }
        queued: { type: boolean }
        creditBudget:
          type: integer
          description: The budget the scan was launched with, in credits.
        buildsOverview:
          type: boolean
          description: >-
            True when no earlier scan of the repository built its overview, so
            this diff scan builds one first. It takes longer, and its minimum
            and recommended budgets are higher.

    RepositoryGuidance:
      type: object
      required: [repositoryId, content, updatedAt]
      properties:
        repositoryId: { type: string }
        content:
          type: [string, "null"]
          description: The configured guidance, or null when none is set.
        updatedAt:
          type: [string, "null"]
          format: date-time
          description: >-
            When the guidance last changed. Null when the repo has no revision
            history (guidance never set, or set before revisions were tracked).

    SetGuidanceRequest:
      type: object
      required: [content]
      properties:
        content:
          type: [string, "null"]
          maxLength: 100000
          description: New guidance content; null clears it.
        expectedContent:
          type: [string, "null"]
          description: >-
            Optional compare-and-set. Omit for last-writer-wins. Send the
            content you last read (or null for "currently cleared") to receive a
            409 if the guidance changed underneath you instead of overwriting it.

    SetGuidanceResult:
      type: object
      required: [repositoryId, revisionId, unchanged]
      properties:
        repositoryId: { type: string }
        revisionId:
          type: [string, "null"]
          description: The recorded revision id, or null on a no-op write.
        unchanged:
          type: boolean
          description: True when the content already matched (no revision recorded).

    AuditArea:
      type: object
      required: [key, name, description, source, inLatestMap, files, lines]
      properties:
        key:
          type: string
          description: Stable slug, unique per repository. Pass it in `auditAreaKeys` when launching a scan.
        name: { type: string }
        description: { type: [string, "null"] }
        source:
          type: string
          enum: [discovered, custom]
          description: >-
            `discovered` was named by a scan's map of the repository; `custom`
            was added through this API or the app.
        inLatestMap:
          type: boolean
          description: Whether the branch's latest map still names this area.
        files:
          type: [integer, "null"]
          description: Files this area covers at that map. Null when the map does not name it.
        lines:
          type: [integer, "null"]
          description: Lines this area covers at that map. Null when the map does not name it.

    AuditAreaList:
      type: object
      required: [repositoryId, branch, mapped, totalFiles, totalLines, areas]
      properties:
        repositoryId: { type: string }
        branch:
          type: [string, "null"]
          description: Branch the sizes were read from.
        mapped:
          type: boolean
          description: Whether that branch has a stored map at all.
        totalFiles: { type: [integer, "null"] }
        totalLines: { type: [integer, "null"] }
        areas:
          type: array
          description: The map's own audit order first, then the areas it no longer names.
          items: { $ref: "#/components/schemas/AuditArea" }

    CreateAuditAreaRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          maxLength: 120
        description:
          type: [string, "null"]
          maxLength: 500
          description: What this part of the code does.

    DeleteAuditAreaResult:
      type: object
      required: [repositoryId, key, deleted]
      properties:
        repositoryId: { type: string }
        key: { type: string }
        deleted: { type: boolean }

    ContinuousFeatureId:
      type: string
      enum: [bug-hunting, formal-verification, dependency-analysis, weak-key-analysis, security-invariants]

    ContinuousTesting:
      type: object
      required:
        [
          repositoryId,
          available,
          enabled,
          state,
          branch,
          monthlyBudgetCredits,
          cadence,
          intervalHours,
          perRunBudgetCredits,
          areaKeys,
          availableFeatures,
          enabledFeatures,
          spentThisMonthCredits,
          runsThisMonth,
          lastRunAt,
          nextRunAt,
          defaultMonthlyCredits,
          recommendedMonthlyCredits,
          minimumMonthlyCredits,
          maximumMonthlyCredits,
        ]
      properties:
        repositoryId: { type: string }
        available:
          type: boolean
          description: False when Continuous Security is not offered.
        enabled:
          type: boolean
          description: False when there is no schedule or it is paused.
        state:
          type: [string, "null"]
          enum: [active, converged, budget_reached, needs_credits, error, null]
          description: >-
            Why an enabled schedule is not running: `budget_reached` when the
            schedule's or project's monthly automation cap is reached, `needs_credits`
            when the organization's credits cannot fund the next run (it resumes on its
            own once they can), `error` after repeated failures. Null with no schedule.
        branch: { type: string }
        monthlyBudgetCredits:
          type: [integer, "null"]
          description: The configured monthly spending cap. Legacy schedules derive the budget from their cadence and per-run budget.
        cadence:
          type: [string, "null"]
          enum: [daily, weekly, biweekly, monthly, null]
          description: >-
            Legacy fixed cadence. Null for a custom interval or no schedule.
            Use intervalHours for the actual interval.
        intervalHours:
          type: [integer, "null"]
          minimum: 1
          description: Hours between scheduled runs. Null when no schedule exists.
        perRunBudgetCredits: { type: [integer, "null"] }
        areaKeys:
          type: array
          items: { type: string }
          description: >-
            Audit areas the runs rotate through, one per run, least recently
            scanned first. Empty means every run scans the whole repository.
        availableFeatures:
          type: array
          uniqueItems: true
          items: { $ref: "#/components/schemas/ContinuousFeatureId" }
          description: Analyses offered on this branch. Empty when Continuous Security is unavailable.
        enabledFeatures:
          type: array
          uniqueItems: true
          items: { $ref: "#/components/schemas/ContinuousFeatureId" }
          description: Selected analyses. A branch with no saved selection defaults to bug hunting when Continuous Security is available. A paused schedule keeps its selection.
        spentThisMonthCredits:
          type: integer
          description: Credits the branch was charged for Continuous Security since the UTC month began, net of refunds. Counts its analysis steps, change assessments, public-key reviews, agent questions and the planning included in steps.
        runsThisMonth:
          type: integer
          description: Runs the schedule launched since the UTC month began.
        lastRunAt: { type: [string, "null"], format: date-time }
        nextRunAt:
          type: [string, "null"]
          format: date-time
          description: >-
            When the next run becomes due. A past time means within the hour.
            Null when paused or stopped.
        defaultMonthlyCredits:
          type: [integer, "null"]
          description: The monthly budget a new schedule gets when the request names none. It funds at least one analysis step.
        recommendedMonthlyCredits:
          type: [integer, "null"]
          description: A monthly budget that funds about four analysis steps, within the minimum and maximum. A suggestion to pass as `monthlyBudgetCredits`. It is never applied when the request names no budget.
        minimumMonthlyCredits:
          type: [integer, "null"]
          description: The smallest month that funds one analysis step. Less is refused.
        maximumMonthlyCredits:
          type: [integer, "null"]
          description: The largest monthly budget currently allowed for the repository. Administrators can raise it.

    SetContinuousTestingRequest:
      type: object
      additionalProperties: false
      not:
        properties: { enableFeatures: {}, enabledFeatures: {} }
        required: [enableFeatures, enabledFeatures]
      properties:
        enabled:
          type: boolean
          description: False pauses the schedule; true turns it on or resumes it.
        monthlyBudgetCredits:
          type: integer
          minimum: 1
          description: Re-plans the interval and the per-run budget within the returned minimum and maximum.
        areaKeys:
          type: array
          maxItems: 20
          items: { type: string }
          description: Replaces the rotation set. An empty array scans the whole repository every run.
        enableFeatures:
          type: array
          minItems: 1
          uniqueItems: true
          items: { $ref: "#/components/schemas/ContinuousFeatureId" }
          description: Adds the listed analyses to the current selection. Mutually exclusive with enabledFeatures.
        enabledFeatures:
          type: array
          minItems: 1
          uniqueItems: true
          items: { $ref: "#/components/schemas/ContinuousFeatureId" }
          description: Replaces the selection with exactly these analyses. Mutually exclusive with enableFeatures.
        branch:
          type: string
          description: The scheduled branch. Defaults to the repository's default branch.

    RemoveContinuousTestingResult:
      type: object
      required: [repositoryId, branch, removed]
      properties:
        repositoryId: { type: string }
        branch: { type: string }
        removed: { type: boolean }

    CancelScanResult:
      type: object
      required: [scanId, status, cancelledJobs]
      properties:
        scanId: { type: string }
        status:
          $ref: "#/components/schemas/ScanStatus"
          description: Terminal status after cancellation (always CANCELLED).
        cancelledJobs:
          type: integer
          description: Number of in-flight jobs signalled to stop.

    InvestigateReportResult:
      type: object
      required: [publicId, scanId, claimsQueued]
      properties:
        publicId: { type: string }
        scanId:
          type: string
          description: The scan triaging this report's claims.
        claimsQueued:
          type: [integer, "null"]
          description: >-
            Claims queued for triage, or null when an investigation was already
            running and this call started nothing.

    SubmitReportRequest:
      type: object
      required: [title, body]
      properties:
        title:
          type: string
          maxLength: 500
          description: One line naming the flaw.
        body:
          type: string
          maxLength: 80000
          description: >-
            What the flaw is, how to reach it, and what it costs. Prose: this
            is read and split into claims, so write it for a reader rather
            than as fields. Anything past the limit would be stored and never
            read.
        claimedSeverity:
          type: [string, "null"]
          enum: [CRITICAL, HIGH, MEDIUM, LOW, INFO, null]
          description: >-
            What the reporter claims, which is not an assessment. It decides
            how closely the report is read, so an inflated claim costs the
            programme more.
        reporter:
          type: object
          description: >-
            Who found it, all self-asserted. Used for attribution on the
            advisory, never for authorization.
          properties:
            name: { type: [string, "null"] }
            email: { type: [string, "null"] }
            githubLogin: { type: [string, "null"] }

    SubmitReportResult:
      type: object
      required: [publicId, intakeState]
      properties:
        publicId:
          type: string
          description: The identifier `investigateReport` takes.
        intakeState:
          type: string
          description: >-
            Always PENDING here. The report is queued to be read and split
            into claims, and an investigation waits for COMPLETE.

    ChangeNote:
      type: object
      description: Optionally attach or reuse a note alongside a resolution change.
      properties:
        content: { type: string, description: Create a new note with this body. }
        existingNoteId: { type: string, description: Reuse an existing note by id. }

    FindingNoteResult:
      type: object
      required: [noteId, findingId]
      properties:
        noteId: { type: string }
        findingId: { type: string }

    FindingPinResult:
      type: object
      required: [findingId, noteId]
      properties:
        findingId: { type: string }
        noteId: { type: [string, "null"] }

    FindingSeverityResult:
      type: object
      required: [findingId, effectiveSeverity]
      properties:
        findingId: { type: string }
        userSeverity:
          oneOf:
            - { $ref: "#/components/schemas/Severity" }
            - { type: "null" }
        effectiveSeverity: { $ref: "#/components/schemas/Severity" }

    FindingResolutionResult:
      type: object
      required: [findingId, resolutionStatus, triageStatus]
      properties:
        findingId: { type: string }
        resolutionStatus: { $ref: "#/components/schemas/ResolutionStatus" }
        triageStatus:
          $ref: "#/components/schemas/TriageStatus"
          description: The triage status after the change. It moves when the change reopens a finding triage dismissed, or undoes that reopen.

    FindingTriageResult:
      type: object
      required: [findingId, triageStatus, previousTriageStatus, noteId]
      properties:
        findingId: { type: string }
        triageStatus: { $ref: "#/components/schemas/TriageStatus" }
        previousTriageStatus: { $ref: "#/components/schemas/TriageStatus" }
        noteId:
          type: [string, "null"]
          description: The comment the override added, or null without a note.

    AgentQuestion:
      type: object
      required: [id, repositoryId, branch, text, options, askedAt, asker]
      properties:
        id: { type: string }
        repositoryId: { type: string }
        branch:
          type: [string, "null"]
          description: The branch the analysis runs on. Null is the repository's default branch.
        text: { type: string }
        options:
          type: array
          items:
            type: object
            required: [label, description]
            properties:
              label: { type: string }
              description: { type: [string, "null"] }
        askedAt: { type: string, format: date-time }
        asker:
          type: string
          description: The analysis that asked.

    ResolutionReason:
      type: string
      description: >
        Short code for why a finding is being closed, chosen from the set
        offered for the `resolutionStatus` it is sent with; a code belonging to
        a different status is rejected with 400. Ignored for the open statuses
        (`NOT_STARTED`, `IN_PROGRESS`) and when `note` is also given. It is not
        stored as a field: it is recorded as a comment on the finding stating
        what was chosen, which is returned by the notes endpoints.


        Codes per status.
        `RESOLVED`: fixed_in_code, fixed_upstream, code_removed.
        `MITIGATED`: compensating_control, limited_exposure, monitored.
        `FALSE_POSITIVE`: not_reachable, guarded_elsewhere, intended_behavior,
        misread_code, bad_assumption.
        `WONT_FIX`: risk_accepted, out_of_scope, not_worth_fixing,
        code_being_removed.
        `DUPLICATE`: duplicate_of_finding, same_root_cause.
      enum:
        - fixed_in_code
        - fixed_upstream
        - code_removed
        - compensating_control
        - limited_exposure
        - monitored
        - not_reachable
        - guarded_elsewhere
        - intended_behavior
        - misread_code
        - bad_assumption
        - risk_accepted
        - out_of_scope
        - not_worth_fixing
        - code_being_removed
        - duplicate_of_finding
        - same_root_cause
      example: not_reachable

    PublishFindingRequest:
      type: object
      properties:
        noteId:
          type: string
          description: A note id on the finding to pin as the published note.
        withPassword:
          type: boolean
          description: >-
            True generates a new access password. False removes password
            protection. Omission preserves an existing password.

    PublishScanRequest:
      type: object
      properties:
        withPassword:
          type: boolean
          description: >-
            True generates a new access password. False removes password
            protection. Omission preserves an existing password.

    PublishArtifactResult:
      type: object
      required: [artifactId, publicId]
      properties:
        artifactId: { type: string }
        publicId: { type: string, description: "Slug in /public/{scans,findings}/<publicId>." }
        accessPassword:
          type: [string, "null"]
          description: The artifact's current access password, or null when it has no password.
