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

# Initiate Scan

> Starts a new vulnerability scan for a given target. The target is specified as the final part of the URL path.



## OpenAPI

````yaml post /api/v1/scan/{target}
openapi: 3.0.3
info:
  title: OneFirewall Offensive Security API
  description: >-
    API endpoints for the Vulnix Scanner, user management, and configuration.


    ## Authentication


    Authentication is handled via API keys. You must include your key in the
    `api-key` header with every request.


    - **Header**: `api-key: {your-api-key}`

    - **Key Format**: A single secret string provided upon creation.


    ## Organization Context


    For endpoints requiring an organization context (like scanning), you can
    specify your organization ID:


    - **Header**: `X-Org-Id: {your-org-id}`

    - **Query Parameter**: `?org_id={your-org-id}`


    If not provided, the request will use your default organization.
  version: 1.0.0
servers:
  - url: https://vulnix0.com
    description: Production server
security:
  - apiKeyAuth: []
paths:
  /api/v1/scan/{target}:
    post:
      tags:
        - Scan Management
      summary: Initiate Scan
      description: >-
        Starts a new vulnerability scan for a given target. The target is
        specified as the final part of the URL path.
      parameters:
        - name: target
          in: path
          required: true
          description: Target to scan (domain, IP, or URL)
          schema:
            type: string
          examples:
            domain:
              value: grok.com
              summary: Simple domain
        - name: X-Org-Id
          in: header
          required: false
          description: Organization ID to associate the scan with
          schema:
            type: string
        - name: org_id
          in: query
          required: false
          description: Organization ID to associate the scan with
          schema:
            type: string
      requestBody:
        description: Optional advanced configuration for the scan
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdvancedScanConfig'
      responses:
        '202':
          description: Scan successfully initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
              examples:
                scanInitiated:
                  summary: Example scan initiation response
                  value:
                    message: >-
                      Scan initiated for target: grok.com (scanning on domain:
                      grok.com)
                    reqid: 95e201b5-93bf-4218-8b96-6fb23b8874d3
        '400':
          description: Invalid target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AdvancedScanConfig:
      type: object
      description: >-
        Advanced configuration options for initiating a scan. Useful for
        authenticated testing, api scanning, and fine-tuning crawler limits.
      properties:
        web:
          type: boolean
          description: Enable web application scanning mode
        fuzzing:
          type: boolean
          description: Enable fuzzing for deeper discovery
        follow_links:
          type: boolean
          description: Follow links during crawling
        exclude_paths:
          type: array
          items:
            type: string
          description: Paths to exclude from scanning (e.g., ['/logout', '/delete'])
        cookies:
          type: string
          description: Custom cookies to include in requests
        proxy_usage:
          type: string
          description: Proxy URL to route scan traffic through
        Authorization:
          type: string
          description: Authorization header value (e.g., Bearer token)
        openapi_spec:
          type: string
          description: Raw JSON or YAML OpenAPI 2.x/3.x specification for API DAST scanning
        openai_spec:
          type: string
          description: Alias for openapi_spec (handles common typos)
        custom_headers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
          description: Custom HTTP headers to include in requests
    ScanResponse:
      type: object
      properties:
        reqid:
          type: string
          description: Unique ID for this scan request
          format: uuid
        message:
          type: string
          example: 'Scan initiated for target: example.com'
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        error:
          type: string
          example: Error message description
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: A unique API Key.

````