> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breachlens.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger a scan on an existing Repository

> Queues a scan for a repository already known to BreachLens. Requires the `scans:trigger` scope plus DEVELOPER role or higher.



## OpenAPI

````yaml /api-reference/openapi.json post /api/repos/{repoId}/scan
openapi: 3.1.0
info:
  title: BreachLens API
  version: 0.1.0
  description: >-
    Customer-facing scan API for BreachLens — trigger a scan, poll its status,
    and download SARIF. This is the same surface the `breachlens` CLI and the
    GitHub Action / GitLab templates drive.


    **Base URL:** your own BreachLens deployment (self-hosted or hosted edge).
    Set the `baseUrl` server variable in the playground to your deployment's
    full URL (including `https://`).


    **Auth:** a scoped API token minted in **Settings → API Tokens**
    (`scans:trigger` + `scans:read`), sent as `Authorization: Bearer blt_…`.
    Deployments fronted by Cloudflare Access ALSO require the
    `CF-Access-Client-Id` / `CF-Access-Client-Secret` service-token headers
    (optional fields on each request; leave blank for self-hosted).


    **Try it:** set the **baseUrl** server variable to your deployment's URL,
    add a `blt_` token, then click **Send**. (A browser/proxy request cannot
    clear a Cloudflare Access edge without a service token.)


    **Flow:** trigger (one target) → poll `GET /api/scans/{scanId}` until
    `COMPLETED` → download `GET /api/scans/{scanId}/export.sarif`.
servers:
  - url: '{baseUrl}'
    description: Your deployment
    variables:
      baseUrl:
        default: https://your-breachlens.example.com
        description: >-
          Full base URL of your BreachLens deployment — include https:// and no
          trailing slash (e.g. https://breachlens.acme.com). Paste the whole
          URL; do not add a second https://.
security:
  - bearerAuth: []
tags:
  - name: Scans
    description: Trigger scans, check status, export SARIF.
paths:
  /api/repos/{repoId}/scan:
    post:
      tags:
        - Scans
      summary: Trigger a scan on an existing Repository
      description: >-
        Queues a scan for a repository already known to BreachLens. Requires the
        `scans:trigger` scope plus DEVELOPER role or higher.
      operationId: triggerRepositoryScan
      parameters:
        - name: repoId
          in: path
          required: true
          schema:
            type: string
          description: BreachLens Repository ID (from its detail-page URL).
        - $ref: '#/components/parameters/CfAccessClientId'
        - $ref: '#/components/parameters/CfAccessClientSecret'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceScanBody'
      responses:
        '202':
          description: Scan queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanTriggerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    CfAccessClientId:
      name: CF-Access-Client-Id
      in: header
      required: false
      schema:
        type: string
      description: >-
        Cloudflare Access service-token client id (ends in .access). Only for
        CF-Access-fronted deployments; leave blank for self-hosted.
    CfAccessClientSecret:
      name: CF-Access-Client-Secret
      in: header
      required: false
      schema:
        type: string
      description: >-
        Cloudflare Access service-token secret. Pair it with
        CF-Access-Client-Id.
  schemas:
    ResourceScanBody:
      type: object
      properties:
        scanTypes:
          $ref: '#/components/schemas/ScanTypes'
      description: Optional body. Omit to run the server default scan set for the target.
    ScanTriggerResponse:
      type: object
      description: >-
        The scan id is returned as `scanJobId` (aliased as `id` on some
        endpoints). `repository` is present only for from-github auto-discovery.
      properties:
        scanJobId:
          type: string
          example: cmrasmw4702sdstu9j4iq1x55
        id:
          type: string
          description: Alias for scanJobId on some endpoints.
        repository:
          type: object
          properties:
            id:
              type: string
            fullName:
              type: string
              example: my-org/payments-api
            newlyCreated:
              type: boolean
              description: true when this call onboarded the repo for the first time.
      additionalProperties: true
    ScanTypes:
      type: array
      items:
        type: string
      example:
        - SAST
        - SCA
        - SECRET
        - IAC
      description: >-
        Scan tiers to run. Omit for the server default (`SAST, SCA, SECRET, IAC`
        for repositories). Valid values depend on target type.
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        message:
          type: string
      additionalProperties: true
  responses:
    Unauthorized:
      description: Missing, invalid, or expired API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid or expired API token
    Forbidden:
      description: Token missing a required scope, or role-gate failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: API token missing required scope
            required: scans:trigger
            granted:
              - scans:read
    NotFound:
      description: Resource not found in your active org.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Scan job not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: blt_ token
      description: >-
        Scoped API token from Settings → API Tokens (scopes: scans:trigger,
        scans:read).

````