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

# Request a new scan

> Queues a scan for the given target. The scanner picks it up within seconds and the results are available via GET /scans. Counts against the plan's daily scan allowance, then scan credits; see Plans and limits.



## OpenAPI

````yaml /api-reference/openapi.yaml post /request-scan
openapi: 3.0.3
info:
  title: validate.al API
  description: >-
    Email validation, security scanning and account management, all at
    https://api.validate.al.
  version: '1.0'
servers:
  - url: https://api.validate.al/v1
security:
  - ApiKeyAuth: []
tags:
  - name: Email validation
  - name: Scanning
  - name: Account
  - name: Health
paths:
  /request-scan:
    post:
      tags:
        - Scanning
      summary: Request a new scan
      description: >-
        Queues a scan for the given target. The scanner picks it up within
        seconds and the results are available via GET /scans. Counts against the
        plan's daily scan allowance, then scan credits; see Plans and limits.
      operationId: requestScan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - target
              properties:
                target:
                  type: string
                  description: Hostname or URL to scan.
                  example: example.com
                scan_type:
                  type: string
                  description: Type of scan. Defaults to webapp.
                  enum:
                    - webapp
                    - dns-auth
                    - ip
                  default: webapp
      responses:
        '200':
          description: Scan queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  scan_id:
                    type: integer
                    example: 42
                  target:
                    type: string
                    example: example.com
                  status:
                    type: string
                    example: pending
                  message:
                    type: string
                    example: Scan queued. Check back for results.
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unknown `scan_type` or missing `target`.
        '429':
          $ref: '#/components/responses/LimitReached'
components:
  schemas:
    Error:
      description: Errors from scanning and account endpoints.
      type: object
      properties:
        detail:
          type: string
          description: Error message
    LimitError:
      type: object
      properties:
        detail:
          type: object
          properties:
            error:
              type: string
              example: Daily scan limit reached. It resets at 2026-10-05T00:00:00Z.
            limit:
              type: string
              enum:
                - scan
                - email check
            resets_at:
              type: string
              format: date-time
              example: '2026-10-05T00:00:00Z'
  responses:
    LimitReached:
      description: >-
        The plan's daily allowance (and any credits or welcome checks) is used
        up. Retry after `Retry-After` seconds, at `resets_at` (00:00 UTC).
      headers:
        Retry-After:
          description: Seconds until the allowance resets.
          schema:
            type: integer
            example: 3600
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LimitError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your validate.al API key, from the portal (Settings → API Key).

````

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