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

# Stage a scan for human launch

> Use this operation to hand a configured pentest to a human for launch. This operation does not launch a scan or reserve credits. First set up verified domains, connected repositories, saved test users, domain scan headers, uploads, and knowledge resources. Use create_test_user for test accounts and create_domain_scan_header for saved headers. The credentials and headers arrays must be absent or empty. Inline secrets are not accepted. Configure the targets and context with the same fields as createScan. Give the user launch_url from the response. That link opens Review & Launch in the dashboard. The human reviews the configuration and clicks Launch. A draft that this operation creates expires after seven days. Launch checks current access, targets, and billing again.



## OpenAPI

````yaml /openapi.json post /scans/drafts
openapi: 3.1.0
info:
  title: Strix API
  version: 1.0.0
  description: >-
    Public REST API for the Strix autonomous penetration testing platform.
    Manage scans, vulnerabilities, assets, schedules, API tokens, and webhooks.
servers:
  - url: /api/v1
    description: Strix v1 API
security:
  - BearerAuth: []
tags:
  - name: Scans
    description: Launch, monitor, and manage security scans.
  - name: Vulnerabilities
    description: View and triage discovered vulnerabilities.
  - name: Assets
    description: Domains and repositories registered for scanning.
  - name: Schedules
    description: Recurring scan schedules (Pro plan).
  - name: Search
    description: Search across issues, pentests, PR reviews, chats, assets and schedules.
  - name: Tokens
    description: Manage API tokens for authentication.
  - name: Webhooks
    description: Configure webhook subscriptions for real-time event notifications.
  - name: Organization
    description: Workspace configuration for the authenticated organization.
  - name: Members
    description: Manage organization members and roles.
  - name: Invitations
    description: List and revoke organization invitations.
  - name: PR Reviews
    description: Automated security review of pull requests.
  - name: Connectors
    description: Network connectors for scanning internal/private targets.
  - name: Knowledge
    description: >-
      Organization knowledge base: documents, policies, and repo profiles that
      steer the agent.
  - name: Uploads
    description: Upload source/code/documentation archives for whitebox scans.
  - name: Integrations
    description: Third-party integrations (GitLab, Bitbucket, ticketing).
  - name: Chat
    description: Conversational agent sessions.
  - name: Analytics
    description: Aggregate dashboard analytics.
  - name: Test Users
    description: >-
      Per-domain test accounts (with optional MFA) the agent authenticates as
      during scans.
  - name: License
    description: Self-hosted license state, entitlements, and aggregate usage.
  - name: Supply Chain
    description: >-
      SBOM inventory, supply-chain findings, scans, and policy for connected
      repositories.
  - name: CLI
    description: >-
      Device authorization endpoints that let the Strix CLI and coding agents
      sign in and receive an API token.
  - name: Billing
    description: Credit balance, agent-payable top-ups, and automatic top-up settings.
  - name: Workspaces
    description: List, create, and switch workspaces.
  - name: Asset Discovery
    description: >-
      Passive reconnaissance runs that map the organization's external attack
      surface, and the discovered-asset inventory they fill.
  - name: Containers
    description: >-
      Container registries, tracked images, image scans, findings, and SBOM
      components.
  - name: Run Logs
    description: Persisted engine logs and the diagnostics bundle of a self-hosted install.
paths:
  /scans/drafts:
    post:
      tags:
        - Scans
      summary: Stage a scan for human launch
      description: >-
        Use this operation to hand a configured pentest to a human for launch.
        This operation does not launch a scan or reserve credits. First set up
        verified domains, connected repositories, saved test users, domain scan
        headers, uploads, and knowledge resources. Use create_test_user for test
        accounts and create_domain_scan_header for saved headers. The
        credentials and headers arrays must be absent or empty. Inline secrets
        are not accepted. Configure the targets and context with the same fields
        as createScan. Give the user launch_url from the response. That link
        opens Review & Launch in the dashboard. The human reviews the
        configuration and clicks Launch. A draft that this operation creates
        expires after seven days. Launch checks current access, targets, and
        billing again.
      operationId: createScanDraft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScanRequest'
      responses:
        '201':
          description: The draft is ready for human review. No scan has started.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - launch_url
                  - expires_at
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Scan draft identifier.
                  launch_url:
                    type: string
                    format: uri
                    description: >-
                      Give this link to the human who will review and launch the
                      scan.
                  expires_at:
                    type: string
                    format: date-time
                    description: The time when the draft expires.
        '400':
          description: Invalid configuration, targets, or inline secrets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The caller cannot use the requested targets or configuration.
        '500':
          description: The server could not create the draft.
      security:
        - BearerAuth:
            - scans:write
components:
  schemas:
    CreateScanRequest:
      type: object
      description: >-
        At least one target (domain_ids, repository_ids, upload_ids, or
        internal_targets) should be provided.
      properties:
        cloud_connection_ids:
          type: array
          items:
            type: string
          description: >-
            Cloud connections this run may read. If you omit this field, the run
            uses the connections that apply to its targets. A connection with
            empty `applies_to_domain_ids` and `applies_to_repository_ids`
            applies to every run. A connection with values in those lists
            applies only to a run that targets one of the listed domains or
            repositories. Send an empty array for no cloud connections.
        concerns:
          description: >-
            Free-text security concerns to prioritize, for example `IDOR on the
            invoices API`.
          type: string
        connector_id:
          description: >-
            ID of a network connector that gives the agent access to a private
            network. Use `listConnectors` to find it.
          type: string
        context:
          description: >-
            Free-text background about the target that helps the agent, for
            example architecture notes or recent changes.
          type: string
        credentials:
          description: >-
            Test accounts the agent logs in with during the scan. Stored
            encrypted and never returned. Prefer saved test users where
            available.
          type: array
          items:
            type: object
            properties:
              username:
                type: string
              password:
                type: string
              notes:
                type: string
              mfa_method:
                type: string
                enum:
                  - none
                  - totp
                  - email_otp
                  - magic_link
                description: Multi-factor method for authenticated scans.
              totp_secret:
                type: string
                description: Base32 TOTP secret, used when mfa_method is `totp`.
              mfa_email:
                type: string
                format: email
                description: >-
                  Inbox to read one-time codes / magic links from, used when
                  mfa_method is `email_otp` or `magic_link`.
              login_url:
                type: string
                format: uri
                description: Login page URL for this credential set.
            required:
              - username
              - password
        domain_ids:
          description: UUIDs of verified domains to test. Use `listDomains` to find them.
          type: array
          items:
            type: string
            format: uuid
        domain_paths:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Map of domain ID to specific paths to scan.
        engagement_type:
          type: string
          enum:
            - code_review
            - live_test
            - internal_infra
            - compliance_pentest
          description: >-
            Which engagement type this run is. When omitted, source-only scopes
            infer `code_review`, domain scopes infer `live_test`, and internal
            targets infer `internal_infra`.
        focus:
          description: >-
            Free-text areas of the target to test first, for example `the
            checkout flow`.
          type: string
        headers:
          description: >-
            Custom HTTP headers the agent sends on every request, for example an
            API key header. Stored encrypted and never returned.
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              notes:
                type: string
            required:
              - name
              - value
        internal_targets:
          description: >-
            Hosts or URLs inside a private network to test through the
            connector, for example `http://10.0.0.5:8080`.
          type: array
          items:
            type: string
        knowledge_resource_pins:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/RunKnowledgeResourcePin'
          description: >-
            Provider resources selected for this run in addition to
            organization-wide pins.
        max_budget_usd:
          type: number
          exclusiveMinimum: 0
          maximum: 1000000
          description: >-
            Self-hosted only: stop the pentest gracefully once total LLM spend
            reaches this amount (USD). Omit for no limit. Spend is counted from
            the model config's Pricing when it is set. Otherwise it uses the
            cost the provider reports, or the LiteLLM price table.
        budget_policy:
          type: string
          enum:
            - stop
            - pause
          description: >-
            Self-hosted only: what happens when `max_budget_usd` is reached.
            `pause` parks every agent before its next model call until an
            operator resumes the scan with a higher limit or stops it (see `POST
            /scans/{scanId}/budget`); a paused scan waits with no deadline.
            `stop` ends the run at the limit. Defaults to `pause`. Ignored
            without `max_budget_usd`.
        model_config_id:
          type: string
          format: uuid
          description: >-
            Self-hosted installs and hosted organizations on their own LLM keys:
            run the scan with a named model config from Settings → LLM Models
            instead of the default assignment.
        notification_emails:
          type: array
          items:
            type: string
            format: email
          description: >-
            Extra addresses to CC on the completion email. Validated only when
            notify_on_completion is true.
        notify_on_completion:
          type: boolean
          description: Email the scan creator when the pentest finishes.
        org_knowledge_enabled:
          description: >-
            When true, the agent uses the organization knowledge base during the
            scan.
          type: boolean
        repository_branches:
          type: object
          additionalProperties:
            type: string
          description: Map of repository ID to branch name.
        repository_ids:
          description: >-
            UUIDs of connected repositories to test. Use `listRepositories` to
            find them.
          type: array
          items:
            type: string
            format: uuid
        test_user_ids:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Saved test users attach to domain targets they cover or to
            internal_infra scans on the same network.
        title:
          type: string
          maxLength: 120
          description: >-
            Custom scan title. When you set a title, the server does not
            generate one. The server trims the value.
        upload_ids:
          type: array
          items:
            type: string
          description: >-
            Completed upload IDs to attach. A repository upload can be the sole
            target of a code review or provide white-box context for a domain
            pentest.
    RunKnowledgeResourcePin:
      type: object
      additionalProperties: false
      properties:
        connection_id:
          type: string
          minLength: 1
          description: Organization cloud connection that owns the resource.
        page_id:
          type: string
          minLength: 1
          description: Provider-specific opaque resource identifier.
        label:
          type: string
          minLength: 1
          maxLength: 200
        url:
          type:
            - string
            - 'null'
          format: uri
        guidance:
          type: string
          maxLength: 500
          description: >-
            Optional context: what the resource holds and when Strix should read
            it.
      required:
        - connection_id
        - page_id
        - label
        - url
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable explanation of the error.
        code:
          type: string
          description: >-
            Stable machine-readable error code. `insufficient_scope` means the
            token does not hold the scope that this endpoint requires.
        required_scope:
          $ref: '#/components/schemas/ApiV1Scope'
          description: >-
            Scope that the caller must add to the token. Returned with the
            `insufficient_scope` code.
        docs:
          type: string
          format: uri
          description: Documentation page that explains how to resolve the error.
        hint:
          type: string
          description: >-
            One instruction that resolves the error. For `insufficient_scope`, a
            CLI session gets the `strix cloud session scopes set full` or `strix
            cloud login --scope-profile full` command, and an API token gets the
            settings page where the user creates a token with the scope. When
            the owner's role cannot hold the scope, the hint asks for a role
            change instead.
      required:
        - detail
    ApiV1Scope:
      type: string
      enum:
        - scans:read
        - scans:write
        - vulnerabilities:read
        - vulnerabilities:write
        - dependencies:read
        - schedules:read
        - schedules:write
        - assets:read
        - assets:write
        - organizations:read
        - organizations:write
        - members:read
        - members:write
        - invitations:read
        - invitations:write
        - webhooks:read
        - webhooks:write
        - tokens:write
        - audit:read
        - pr_reviews:read
        - pr_reviews:write
        - connectors:read
        - connectors:write
        - knowledge:read
        - knowledge:write
        - uploads:write
        - integrations:read
        - integrations:write
        - chat:read
        - chat:write
        - scans:message
        - analytics:read
        - llm:read
        - llm:write
        - test_users:read
        - test_users:write
        - discovery:read
        - discovery:write
        - license:read
        - supply_chain:read
        - supply_chain:write
        - billing:read
        - billing:write
        - containers:read
        - containers:write
        - logs:read
  responses:
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token obtained from the Tokens endpoint or CLI device login. Include
        as `Authorization: Bearer <token>`. Requests made with a managed CLI
        session also include `X-Strix-Workspace: <organization_id>` to pin a
        process to the workspace it started in; recovery endpoints report the
        current workspace after a concurrent switch.

````

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