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

# Start a scan

> Queues a scan of the domain's pages and returns one scan run per engine. Omit the body to scan every active page with the domain's own WCAG target and engines. With an API key, the domain's plan must include API triggers, or the request fails with `403` and `reason: api_triggers_not_entitled`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/domains/{slug}/scans
openapi: 3.1.0
info:
  title: ility API
  version: 1.0.0
  description: Read accessibility results and start scans in your ility workspace.
servers:
  - url: https://app.ilitylabs.com
security:
  - apiKey: []
tags:
  - name: Workspaces
  - name: Surfaces
  - name: Domains
  - name: Scans
  - name: Issues
paths:
  /v1/domains/{slug}/scans:
    post:
      tags:
        - Scans
      summary: Start a scan
      description: >-
        Queues a scan of the domain's pages and returns one scan run per engine.
        Omit the body to scan every active page with the domain's own WCAG
        target and engines. With an API key, the domain's plan must include API
        triggers, or the request fails with `403` and `reason:
        api_triggers_not_entitled`.
      parameters:
        - schema:
            type: string
            minLength: 1
          required: true
          name: slug
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScansRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanRunListResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Forbidden — viewer role, or an API key on a domain whose plan has no
            programmatic triggers (reason: 'api_triggers_not_entitled')
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Domain not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Active scan exists for one or more engines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanConflictResponse'
        '422':
          description: Precondition failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanPreconditionResponse'
components:
  schemas:
    CreateScansRequest:
      type: object
      properties:
        engine_ids:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
        wcag_level:
          type: string
          enum:
            - 2.0-A
            - 2.0-AA
            - 2.0-AAA
            - 2.1-A
            - 2.1-AA
            - 2.1-AAA
            - 2.2-A
            - 2.2-AA
            - 2.2-AAA
        scope:
          type: string
          enum:
            - all
            - unscanned
    ScanRunListResponse:
      type: array
      items:
        $ref: '#/components/schemas/ScanRun'
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
        reason:
          type: string
      required:
        - detail
    ScanConflictResponse:
      type: object
      properties:
        detail:
          type: string
        conflicts:
          type: array
          items:
            type: object
            properties:
              engine_id:
                type: string
                format: uuid
              engine_slug:
                type: string
              existing_scan_run:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                  started_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                required:
                  - id
                  - status
                  - started_at
            required:
              - engine_id
              - engine_slug
              - existing_scan_run
      required:
        - detail
        - conflicts
    ScanPreconditionResponse:
      type: object
      properties:
        detail:
          type: string
        reason:
          type: string
          enum:
            - no_active_pages
            - no_unscanned_pages
            - document_not_scannable
      required:
        - detail
        - reason
    ScanRun:
      type: object
      properties:
        id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        domain_id:
          type: string
          format: uuid
        engine_id:
          type: string
          format: uuid
        engine_slug:
          type: string
        scan_request_id:
          type: string
          format: uuid
        scope:
          type: string
        status:
          type: string
        trigger_source:
          type: string
        triggered_by_user_id:
          type:
            - string
            - 'null'
        config_snapshot:
          type: object
          additionalProperties: {}
        pages_scanned:
          type:
            - integer
            - 'null'
        pages_failed:
          type:
            - integer
            - 'null'
        issues_found:
          type:
            - integer
            - 'null'
        score:
          type:
            - integer
            - 'null'
        has_blocking:
          type: boolean
        error:
          type:
            - string
            - 'null'
        cancel_requested_at:
          type:
            - string
            - 'null'
          format: date-time
        pause_requested_at:
          type:
            - string
            - 'null'
          format: date-time
        paused_at:
          type:
            - string
            - 'null'
          format: date-time
        started_at:
          type:
            - string
            - 'null'
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - workspace_id
        - domain_id
        - engine_id
        - engine_slug
        - scan_request_id
        - scope
        - status
        - trigger_source
        - triggered_by_user_id
        - config_snapshot
        - pages_scanned
        - pages_failed
        - issues_found
        - score
        - has_blocking
        - error
        - cancel_requested_at
        - pause_requested_at
        - paused_at
        - started_at
        - completed_at
        - created_at
        - updated_at
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An ility API key, such as `ilk_1a2b3c4d_…`. Workspace owners create keys
        under Settings → API keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.