# GENERATED FILE — DO NOT EDIT BY HAND.
#
# Produced from the zod request schemas in src/api/schemas by
#   npm run openapi:generate
#
# CI runs `npm run openapi:check`, which fails if this file is out of sync with
# the code, so request validation and these docs cannot silently diverge.
openapi: 3.0.0
info:
  title: DeepScraper API
  version: 1.0.0
  description: >-
    Open-source web scraping API — scrape, crawl, map, search, extract structured data, drive
    persistent browser sessions, and expose any site as a reusable endpoint.


    This file is GENERATED from the zod request schemas in `src/api/schemas`. Do not edit by hand —
    run `npm run openapi:generate`.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:3000
    description: Local instance
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
      description: API key. Required on every /api/* route.
  schemas:
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
      required:
        - success
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
      required:
        - success
        - error
    AsyncJobAccepted:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        id:
          type: string
        url:
          type: string
          description: Polling URL for this job
        status:
          type: string
      required:
        - success
        - id
        - url
        - status
  parameters: {}
paths:
  /api/scrape:
    post:
      tags:
        - Scrape
      summary: Scrape a URL to markdown, HTML, text or structured data
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                options:
                  type: object
                  properties:
                    waitForSelector:
                      type: string
                    waitForTimeout:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    actions:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - click
                              - scroll
                              - wait
                              - fill
                              - select
                          selector:
                            type: string
                          value:
                            type: string
                          position:
                            type: number
                          timeout:
                            type: number
                          optional:
                            type: boolean
                        required:
                          - type
                    skipCache:
                      type: boolean
                    cacheTtl:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    extractorFormat:
                      type: string
                      enum:
                        - html
                        - markdown
                        - text
                    onlyMainContent:
                      type: boolean
                    fitMarkdown:
                      type: boolean
                    useBrowser:
                      type: boolean
                    stealthMode:
                      type: boolean
                    skipTlsVerification:
                      type: boolean
                    extractionOptions:
                      nullable: true
              required:
                - url
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/scrape/async:
    post:
      tags:
        - Scrape
      summary: Submit a scrape as an async job
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                options:
                  type: object
                  properties:
                    waitForSelector:
                      type: string
                    waitForTimeout:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    actions:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - click
                              - scroll
                              - wait
                              - fill
                              - select
                          selector:
                            type: string
                          value:
                            type: string
                          position:
                            type: number
                          timeout:
                            type: number
                          optional:
                            type: boolean
                        required:
                          - type
                    skipCache:
                      type: boolean
                    cacheTtl:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    extractorFormat:
                      type: string
                      enum:
                        - html
                        - markdown
                        - text
                    onlyMainContent:
                      type: boolean
                    fitMarkdown:
                      type: boolean
                    useBrowser:
                      type: boolean
                    stealthMode:
                      type: boolean
                    skipTlsVerification:
                      type: boolean
                    extractionOptions:
                      nullable: true
              required:
                - url
      responses:
        '200':
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobAccepted'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/scrape/job/{id}:
    get:
      tags:
        - Scrape
      summary: Poll an async scrape job
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Async scrape job id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/extract-schema:
    post:
      tags:
        - Scrape
      summary: Extract structured data using a JSON Schema (LLM)
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                schema:
                  type: object
                  properties: {}
                options:
                  type: object
                  properties:
                    waitForSelector:
                      type: string
                    waitForTimeout:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    actions:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - click
                              - scroll
                              - wait
                              - fill
                              - select
                          selector:
                            type: string
                          value:
                            type: string
                          position:
                            type: number
                          timeout:
                            type: number
                          optional:
                            type: boolean
                        required:
                          - type
                    skipCache:
                      type: boolean
                    cacheTtl:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    extractorFormat:
                      type: string
                      enum:
                        - html
                        - markdown
                        - text
                    temperature:
                      type: number
                      minimum: 0
                      maximum: 2
                    maxTokens:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    instructions:
                      type: string
              required:
                - url
                - schema
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/summarize:
    post:
      tags:
        - Scrape
      summary: Scrape a URL and generate an AI summary
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                maxLength:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                options:
                  type: object
                  properties:
                    waitForSelector:
                      type: string
                    waitForTimeout:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    actions:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - click
                              - scroll
                              - wait
                              - fill
                              - select
                          selector:
                            type: string
                          value:
                            type: string
                          position:
                            type: number
                          timeout:
                            type: number
                          optional:
                            type: boolean
                        required:
                          - type
                    skipCache:
                      type: boolean
                    cacheTtl:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    extractorFormat:
                      type: string
                      enum:
                        - html
                        - markdown
                        - text
                    temperature:
                      type: number
                      minimum: 0
                      maximum: 2
              required:
                - url
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/cache:
    delete:
      tags:
        - Scrape
      summary: Invalidate the scrape cache (all, or a single URL)
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/crawl:
    post:
      tags:
        - Crawl
      summary: Start a multi-page crawl
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                limit:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                maxUrls:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                maxDepth:
                  type: integer
                  minimum: 0
                maxDiscoveryDepth:
                  type: integer
                  minimum: 0
                webhook:
                  type: string
                  format: uri
                includePaths:
                  type: array
                  items:
                    type: string
                excludePaths:
                  type: array
                  items:
                    type: string
                includePatterns:
                  type: array
                  items:
                    type: string
                excludePatterns:
                  type: array
                  items:
                    type: string
                crawlOptions:
                  type: object
                  properties:
                    maxConcurrentCrawlers:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                    browserPoolSize:
                      type: integer
                      minimum: 0
                      exclusiveMinimum: true
                scrapeOptions:
                  type: object
                  additionalProperties:
                    nullable: true
              required:
                - url
      responses:
        '200':
          description: Crawl started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobAccepted'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/crawl/estimate:
    post:
      tags:
        - Crawl
      summary: Pre-run size/cost estimate for a crawl
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                limit:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                maxDepth:
                  type: integer
                  minimum: 0
                scrapeOptions:
                  type: object
                  additionalProperties:
                    nullable: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/crawl/active:
    get:
      tags:
        - Crawl
      summary: List currently-active crawls
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/crawl/{jobId}:
    get:
      tags:
        - Crawl
      summary: Get crawl status and exported files
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Crawl job id
          required: true
          name: jobId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Crawl
      summary: Cancel a running crawl
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Crawl job id
          required: true
          name: jobId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/crawl/{jobId}/errors:
    get:
      tags:
        - Crawl
      summary: List per-page failures for a crawl
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Crawl job id
          required: true
          name: jobId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/crawl/{jobId}/stream:
    get:
      tags:
        - Crawl
      summary: Stream crawl pages as Server-Sent Events
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Crawl job id
          required: true
          name: jobId
          in: path
      responses:
        '200':
          description: SSE stream of pages as they complete
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/crawl/{jobId}/download/zip:
    get:
      tags:
        - Crawl
      summary: Download all crawled pages as a ZIP
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Crawl job id
          required: true
          name: jobId
          in: path
        - schema:
            type: string
            enum:
              - markdown
              - json
          required: false
          name: format
          in: query
      responses:
        '200':
          description: ZIP archive of crawled pages
          content:
            application/zip:
              schema:
                type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/crawl/{jobId}/download/json:
    get:
      tags:
        - Crawl
      summary: Download all crawled pages as one JSON array
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Crawl job id
          required: true
          name: jobId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/batch/scrape:
    post:
      tags:
        - Batch
      summary: Scrape many URLs concurrently
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                urls:
                  type: array
                  items:
                    type: string
                    format: uri
                  minItems: 1
                  maxItems: 100
                concurrency:
                  type: integer
                  minimum: 1
                  maximum: 10
                webhook:
                  type: string
                  format: uri
                timeout:
                  type: integer
                  minimum: 10000
                failFast:
                  type: boolean
                maxRetries:
                  type: integer
                  minimum: 0
                  maximum: 10
                options:
                  type: object
                  properties:
                    timeout:
                      type: integer
                      minimum: 1000
                      maximum: 300000
                    userAgent:
                      type: string
                      maxLength: 500
                    waitForTimeout:
                      type: integer
                      minimum: 0
                      maximum: 60000
              required:
                - urls
      responses:
        '200':
          description: Batch accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobAccepted'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/batch/scrape/{batchId}/status:
    get:
      tags:
        - Batch
      summary: Batch progress and results
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Batch id (UUID)
          required: true
          name: batchId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/batch/scrape/{batchId}/errors:
    get:
      tags:
        - Batch
      summary: Per-URL failures for a batch
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Batch id (UUID)
          required: true
          name: batchId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/batch/scrape/{batchId}/download/zip:
    get:
      tags:
        - Batch
      summary: Download batch results as a ZIP
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Batch id (UUID)
          required: true
          name: batchId
          in: path
      responses:
        '200':
          description: ZIP archive of batch results
          content:
            application/zip:
              schema:
                type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/batch/scrape/{batchId}/download/json:
    get:
      tags:
        - Batch
      summary: Download batch results as JSON
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Batch id (UUID)
          required: true
          name: batchId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/batch/scrape/{batchId}/download/{jobId}:
    get:
      tags:
        - Batch
      summary: Download a single result from a batch
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Batch id (UUID)
          required: true
          name: batchId
          in: path
        - schema:
            type: string
            description: Job id within the batch
          required: true
          name: jobId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/batch/scrape/{batchId}:
    delete:
      tags:
        - Batch
      summary: Cancel a batch
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Batch id (UUID)
          required: true
          name: batchId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/batch/cleanup:
    post:
      tags:
        - Batch
      summary: Clean up batch records older than N days
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 365
          required: false
          name: days
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/map:
    post:
      tags:
        - Map
      summary: Discover all URLs on a site
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                maxUrls:
                  type: integer
                  minimum: 1
                  maximum: 30000
                  default: 5000
                includeSubdomains:
                  type: boolean
                  default: true
                searchQuery:
                  type: string
                skipSitemaps:
                  type: boolean
                  default: false
                sitemapsOnly:
                  type: boolean
                  default: false
                useUrlIndex:
                  type: boolean
                  default: true
                timeoutMs:
                  type: integer
                  minimum: 1000
                  maximum: 300000
                  default: 60000
                includePatterns:
                  type: array
                  items:
                    type: string
                excludePatterns:
                  type: array
                  items:
                    type: string
              required:
                - url
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/map/health:
    get:
      tags:
        - Map
      summary: URL-discovery subsystem health
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/map/cache/stats:
    get:
      tags:
        - Map
      summary: URL-discovery cache statistics
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/map/cache/clear:
    post:
      tags:
        - Map
      summary: Clear the URL-discovery cache for a site
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
              required:
                - url
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/search:
    post:
      tags:
        - Search
      summary: Web search, optionally scraping each result
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 500
                limit:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  maximum: 50
                provider:
                  type: string
                  enum:
                    - duckduckgo
                    - searxng
                    - serper
                lang:
                  type: string
                  maxLength: 10
                scrapeResults:
                  type: boolean
                scrapeOptions:
                  type: object
                  additionalProperties:
                    nullable: true
              required:
                - query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/extract:
    post:
      tags:
        - Extract
      summary: Async multi-URL LLM extraction
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                urls:
                  type: array
                  items:
                    type: string
                    format: uri
                  maxItems: 1000
                url:
                  type: string
                  format: uri
                prompt:
                  type: string
                  maxLength: 5000
                schema:
                  nullable: true
                limit:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  maximum: 1000
                scrapeOptions:
                  type: object
                  additionalProperties:
                    nullable: true
      responses:
        '200':
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobAccepted'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/extract/{id}:
    get:
      tags:
        - Extract
      summary: Poll an extract job
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Extract job id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/extract-auto:
    post:
      tags:
        - Extract
      summary: Self-healing extraction — derives and caches CSS selectors, re-derives on breakage
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                fields:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 100
                      description:
                        type: string
                        maxLength: 500
                      type:
                        type: string
                        enum:
                          - text
                          - attribute
                          - html
                          - number
                          - list
                          - nested
                          - nested_list
                      attribute:
                        type: string
                        maxLength: 100
                      required:
                        type: boolean
                    required:
                      - name
                  minItems: 1
                  maxItems: 50
                cssSchema:
                  nullable: true
                forceReheal:
                  type: boolean
                scrapeOptions:
                  type: object
                  additionalProperties:
                    nullable: true
              required:
                - url
                - fields
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/llmstxt:
    post:
      tags:
        - Tools
      summary: Generate an llms.txt for a site
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                maxUrls:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  maximum: 500
                includeFullText:
                  type: boolean
              required:
                - url
      responses:
        '200':
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobAccepted'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/llmstxt/{id}:
    get:
      tags:
        - Tools
      summary: Poll an llms.txt job
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: llms.txt job id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/parse:
    post:
      tags:
        - Tools
      summary: Parse a document (PDF/DOCX/…) to markdown
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                url:
                  type: string
                  format: uri
                contentType:
                  type: string
                  maxLength: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/discover-apis:
    post:
      tags:
        - Tools
      summary: Surface a page’s underlying JSON/XHR endpoints
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                timeout:
                  type: integer
                  minimum: 1000
                  maximum: 120000
                includeNonJson:
                  type: boolean
              required:
                - url
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/reader:
    get:
      tags:
        - Tools
      summary: 'Scrape a URL to markdown; honours Accept: text/markdown'
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            format: uri
            description: URL to read
          required: true
          name: url
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/usage:
    get:
      tags:
        - Ops
      summary: API key usage and quota
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/proxies:
    get:
      tags:
        - Ops
      summary: Proxy pool health
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/agent:
    post:
      tags:
        - Agent
      summary: Autonomous navigation toward a natural-language goal
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 5000
                schema:
                  nullable: true
                maxSteps:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  maximum: 20
                onlyMainContent:
                  type: boolean
                fitMarkdown:
                  type: boolean
              required:
                - url
                - prompt
      responses:
        '200':
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobAccepted'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/agent/{id}:
    get:
      tags:
        - Agent
      summary: Poll an agent run
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Agent task id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/sessions:
    post:
      tags:
        - Sessions
      summary: Create a persistent browser session
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userAgent:
                  type: string
                  maxLength: 500
                viewport:
                  type: object
                  properties:
                    width:
                      type: integer
                      minimum: 200
                      maximum: 4000
                    height:
                      type: integer
                      minimum: 200
                      maximum: 4000
                  required:
                    - width
                    - height
                initialUrl:
                  type: string
                  format: uri
                proxy:
                  type: object
                  properties:
                    server:
                      type: string
                      maxLength: 300
                    username:
                      type: string
                      maxLength: 200
                    password:
                      type: string
                      maxLength: 200
                  required:
                    - server
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - Sessions
      summary: List active sessions
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/sessions/{id}:
    get:
      tags:
        - Sessions
      summary: Get a session
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Session id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Sessions
      summary: Close a session
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Session id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/sessions/{id}/action:
    post:
      tags:
        - Sessions
      summary: Run an action in a session (navigate, click, scrape, …)
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Session id
          required: true
          name: id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - navigate
                    - click
                    - type
                    - fill
                    - select
                    - scroll
                    - waitForSelector
                    - wait
                    - screenshot
                    - scrape
                    - evaluate
                    - back
                    - forward
                    - reload
                    - content
                url:
                  type: string
                  format: uri
                selector:
                  type: string
                  maxLength: 2000
                value:
                  type: string
                text:
                  type: string
                position:
                  type: number
                timeout:
                  type: integer
                  minimum: 0
                  maximum: 120000
                script:
                  type: string
                  maxLength: 20000
                fullPage:
                  type: boolean
                formats:
                  type: array
                  items:
                    type: string
                  maxItems: 6
                onlyMainContent:
                  type: boolean
                fitMarkdown:
                  type: boolean
                waitUntil:
                  type: string
                  enum:
                    - load
                    - domcontentloaded
                    - networkidle
                    - commit
              required:
                - type
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/sites:
    post:
      tags:
        - Sites
      summary: Create a reusable site spec (becomes an MCP tool)
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 48
                description:
                  type: string
                  maxLength: 500
                url:
                  type: string
                  minLength: 1
                  maxLength: 2000
                params:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 60
                      description:
                        type: string
                        maxLength: 500
                      required:
                        type: boolean
                    required:
                      - name
                  maxItems: 20
                fields:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 100
                      description:
                        type: string
                        maxLength: 500
                      type:
                        type: string
                        enum:
                          - text
                          - attribute
                          - html
                          - number
                          - list
                          - nested
                          - nested_list
                      attribute:
                        type: string
                        maxLength: 100
                      required:
                        type: boolean
                    required:
                      - name
                  minItems: 1
                  maxItems: 50
                cssSchema:
                  nullable: true
                sampleParams:
                  type: object
                  additionalProperties:
                    nullable: true
                sessionId:
                  type: string
                  maxLength: 100
                verify:
                  type: boolean
              required:
                - name
                - url
                - fields
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - Sites
      summary: List site specs
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/sites/{id}:
    get:
      tags:
        - Sites
      summary: Get a site spec
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Site spec id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Sites
      summary: Delete a site spec
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Site spec id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/sites/{id}/run:
    post:
      tags:
        - Sites
      summary: Run a site spec by id
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Site spec id
          required: true
          name: id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                params:
                  type: object
                  additionalProperties:
                    nullable: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/sites/by-name/{name}/run:
    post:
      tags:
        - Sites
      summary: Run a site spec by name
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Site spec name (slug)
          required: true
          name: name
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                params:
                  type: object
                  additionalProperties:
                    nullable: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/sites/{id}/verify:
    post:
      tags:
        - Sites
      summary: Verify a spec still extracts correctly (self-heals on drift)
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            description: Site spec id
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /health:
    get:
      tags:
        - Ops
      summary: Liveness probe
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /health/ready:
    get:
      tags:
        - Ops
      summary: Readiness probe (dependencies reachable)
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /metrics:
    get:
      tags:
        - Ops
      summary: Prometheus metrics
      responses:
        '200':
          description: Prometheus exposition format
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'