openapi: 3.0.0
paths:
  /api/v1/files:
    get:
      operationId: FilesController_listFiles_v1
      parameters:
        - name: page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 1000
            default: 1
            type: number
        - name: per_page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 100
            default: 15
            type: number
        - name: sort
          required: false
          in: query
          description: >-
            Sort keys, e.g. -createdAt or filename,-createdAt (prefix - =
            descending).
          schema:
            example: -createdAt
            type: string
      responses:
        '200':
          description: Paginated safe file registry.
      security:
        - bearer: []
      summary: List organization files without internal storage paths.
      tags:
        - files
  /api/v1/files/groups:
    get:
      operationId: FilesController_listFileGroups_v1
      parameters:
        - name: page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 1000
            default: 1
            type: number
        - name: per_page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 100
            default: 15
            type: number
        - name: sort
          required: false
          in: query
          description: >-
            Sort keys, e.g. -createdAt or filename,-createdAt (prefix - =
            descending).
          schema:
            example: -createdAt
            type: string
        - name: product_code
          required: false
          in: query
          description: >-
            Only requests of this product: an API product code,
            `batch_web_scraping` or `website_crawler`.
          schema:
            example: airbnb_search
            type: string
      responses:
        '200':
          description: Paginated file records without internal storage paths.
      security:
        - bearer: []
      summary: >-
        List the file registry grouped by request: one record per request with
        its product and every format of its result.
      tags:
        - files
  /api/v1/files/{id}/content:
    get:
      operationId: FilesController_getFileContent_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: format
          required: false
          in: query
          description: >-
            Serve only this part of a batch item's content JSON (its Markdown or
            Text) instead of the whole file.
          schema:
            type: string
            enum:
              - markdown
              - text
      responses:
        '200':
          description: Inline content preview without internal storage location.
      security:
        - bearer: []
      summary: Preview small text-like file content inline.
      tags:
        - files
  /api/v1/files/{id}/raw:
    get:
      operationId: FilesController_streamFile_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
      security:
        - x-api-key: []
        - bearer: []
      summary: Stream the whole file of the current organization (any size or type).
      tags:
        - files
  /api/v1/files/{id}/download-token:
    post:
      operationId: FilesController_createDownloadToken_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: Download token and platform-proxied download URL.
      security:
        - bearer: []
      summary: Create short-lived file download token.
      tags:
        - files
  /api/v1/files/{id}/download:
    get:
      operationId: FilesController_downloadFile_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: format
          required: false
          in: query
          description: >-
            Serve only this part of a batch item's content JSON (its Markdown or
            Text) instead of the whole file.
          schema:
            type: string
            enum:
              - markdown
              - text
        - name: x-download-token
          in: header
          description: >-
            One-time token from `POST /api/v1/files/{id}/download-token`; never
            in the URL.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
      summary: Stream a file through Platform API using a short-lived token.
      tags:
        - files
  /api/v1/jobs:
    get:
      operationId: JobsController_listJobs_v1
      parameters:
        - name: tab
          required: false
          in: query
          schema:
            default: api_requests
            type: string
            enum:
              - api_requests
              - batch_jobs
              - no_code_jobs
              - crawler_jobs
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - queued
              - running
              - success
              - failed
              - blocked
              - timeout
              - stopped
        - name: search
          required: false
          in: query
          schema:
            example: example.com
            type: string
        - name: date_from
          required: false
          in: query
          schema:
            example: '2026-06-01'
            type: string
        - name: date_to
          required: false
          in: query
          schema:
            example: '2026-06-05'
            type: string
        - name: api_key_id
          required: false
          in: query
          description: >-
            API requests tab only: requests made with this API key of the
            organization.
          schema:
            format: uuid
            type: string
        - name: product_code
          required: false
          in: query
          description: >-
            API requests, no-code and crawler tabs: exact product code of the
            job.
          schema:
            example: web_scraping_api
            type: string
        - name: target_http_status
          required: false
          in: query
          description: >-
            API requests tab only: exact target HTTP status (404) or class
            (2xx…5xx).
          schema:
            example: 4xx
            type: string
        - name: category
          required: false
          in: query
          description: >-
            API requests tab only: billable result or non-charged failure
            category.
          schema:
            type: string
            enum:
              - target_response_received
              - target_http_error
              - target_empty_content
              - target_block_page_returned
              - extraction_empty
              - validation_error
              - invalid_api_key
              - insufficient_credits
              - concurrency_limit_exceeded
              - ssrf_blocked
              - proxy_error
              - network_error
              - browser_runtime_error
              - worker_internal_error
              - storage_error
              - platform_timeout
              - anti_bot_challenge
              - response_too_large
        - name: sort
          required: false
          in: query
          description: >-
            Sort keys, e.g. -createdAt or status,-credits (prefix - =
            descending).
          schema:
            example: -createdAt
            type: string
        - name: page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 1000
            example: 1
            type: number
        - name: per_page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 100
            example: 15
            type: number
      responses:
        '200':
          description: Paginated unified jobs list.
      security:
        - x-api-key: []
        - bearer: []
      summary: List API requests, batch jobs and no-code scraper jobs.
      tags:
        - jobs
  /api/v1/jobs/recent:
    get:
      operationId: JobsController_listRecentJobs_v1
      parameters:
        - name: page
          required: false
          in: query
          description: '`meta.total` counts only the jobs this window can reach.'
          schema:
            minimum: 1
            maximum: 50
            example: 1
            type: number
        - name: per_page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 20
            example: 8
            type: number
      responses:
        '200':
          description: Recent normalized jobs.
      security:
        - x-api-key: []
        - bearer: []
      summary: List recent jobs for dashboard widgets.
      tags:
        - jobs
  /api/v1/jobs/{jobId}:
    get:
      operationId: JobsController_getJobDetail_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Unified job detail.
      security:
        - x-api-key: []
        - bearer: []
      summary: Get sanitized unified job diagnostics.
      tags:
        - jobs
  /api/v1/scrape/requests/{scrapeRequestId}:
    get:
      operationId: JobsController_getScrapeRequestDiagnostics_v1
      parameters:
        - name: scrapeRequestId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Scrape request diagnostics detail.
      security:
        - x-api-key: []
        - bearer: []
      summary: Get full sanitized scrape request diagnostics.
      tags:
        - jobs
  /api/v1/scrape/requests/{scrapeRequestId}/attempts:
    get:
      operationId: JobsController_listScrapeRequestAttempts_v1
      parameters:
        - name: scrapeRequestId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Scrape request attempts.
      security:
        - x-api-key: []
        - bearer: []
      summary: List sanitized proxy/browser attempts for a scrape request.
      tags:
        - jobs
  /api/v1/scrape/requests/{scrapeRequestId}/events:
    get:
      operationId: JobsController_getScrapeRequestEvents_v1
      parameters:
        - name: scrapeRequestId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Scrape request events.
      security:
        - x-api-key: []
        - bearer: []
      summary: List sanitized audit/webhook/ingestion events for a scrape request.
      tags:
        - jobs
  /api/v1/scrape/jobs/{jobId}:
    delete:
      operationId: JobsController_stopJob_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Updated unified job detail.
      security:
        - x-api-key: []
        - bearer: []
      summary: >-
        Stop a queued/running batch, crawler or scraper job. A single API
        request answers 409 SCRAPE_REQUEST_CANNOT_BE_STOPPED.
      tags:
        - jobs
  /api/v1/scrape/web/async:
    post:
      operationId: BatchScrapingController_createAsyncWebScrape_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAsyncWebScrapeDto'
      responses:
        '201':
          description: Created async request (a one-item job).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncWebScrapeJobResponse'
        '400':
          description: 'VALIDATION_ERROR: the request body is invalid.'
        '403':
          description: >-
            INSUFFICIENT_CREDITS: the balance cannot cover the request;
            SSRF_BLOCKED: the target URL is not public;
            PLAN_FEATURE_NOT_AVAILABLE: the plan does not include it.
        '422':
          description: >-
            WEBHOOK_SECRET_NOT_CONFIGURED: webhookUrl is set but the request
            webhook signing secret was never created; VALIDATION_ERROR:
            webhookUrl is not a public http(s) URL; API_PRODUCT_NOT_EXECUTABLE:
            the Web Scraping API product is disabled; TARGET_HOST_NOT_FOUND: the
            target hostname does not exist in DNS.
        '429':
          description: >-
            CONCURRENCY_LIMIT_EXCEEDED: every concurrency slot of the plan is
            busy; RATE_LIMIT_EXCEEDED: the API key rate limit is reached.
        '503':
          description: >-
            TARGET_DNS_UNAVAILABLE: the target hostname could not be resolved
            right now; retry after details.retry_after_ms.
      security:
        - x-api-key: []
        - bearer: []
      summary: >-
        Run one Web Scraping API request in the background; the result is polled
        or posted to webhookUrl.
      tags:
        - batch-scraping
  /api/v1/scrape/web/async/{jobId}:
    get:
      description: >-
        Poll until status is terminal (finished, failed, stopped or skipped);
        result then carries the outcome, credits charged and result file ids.
      operationId: BatchScrapingController_getAsyncWebScrape_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: The async request and its result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncWebScrapeJobResponse'
        '404':
          description: >-
            BATCH_JOB_NOT_FOUND: no async request with this id in the
            organization.
      security:
        - x-api-key: []
        - bearer: []
      summary: Get an async Web Scraping API request with its result.
      tags:
        - batch-scraping
  /api/v1/scrape/batch/web:
    post:
      operationId: BatchScrapingController_createBatchWebScrape_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatchWebScrapeDto'
      responses:
        '201':
          description: Created batch job summary.
      security:
        - x-api-key: []
        - bearer: []
      summary: Create an asynchronous batch Web Scraping API job.
      tags:
        - batch-scraping
  /api/v1/scrape/batch/web/{jobId}:
    get:
      operationId: BatchScrapingController_getBatchWebScrape_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
      security:
        - x-api-key: []
        - bearer: []
      summary: Get batch Web Scraping API job status.
      tags:
        - batch-scraping
  /api/v1/scrape/batch/web/{jobId}/stop:
    post:
      operationId: BatchScrapingController_stopBatchWebScrape_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: Stopped batch job summary.
      security:
        - x-api-key: []
        - bearer: []
      summary: Stop an asynchronous batch Web Scraping API job.
      tags:
        - batch-scraping
  /api/v1/scrape/batch/web/{jobId}/results:
    get:
      operationId: BatchScrapingController_listBatchWebScrapeResults_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 1000
            example: 1
            type: number
        - name: per_page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 100
            example: 100
            type: number
        - name: status
          required: false
          in: query
          description: Optional item status filter. Omit or pass all to return every item.
          schema:
            example: finished
            type: string
            enum:
              - all
              - queued
              - running
              - stopping
              - stopped
              - finished
              - failed
              - skipped
        - name: sort
          required: false
          in: query
          description: >-
            Optional sort, e.g. itemIndex, -createdAt, status,-creditsSpent.
            Unknown fields are ignored.
          schema:
            example: -createdAt
            type: string
      responses:
        '200':
          description: ''
      security:
        - x-api-key: []
        - bearer: []
      summary: Get paginated batch Web Scraping API item results.
      tags:
        - batch-scraping
  /api/v1/scrape/batch/web/{jobId}/export:
    get:
      description: >-
        Streams the items in input order. Items without content (failed, still
        running, or past file retention) have content null in json and are left
        out of markdown and text. csv is the status table: one row per item,
        without content.
      operationId: BatchScrapingController_exportBatchWebScrapeResults_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
        - name: format
          required: true
          in: query
          description: >-
            json: every item with its outcome and content (what a synchronous
            request returns in data.content); markdown and text: the pages one
            after another, each under its URL; csv: one status row per item,
            without content.
          schema:
            example: json
            type: string
            enum:
              - json
              - markdown
              - text
              - csv
        - name: status
          required: false
          in: query
          description: >-
            Only the items in this status. Omit or pass all to export every
            item.
          schema:
            example: failed
            type: string
            enum:
              - all
              - queued
              - running
              - stopping
              - stopped
              - finished
              - failed
              - skipped
      responses:
        '200':
          description: The merged results file, as an attachment.
        '400':
          description: >-
            VALIDATION_ERROR: format is not json, markdown, text or csv, or
            status is unknown.
        '404':
          description: 'BATCH_JOB_NOT_FOUND: no batch job with this id in the organization.'
      security:
        - x-api-key: []
        - bearer: []
      summary: >-
        Download every batch item in one file: its content, or the status table
        as CSV.
      tags:
        - batch-scraping
  /api/v1/api-products:
    get:
      operationId: ApiProductsController_listProducts_v1
      parameters:
        - name: sort
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: API product catalog.
      security:
        - bearer: []
      summary: List metadata-driven API products.
      tags:
        - api-products
  /api/v1/api-products/{code}:
    get:
      operationId: ApiProductsController_getProductByCode_v1
      parameters:
        - name: code
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: API product detail with metadata.
      security:
        - bearer: []
      summary: Get API product detail by code.
      tags:
        - api-products
  /api/v1/api-products/{code}/parameters:
    get:
      operationId: ApiProductsController_listParameters_v1
      parameters:
        - name: code
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: API product parameters.
      security:
        - bearer: []
      summary: Get API product parameters for dynamic forms.
      tags:
        - api-products
  /api/v1/api-products/{code}/examples:
    get:
      operationId: ApiProductsController_listExamples_v1
      parameters:
        - name: code
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: API product examples.
      security:
        - bearer: []
      summary: Get API product request/response examples.
      tags:
        - api-products
  /api/v1/api-products/{code}/pricing-estimate:
    get:
      operationId: ApiProductsController_getPricingEstimateMetadata_v1
      parameters:
        - name: code
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Pricing estimate metadata.
      security:
        - bearer: []
      summary: Get pricing estimate metadata for Scraper API.
      tags:
        - api-products
  /api/v1/webhooks:
    get:
      operationId: WebhooksController_listEndpoints_v1
      parameters:
        - name: page
          required: false
          in: query
          description: Page number.
          schema:
            maximum: 1000
            type: number
        - name: per_page
          required: false
          in: query
          description: Items per page.
          schema:
            type: number
        - name: status
          required: false
          in: query
          description: Filter by endpoint status.
          schema:
            type: string
            enum:
              - active
              - disabled
        - name: sort
          required: false
          in: query
          description: >-
            Sort keys, e.g. -createdAt or url,-createdAt (prefix - =
            descending).
          schema:
            example: -createdAt
            type: string
      responses:
        '200':
          description: Paginated webhook endpoints without secrets.
      security:
        - bearer: []
      summary: List webhook endpoints for current organization.
      tags:
        - webhooks
    post:
      operationId: WebhooksController_createEndpoint_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointDto'
      responses:
        '201':
          description: Created webhook endpoint with one-time signing secret.
      security:
        - bearer: []
      summary: Create webhook endpoint. Signing secret is returned once.
      tags:
        - webhooks
  /api/v1/webhooks/deliveries:
    get:
      operationId: WebhooksController_listDeliveries_v1
      parameters:
        - name: page
          required: false
          in: query
          description: Page number.
          schema:
            maximum: 1000
            type: number
        - name: per_page
          required: false
          in: query
          description: Items per page.
          schema:
            type: number
        - name: endpointId
          required: false
          in: query
          description: Filter by webhook endpoint id.
          schema:
            type: string
        - name: eventType
          required: false
          in: query
          description: Filter by event type.
          schema:
            type: string
            enum:
              - scrape.request.finished
              - scrape.request.failed
              - batch.job.started
              - batch.job.finished
              - scraper.job.started
              - scraper.job.finished
              - scraper.job.failed
        - name: sort
          required: false
          in: query
          description: >-
            Sort keys, e.g. -createdAt or status,-createdAt (prefix - =
            descending).
          schema:
            example: -createdAt
            type: string
      responses:
        '200':
          description: Paginated webhook delivery logs.
      security:
        - bearer: []
      summary: List webhook delivery logs for current organization.
      tags:
        - webhooks
  /api/v1/webhooks/{id}/deliveries:
    get:
      operationId: WebhooksController_listEndpointDeliveries_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: page
          required: false
          in: query
          description: Page number.
          schema:
            maximum: 1000
            type: number
        - name: per_page
          required: false
          in: query
          description: Items per page.
          schema:
            type: number
        - name: endpointId
          required: false
          in: query
          description: Filter by webhook endpoint id.
          schema:
            type: string
        - name: eventType
          required: false
          in: query
          description: Filter by event type.
          schema:
            type: string
            enum:
              - scrape.request.finished
              - scrape.request.failed
              - batch.job.started
              - batch.job.finished
              - scraper.job.started
              - scraper.job.finished
              - scraper.job.failed
        - name: sort
          required: false
          in: query
          description: >-
            Sort keys, e.g. -createdAt or status,-createdAt (prefix - =
            descending).
          schema:
            example: -createdAt
            type: string
      responses:
        '200':
          description: Paginated webhook delivery logs for one endpoint.
      security:
        - bearer: []
      summary: List delivery logs for a webhook endpoint.
      tags:
        - webhooks
  /api/v1/webhooks/deliveries/{id}/retry:
    post:
      operationId: WebhooksController_retryDelivery_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: Webhook delivery retry was queued.
      security:
        - bearer: []
      summary: Retry a failed webhook delivery immediately.
      tags:
        - webhooks
  /api/v1/webhooks/request-signing-secret:
    post:
      operationId: WebhooksController_rotateRequestSigningSecret_v1
      parameters: []
      responses:
        '201':
          description: >-
            Request webhook signing secret created or rotated; the previous
            secret stops verifying at once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestWebhookSigningSecretResponse'
        '403':
          description: 'PERMISSION_DENIED: the member lacks the webhooks:manage permission.'
      security:
        - bearer: []
      summary: >-
        Create or rotate the request webhook signing secret: it signs the
        webhookUrl deliveries of async scrape requests. Returned once.
      tags:
        - webhooks
  /api/v1/webhooks/{id}/rotate-secret:
    post:
      operationId: WebhooksController_rotateEndpointSecret_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: Webhook signing secret rotated.
      security:
        - bearer: []
      summary: Rotate webhook signing secret. New secret is returned once.
      tags:
        - webhooks
  /api/v1/webhooks/{id}:
    patch:
      operationId: WebhooksController_updateEndpoint_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookEndpointDto'
      responses:
        '200':
          description: Updated webhook endpoint.
      security:
        - bearer: []
      summary: Update webhook endpoint.
      tags:
        - webhooks
    delete:
      operationId: WebhooksController_deleteEndpoint_v1
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Disabled webhook endpoint.
      security:
        - bearer: []
      summary: Disable webhook endpoint.
      tags:
        - webhooks
  /api/v1/scrapers/crawler/jobs:
    post:
      operationId: CrawlerController_createCrawlerJob_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCrawlerJobDto'
      responses:
        '201':
          description: Created Website Crawler job summary.
      security:
        - x-api-key: []
        - bearer: []
      summary: Create Website Crawler job.
      tags:
        - website-crawler
  /api/v1/scrapers/jobs/{jobId}:
    get:
      operationId: CrawlerController_getCrawlerJob_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
      security:
        - x-api-key: []
        - bearer: []
      summary: Get no-code scraper or crawler job status.
      tags:
        - website-crawler
    delete:
      operationId: CrawlerController_stopCrawlerJob_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
      security:
        - x-api-key: []
        - bearer: []
      summary: Stop Website Crawler job.
      tags:
        - website-crawler
  /api/v1/scrapers/jobs/{jobId}/results:
    get:
      operationId: CrawlerController_listCrawlerResults_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 1000
            example: 1
            type: number
        - name: per_page
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 100
            example: 100
            type: number
      responses:
        '200':
          description: ''
      security:
        - x-api-key: []
        - bearer: []
      summary: Get paginated Website Crawler page results.
      tags:
        - website-crawler
  /api/v1/usage/me:
    get:
      operationId: UsageController_getUsageMe_v1
      parameters: []
      responses:
        '200':
          description: ''
      security:
        - x-api-key: []
        - bearer: []
      summary: Get current organization credits, concurrency and usage summary.
      tags:
        - usage
  /api/v1/scrape/web:
    post:
      operationId: ScrapingApiController_scrapeWeb_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeWebDto'
      responses:
        '201':
          description: Web Scraping API terminal response.
      security:
        - x-api-key: []
        - bearer: []
      summary: Run synchronous Web Scraping API request.
      tags:
        - scraping-api
  /api/v1/scrape/zillow/listing:
    get:
      operationId: ZillowController_runListing_v1
      parameters:
        - name: city
          required: false
          in: query
          description: Target city, e.g. Chicago.
          schema:
            example: Chicago
            type: string
        - name: state
          required: false
          in: query
          description: Two-letter US state code, e.g. IL.
          schema:
            example: IL
            type: string
        - name: neighborhood
          required: false
          in: query
          description: Optional neighborhood, e.g. Lincoln Park.
          schema:
            example: Lincoln Park
            type: string
        - name: listing_status
          required: false
          in: query
          description: Market to search. Defaults to for_sale.
          schema:
            example: for_sale
            type: string
            enum:
              - for_sale
              - for_rent
              - sold
        - name: home_types
          required: false
          in: query
          description: Home categories to include.
          schema:
            example:
              - houses
              - condos
            type: array
            items:
              type: string
              enum:
                - houses
                - apartments
                - condos
                - townhomes
                - manufactured
                - lots_land
                - multi_family
        - name: min_price
          required: false
          in: query
          description: Minimum price in USD (monthly rent for rentals).
          schema:
            example: 250000
            type: number
        - name: max_price
          required: false
          in: query
          description: Maximum price in USD (monthly rent for rentals).
          schema:
            example: 500000
            type: number
        - name: min_bedrooms
          required: false
          in: query
          description: Minimum bedrooms (0 = studio).
          schema:
            example: 2
            type: number
        - name: max_bedrooms
          required: false
          in: query
          description: Maximum bedrooms.
          schema:
            example: 4
            type: number
        - name: min_bathrooms
          required: false
          in: query
          description: Minimum bathrooms.
          schema:
            example: 2
            type: number
        - name: page
          required: false
          in: query
          description: 1-based result page. Defaults to 1.
          schema:
            example: 2
            type: number
        - name: limit
          required: false
          in: query
          description: Maximum listings to return (1..41).
          schema:
            example: 41
            type: number
        - name: include_detail
          required: false
          in: query
          description: Also scrape each listing detail page (billed extra per card).
          schema:
            example: true
            type: boolean
        - name: min_square_feet
          required: false
          in: query
          description: Minimum living area in square feet.
          schema:
            example: 1200
            type: number
        - name: max_square_feet
          required: false
          in: query
          description: Maximum living area in square feet.
          schema:
            example: 2500
            type: number
        - name: min_lot_size
          required: false
          in: query
          description: Minimum lot size in square feet.
          schema:
            example: 3000
            type: number
        - name: max_lot_size
          required: false
          in: query
          description: Maximum lot size in square feet.
          schema:
            example: 10000
            type: number
        - name: min_year_built
          required: false
          in: query
          description: Earliest construction year.
          schema:
            example: 1990
            type: number
        - name: max_year_built
          required: false
          in: query
          description: Latest construction year.
          schema:
            example: 2024
            type: number
        - name: max_hoa_fee
          required: false
          in: query
          description: Maximum monthly HOA fee in USD.
          schema:
            example: 300
            type: number
        - name: max_days_on_zillow
          required: false
          in: query
          description: Only listings published within this many days.
          schema:
            example: 30
            type: number
        - name: sort
          required: false
          in: query
          description: Result ordering.
          schema:
            example: newest
            type: string
            enum:
              - relevance
              - newest
              - price_high_low
              - price_low_high
              - bedrooms
              - bathrooms
              - square_feet
              - lot_size
        - name: keywords
          required: false
          in: query
          description: Free-text keyword filter, e.g. garage.
          schema:
            example: garage
            type: string
        - name: has_pool
          required: false
          in: query
          description: Only listings with a pool.
          schema:
            example: true
            type: boolean
        - name: has_garage
          required: false
          in: query
          description: Only listings with a garage.
          schema:
            example: true
            type: boolean
        - name: has_air_conditioning
          required: false
          in: query
          description: Only listings with air conditioning.
          schema:
            example: true
            type: boolean
        - name: is_waterfront
          required: false
          in: query
          description: Only waterfront listings.
          schema:
            example: true
            type: boolean
        - name: is_new_construction
          required: false
          in: query
          description: Only new-construction listings.
          schema:
            example: true
            type: boolean
        - name: has_open_house
          required: false
          in: query
          description: Only listings with a scheduled open house.
          schema:
            example: true
            type: boolean
        - name: price_reduced
          required: false
          in: query
          description: Only listings whose price was recently reduced.
          schema:
            example: true
            type: boolean
        - name: pets_allowed
          required: false
          in: query
          description: 'Rentals only: listings that allow pets.'
          schema:
            example: true
            type: boolean
        - name: include_html
          required: false
          in: query
          description: >-
            Also return the fetched page HTML in `html`. Paid add-on: costs
            extra credits per request.
          schema:
            example: true
            type: boolean
      responses:
        '200':
          description: Grouped listing search result.
      security:
        - x-api-key: []
        - bearer: []
      summary: Search zillow.com listings and return normalized cards.
      tags:
        - zillow-api
  /api/v1/scrape/zillow/property:
    get:
      operationId: ZillowController_runProperty_v1
      parameters:
        - name: url
          required: true
          in: query
          description: Absolute zillow.com property URL.
          schema:
            example: https://www.zillow.com/homedetails/1133-W-Cornelia-Ave-APT-B-Chicago-IL-60657/3712404_zpid/
            type: string
        - name: include_html
          required: false
          in: query
          description: >-
            Also return the fetched page HTML in `html`. Paid add-on: costs
            extra credits per request.
          schema:
            example: true
            type: boolean
      responses:
        '200':
          description: Grouped property detail.
      security:
        - x-api-key: []
        - bearer: []
      summary: Scrape one zillow.com property and return full detail.
      tags:
        - zillow-api
  /api/v1/scrapers/zillow/jobs:
    post:
      operationId: ZillowBulkController_createZillowBulkJob_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZillowBulkDto'
      responses:
        '201':
          description: Zillow bulk job summary with result file ids.
      security:
        - x-api-key: []
        - bearer: []
      summary: Run the no-code Zillow bulk scraper (JSON/CSV/XML output).
      tags:
        - zillow-bulk
  /api/v1/scrapers/zillow/jobs/{jobId}:
    get:
      operationId: ZillowBulkController_getZillowBulkJob_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Zillow bulk job summary with current status and result file ids.
      security:
        - x-api-key: []
        - bearer: []
      summary: >-
        Get a Zillow bulk job status (poll until finished for large async
        sweeps).
      tags:
        - zillow-bulk
  /api/v1/scrape/apartments/listing:
    get:
      operationId: ApartmentsController_runListing_v1
      parameters:
        - name: city
          required: false
          in: query
          description: Target city, e.g. Chicago.
          schema:
            example: Miami
            type: string
        - name: state
          required: false
          in: query
          description: Two-letter US state code, e.g. IL.
          schema:
            example: FL
            type: string
        - name: neighborhood
          required: false
          in: query
          description: Optional neighborhood, e.g. Lincoln Park.
          schema:
            example: Brickell
            type: string
        - name: min_price
          required: false
          in: query
          description: Minimum monthly rent in USD.
          schema:
            example: 1500
            type: number
        - name: max_price
          required: false
          in: query
          description: Maximum monthly rent in USD.
          schema:
            example: 3000
            type: number
        - name: min_bedrooms
          required: false
          in: query
          description: Minimum bedrooms (0 = studio).
          schema:
            example: 1
            type: number
        - name: max_bedrooms
          required: false
          in: query
          description: Maximum bedrooms (0 = studio).
          schema:
            example: 2
            type: number
        - name: min_bathrooms
          required: false
          in: query
          description: Minimum bathrooms.
          schema:
            example: 1
            type: number
        - name: property_type
          required: false
          in: query
          description: Property category to search.
          schema:
            example: apartments
            type: string
            enum:
              - apartments
              - houses
              - condos
              - townhomes
        - name: amenities
          required: false
          in: query
          description: Amenity slugs (e.g. pet-friendly, pool).
          schema:
            type: array
            items:
              type: string
        - name: space
          required: false
          in: query
          description: Whole place vs a single room.
          schema:
            example: entire_place
            type: string
            enum:
              - entire_place
              - room_for_rent
        - name: home_styles
          required: false
          in: query
          description: Home-style refinements.
          schema:
            example:
              - new_construction
            type: array
            items:
              type: string
              enum:
                - duplex
                - new_construction
                - fewer_than_50_units
        - name: housing_type
          required: false
          in: query
          description: Specialty-housing slug (e.g. student, senior).
          schema:
            example: student
            type: string
        - name: short_term
          required: false
          in: query
          description: Short-term / furnished rentals only.
          schema:
            example: true
            type: boolean
        - name: income_restricted
          required: false
          in: query
          description: Income-restricted / affordable housing only.
          schema:
            example: true
            type: boolean
        - name: pet_policy
          required: false
          in: query
          description: Pet policy requirement.
          schema:
            example: dog
            type: string
            enum:
              - dog
              - cat
              - dog_and_cat
              - none
        - name: page
          required: false
          in: query
          description: 1-based result page. Defaults to 1.
          schema:
            example: 2
            type: number
        - name: limit
          required: false
          in: query
          description: Maximum listings to return (1..40). Defaults to 40.
          schema:
            example: 20
            type: number
        - name: include_detail
          required: false
          in: query
          description: Also scrape each listing detail page (billed extra per card).
          schema:
            example: true
            type: boolean
        - name: include_html
          required: false
          in: query
          description: >-
            Also return the fetched page HTML in `html`. Paid add-on: costs
            extra credits per request.
          schema:
            example: true
            type: boolean
      responses:
        '200':
          description: Grouped listing search result.
      security:
        - x-api-key: []
        - bearer: []
      summary: Search apartments.com listings and return normalized cards.
      tags:
        - apartments-api
  /api/v1/scrape/apartments/property:
    get:
      operationId: ApartmentsController_runProperty_v1
      parameters:
        - name: url
          required: true
          in: query
          description: Absolute apartments.com property URL.
          schema:
            example: https://www.apartments.com/the-skylar-miami-fl/qnn7y2y/
            type: string
        - name: include_html
          required: false
          in: query
          description: >-
            Also return the fetched page HTML in `html`. Paid add-on: costs
            extra credits per request.
          schema:
            example: true
            type: boolean
      responses:
        '200':
          description: Grouped property detail.
      security:
        - x-api-key: []
        - bearer: []
      summary: Scrape one apartments.com property and return full detail.
      tags:
        - apartments-api
  /api/v1/scrapers/apartments/jobs:
    post:
      operationId: ApartmentsBulkController_createApartmentsBulkJob_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApartmentsBulkDto'
      responses:
        '201':
          description: Apartments bulk job summary with result file ids.
      security:
        - x-api-key: []
        - bearer: []
      summary: Run the no-code Apartments.com bulk scraper (JSON/CSV/XML output).
      tags:
        - apartments-bulk
  /api/v1/scrapers/apartments/jobs/{jobId}:
    get:
      operationId: ApartmentsBulkController_getApartmentsBulkJob_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Apartments bulk job summary with current status and result file ids.
      security:
        - x-api-key: []
        - bearer: []
      summary: >-
        Get an Apartments.com bulk job status (poll until finished for large
        async sweeps).
      tags:
        - apartments-bulk
  /api/v1/scrape/allegro/listing:
    get:
      operationId: AllegroController_runListing_v1
      parameters:
        - name: phrase
          required: false
          in: query
          description: Search phrase, e.g. makita ddf484. An EAN/GTIN barcode also works.
          schema:
            example: makita ddf484
            type: string
        - name: category_id
          required: false
          in: query
          description: Allegro category id to browse, e.g. 85166.
          schema:
            example: '85166'
            type: string
        - name: url
          required: false
          in: query
          description: >-
            An existing allegro.pl listing URL whose filters are reused
            verbatim.
          schema:
            example: https://allegro.pl/kategoria/sluchawki-bezprzewodowe-85166?marka=Guess
            type: string
        - name: product_id
          required: false
          in: query
          description: >-
            product_id of a product card. Lists every seller offer of that
            product; combines only with limit, page_token and include_detail.
          schema:
            example: 6f05b1ef-a2b3-4075-938a-263472745ccc
            type: string
        - name: page_token
          required: false
          in: query
          description: >-
            Cursor of the next page, copied from next_page_token of the previous
            response. Omit for the first page.
          schema:
            example: MTAwfHwwfDB8MTJ8MHwwfDF8MHwwfDB8MHw3Mg
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum offers to return (1..100).
          schema:
            example: 100
            type: number
        - name: sort
          required: false
          in: query
          description: Result ordering.
          schema:
            example: price_low_high
            type: string
            enum:
              - relevance
              - price_low_high
              - price_high_low
              - price_with_delivery_low_high
              - price_with_delivery_high_low
              - popularity
              - newest
              - ending_soon
        - name: min_price
          required: false
          in: query
          description: Minimum price in PLN.
          schema:
            example: 200
            type: number
        - name: max_price
          required: false
          in: query
          description: Maximum price in PLN.
          schema:
            example: 500
            type: number
        - name: include_detail
          required: false
          in: query
          description: Also fetch each offer card (billed per fetched offer).
          schema:
            example: true
            type: boolean
        - name: conditions
          required: false
          in: query
          description: Item conditions to include.
          schema:
            example:
              - new
              - refurbished
            type: array
            items:
              type: string
              enum:
                - new
                - used
                - refurbished
                - damaged
                - incomplete
        - name: formats
          required: false
          in: query
          description: Sale formats to include.
          schema:
            example:
              - buy_now
            type: array
            items:
              type: string
              enum:
                - buy_now
                - auction
                - advertisement
        - name: free_delivery
          required: false
          in: query
          description: Only offers with free delivery.
          schema:
            example: true
            type: boolean
        - name: vat_invoice
          required: false
          in: query
          description: Only offers whose seller issues a VAT invoice.
          schema:
            example: true
            type: boolean
        - name: shipping_from_poland
          required: false
          in: query
          description: Only offers dispatched from Poland.
          schema:
            example: true
            type: boolean
        - name: smart_delivery
          required: false
          in: query
          description: Only offers in the Allegro Smart! programme.
          schema:
            example: true
            type: boolean
        - name: super_seller
          required: false
          in: query
          description: Only offers from Allegro Super Sellers.
          schema:
            example: true
            type: boolean
        - name: personal_pickup
          required: false
          in: query
          description: Only offers that can be collected in person.
          schema:
            example: true
            type: boolean
        - name: seller_logins
          required: false
          in: query
          description: Restrict the search to these seller logins.
          schema:
            type: array
            items:
              type: string
        - name: excluded_category_ids
          required: false
          in: query
          description: Category ids to keep out of the results.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Grouped listing search result.
      security:
        - x-api-key: []
        - bearer: []
      summary: Search allegro.pl offers and return normalized cards.
      tags:
        - allegro-api
  /api/v1/scrape/allegro/offer:
    get:
      operationId: AllegroController_runOffer_v1
      parameters:
        - name: offer_id
          required: false
          in: query
          description: Allegro offer id, e.g. 17838076590.
          schema:
            example: '17838076590'
            type: string
        - name: url
          required: false
          in: query
          description: >-
            Absolute allegro.pl offer URL, e.g.
            https://allegro.pl/oferta/...-17838076590.
          schema:
            example: https://allegro.pl/oferta/sluchawki-bezprzewodowe-douszne-guess-3666339051433-17065525430
            type: string
        - name: include_seller_company
          required: false
          in: query
          description: Also return the seller company name, tax id and registered address.
          schema:
            example: true
            type: boolean
        - name: include_description
          required: false
          in: query
          description: >-
            Also return the offer description sections as plain text (large
            payload).
          schema:
            example: true
            type: boolean
      responses:
        '200':
          description: Grouped offer detail.
      security:
        - x-api-key: []
        - bearer: []
      summary: Scrape one allegro.pl offer and return the full card.
      tags:
        - allegro-api
  /api/v1/scrapers/allegro/jobs:
    post:
      operationId: AllegroBulkController_createAllegroBulkJob_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllegroBulkDto'
      responses:
        '201':
          description: Allegro bulk job summary with result file ids.
      security:
        - x-api-key: []
        - bearer: []
      summary: Run the no-code Allegro bulk scraper (JSON/CSV/XML output).
      tags:
        - allegro-bulk
  /api/v1/scrapers/allegro/jobs/{jobId}:
    get:
      operationId: AllegroBulkController_getAllegroBulkJob_v1
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Allegro bulk job summary with current status and result file ids.
      security:
        - x-api-key: []
        - bearer: []
      summary: >-
        Get an Allegro bulk job status (poll until finished for large async
        sweeps).
      tags:
        - allegro-bulk
info:
  title: ScrapeIt API Reference
  description: >-
    Public workspace API for ScrapeIt: Web Scraping API, batch scraping, Website
    Crawler, the Allegro, Apartments.com and Zillow product APIs, files,
    webhooks, usage and job monitoring. Authenticate with the `x-api-key:
    sk_...` header or `Authorization: Bearer sk_...`. Successful responses use
    the `{ data, meta }` envelope; errors use `{ error }` with a stable
    machine-readable `code` and a `correlation_id` for support requests.
  version: 0.1.0
  contact: {}
tags: []
servers:
  - url: https://api.scrapeit.io
    description: Production
  - url: /
    description: Current origin (local development)
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    ScrapeCookieDto:
      type: object
      properties:
        name:
          type: string
          description: Cookie name.
          example: currency
        value:
          type: string
          description: Cookie value.
          example: EUR
      required:
        - name
        - value
    CaptureNetworkOptionsDto:
      type: object
      properties:
        enabled:
          type: boolean
          description: Capture the page’s own JSON API/XHR traffic during render.
          example: true
        urlIncludes:
          description: Only capture responses whose URL contains one of these.
          example:
            - /api/
          type: array
          items:
            type: string
        maxResponses:
          type: number
          description: Max number of captured responses (default 20).
          example: 20
        maxBytes:
          type: number
          description: >-
            Max bytes per captured response body (default 524288). maxResponses
            × maxBytes is capped at 16777216 bytes.
          example: 524288
    CreateAsyncWebScrapeDto:
      type: object
      properties:
        url:
          type: string
          description: Absolute target URL.
          example: https://books.toscrape.com/catalogue/page-2.html
        proxyType:
          type: string
          description: >-
            Proxy network class: `datacenter` (default), `residential`, or
            `auto` (the tier this domain already answered on, else datacenter,
            escalating to residential inside the same request; billed by the
            tier that served it).
          enum:
            - datacenter
            - residential
            - auto
          example: residential
        proxyCountry:
          type: string
          description: >-
            Proxy country ISO 3166-1 alpha-2 code (case-insensitive, e.g. "us"
            or "US").
          example: DE
        waitUntil:
          type: string
          description: >-
            Rendered mode: page event to wait for after navigation.
            `domcontentloaded` (default), `load`, or `networkidle` (no network
            activity for 500 ms, capped so a page that never goes quiet does not
            use up the attempt). Ignored by the plain fetch.
          enum:
            - load
            - domcontentloaded
            - networkidle
          example: load
        device:
          type: string
          description: Device class for the non-rendered (fetch) persona.
          enum:
            - mobile
            - desktop
          example: desktop
        extractRules:
          type: object
          description: >-
            CSS extraction rules: field name → selector string (text of the
            first match) or { selector, type?: "item" | "list", output?: "text"
            | "html" | "attribute" | { nested rules }, attribute? }.
          example:
            title: h1
            price:
              selector: .price_color
              type: list
        aiExtractRules:
          type: object
          description: >-
            AI extraction: field name → { type, description?, required? }. An
            LLM fills the schema from the page and returns it as ai_extraction.
            +40 credits; paid plans only (feature ai_extraction).
          example:
            product_name:
              type: string
              description: the product title
            price:
              type: string
              description: the price with currency
        screenshot:
          type: boolean
          description: Capture screenshot artifact.
          example: true
        extractEmails:
          type: boolean
          description: Extract emails from page.
          example: true
        extractLinks:
          type: boolean
          description: Extract links from page.
          example: true
        includeOnlyTags:
          description: HTML tags allow-list.
          example:
            - main
            - article
          type: array
          items:
            type: string
        excludeTags:
          description: HTML tags deny-list.
          example:
            - script
            - style
            - footer
          type: array
          items:
            type: string
        removeBase64Images:
          type: boolean
          description: Remove inline base64 images.
          example: true
        wait:
          type: number
          description: >-
            Additional wait in milliseconds after navigation. When omitted, the
            wait is chosen per target: 3000 ms on a page that carries anti-bot
            protection, and none on a page without it (its content is already
            rendered). Pass an explicit value — including 0 — to override.
          example: 2000
        waitFor:
          type: string
          description: Selector or condition to wait for.
          example: .product_pod
        expectContent:
          type: string
          description: >-
            Literal text the real page always contains. A 2xx without it is
            treated as a stripped page and retried through another proxy; after
            the last attempt it is returned as is.
          maxLength: 256
          example: Add to basket
        minContentBytes:
          type: number
          description: >-
            Smallest body, in bytes, a real page has. A 2xx below it is retried
            through another proxy, like expectContent.
          minimum: 1
          maximum: 10485760
          example: 10240
        captureWhenReady:
          type: string
          description: >-
            CSS selector marking the target content is present. On
            server-rendered pages the runtime captures the moment it appears —
            before the anti-bot challenge JS can replace the content — and
            returns immediately, racing a Cloudflare managed challenge.
          example: .product_pod
        blockResources:
          type: boolean
          description: Block heavy resources.
          example: true
        humanInteraction:
          type: boolean
          description: >-
            Run human-like cursor/scroll/pause interaction before extraction
            (default true). Set false only for targets whose content is in the
            initial document and need no behavioral anti-bot clearance, to
            reduce render latency.
          example: false
        blockAds:
          type: boolean
          description: Enable ad-blocking rules.
          example: true
        blockUrls:
          description: URL patterns to block (`*` matches any substring).
          maxItems: 50
          example:
            - '*google-analytics.com*'
            - '*.woff2'
          type: array
          items:
            type: string
        jsRendering:
          description: >-
            `auto` (the default when omitted): plain HTTP fetch first, a real
            browser only when the request or the fetched page needs one, billed
            by the runtime that produced the result. `true` always renders in a
            browser; `false` starts on the fetch.
          oneOf:
            - type: boolean
            - type: string
              enum:
                - auto
          example: auto
        jsScenario:
          description: >-
            Browser automation steps run before extraction: wait, wait_for,
            click, fill, scroll, press, select and evaluate (an expression run
            in the target page; its JSON result is returned in
            content.scenarioResults). A scenario always renders in a browser.
          example:
            - action: click
              selector: '#load-more'
            - action: wait
              durationMs: 1000
            - action: scroll
              target: bottom
          type: array
          items:
            type: string
        headers:
          type: object
          description: >-
            Target request headers (string values), at most 50 headers and 16384
            bytes in total.
          example:
            Accept-Language: de-DE
        cookies:
          description: >-
            Target cookies, at most 50 cookies and 16384 bytes of names and
            values in total.
          example:
            - name: currency
              value: EUR
          type: array
          items:
            $ref: '#/components/schemas/ScrapeCookieDto'
        outputFormat:
          type: array
          description: Requested output formats.
          example:
            - html
            - markdown
          items:
            type: string
            enum:
              - html
              - text
              - markdown
              - json
        timeoutMs:
          type: number
          description: End-to-end timeout in milliseconds.
          example: 60000
        captureNetwork:
          description: Capture the page’s own JSON API traffic during render.
          example:
            enabled: true
            urlIncludes:
              - /api/
          allOf:
            - $ref: '#/components/schemas/CaptureNetworkOptionsDto'
        webhookUrl:
          type: string
          description: >-
            Public http(s) URL receiving the signed result when the request ends
            (signed with the request webhook signing secret).
          example: https://your-app.example.com/scrapeit/webhook
        webhookEvents:
          type: array
          description: Events posted to webhookUrl; both when omitted.
          example:
            - scrape.request.finished
          items:
            type: string
            enum:
              - scrape.request.finished
              - scrape.request.failed
      required:
        - url
    BatchJobCountersDto:
      type: object
      properties:
        total:
          type: number
          description: Total URL items accepted into the job.
        processed:
          type: number
          description: Items that reached a terminal status.
        billable_success:
          type: number
          description: Items with a billable target outcome.
        non_billable_failed:
          type: number
          description: Items that failed before a billable target outcome.
        target_errors:
          type: number
          description: Billable target HTTP/block/empty-content outcomes.
        proxy_errors:
          type: number
          description: Non-billable proxy failures.
        network_errors:
          type: number
          description: Non-billable network failures.
        browser_errors:
          type: number
          description: Non-billable browser runtime failures.
        internal_errors:
          type: number
          description: Non-billable platform/internal/storage failures.
        skipped:
          type: number
          description: Items skipped because the job was stopped before processing.
        credits_spent:
          type: number
          description: Total credits charged across billable items.
      required:
        - total
        - processed
        - billable_success
        - non_billable_failed
        - target_errors
        - proxy_errors
        - network_errors
        - browser_errors
        - internal_errors
        - skipped
        - credits_spent
    BatchJobItemSummaryDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        batch_job_id:
          type: string
          format: uuid
          description: Parent job id.
        item_index:
          type: number
          description: Zero-based input order.
        url:
          type: string
          description: Target URL.
        status:
          type: string
          enum:
            - queued
            - running
            - stopping
            - stopped
            - finished
            - failed
            - skipped
        scrape_request_id:
          type: string
          format: uuid
          nullable: true
        result_metadata:
          type: object
          additionalProperties: true
          description: >-
            Sanitized result metadata; never contains secrets or internal
            storage paths.
        error_code:
          type: string
          nullable: true
          description: Stable error code of a failed item.
        credits_spent:
          type: number
          description: Credits charged for this item.
        execution_status:
          type: string
          enum:
            - billable_success
            - non_billable_failure
            - rejected
          nullable: true
        billing_status:
          type: string
          enum:
            - charged
            - not_charged
            - refunded
          nullable: true
        billable_result_category:
          type: string
          enum:
            - target_response_received
            - target_http_error
            - target_empty_content
            - target_block_page_returned
            - extraction_empty
          nullable: true
        non_billable_failure_category:
          type: string
          enum:
            - validation_error
            - invalid_api_key
            - insufficient_credits
            - concurrency_limit_exceeded
            - ssrf_blocked
            - proxy_error
            - network_error
            - browser_runtime_error
            - worker_internal_error
            - storage_error
            - platform_timeout
            - anti_bot_challenge
            - response_too_large
          nullable: true
        target_http_status:
          type: number
          nullable: true
          description: Target HTTP status when Scrapeit reached the target.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - batch_job_id
        - item_index
        - url
        - status
        - scrape_request_id
        - result_metadata
        - error_code
        - credits_spent
        - execution_status
        - billing_status
        - billable_result_category
        - non_billable_failure_category
        - target_http_status
        - created_at
        - updated_at
    AsyncWebScrapeJobDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Job id to poll with GET /api/v1/scrape/web/async/{jobId}.
        organization_id:
          type: string
          format: uuid
        api_key_id:
          type: string
          format: uuid
          nullable: true
        product_code:
          type: string
          enum:
            - web_scraping_api
        status:
          type: string
          enum:
            - queued
            - running
            - stopping
            - stopped
            - finished
            - failed
            - skipped
        counters:
          $ref: '#/components/schemas/BatchJobCountersDto'
        shared_config:
          type: object
          additionalProperties: true
          description: Sanitized Web Scraping API options the request runs with.
        correlation_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          nullable: true
        result:
          nullable: true
          description: >-
            The request item; carries the outcome, credits and result file ids
            once terminal.
          type: object
          allOf:
            - $ref: '#/components/schemas/BatchJobItemSummaryDto'
      required:
        - id
        - organization_id
        - api_key_id
        - product_code
        - status
        - counters
        - shared_config
        - correlation_id
        - created_at
        - updated_at
        - finished_at
        - result
    AsyncWebScrapeJobResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AsyncWebScrapeJobDto'
      required:
        - data
    CreateBatchWebScrapeDto:
      type: object
      properties:
        proxyType:
          type: string
          description: >-
            Proxy network class: `datacenter` (default), `residential`, or
            `auto` (the tier this domain already answered on, else datacenter,
            escalating to residential inside the same request; billed by the
            tier that served it).
          enum:
            - datacenter
            - residential
            - auto
          example: residential
        proxyCountry:
          type: string
          description: >-
            Proxy country ISO 3166-1 alpha-2 code (case-insensitive, e.g. "us"
            or "US").
          example: DE
        waitUntil:
          type: string
          description: >-
            Rendered mode: page event to wait for after navigation.
            `domcontentloaded` (default), `load`, or `networkidle` (no network
            activity for 500 ms, capped so a page that never goes quiet does not
            use up the attempt). Ignored by the plain fetch.
          enum:
            - load
            - domcontentloaded
            - networkidle
          example: load
        device:
          type: string
          description: Device class for the non-rendered (fetch) persona.
          enum:
            - mobile
            - desktop
          example: desktop
        extractRules:
          type: object
          description: >-
            CSS extraction rules: field name → selector string (text of the
            first match) or { selector, type?: "item" | "list", output?: "text"
            | "html" | "attribute" | { nested rules }, attribute? }.
          example:
            title: h1
            price:
              selector: .price_color
              type: list
        aiExtractRules:
          type: object
          description: >-
            AI extraction: field name → { type, description?, required? }. An
            LLM fills the schema from the page and returns it as ai_extraction.
            +40 credits; paid plans only (feature ai_extraction).
          example:
            product_name:
              type: string
              description: the product title
            price:
              type: string
              description: the price with currency
        screenshot:
          type: boolean
          description: Capture screenshot artifact.
          example: true
        extractEmails:
          type: boolean
          description: Extract emails from page.
          example: true
        extractLinks:
          type: boolean
          description: Extract links from page.
          example: true
        includeOnlyTags:
          description: HTML tags allow-list.
          example:
            - main
            - article
          type: array
          items:
            type: string
        excludeTags:
          description: HTML tags deny-list.
          example:
            - script
            - style
            - footer
          type: array
          items:
            type: string
        removeBase64Images:
          type: boolean
          description: Remove inline base64 images.
          example: true
        wait:
          type: number
          description: >-
            Additional wait in milliseconds after navigation. When omitted, the
            wait is chosen per target: 3000 ms on a page that carries anti-bot
            protection, and none on a page without it (its content is already
            rendered). Pass an explicit value — including 0 — to override.
          example: 2000
        waitFor:
          type: string
          description: Selector or condition to wait for.
          example: .product_pod
        expectContent:
          type: string
          description: >-
            Literal text the real page always contains. A 2xx without it is
            treated as a stripped page and retried through another proxy; after
            the last attempt it is returned as is.
          maxLength: 256
          example: Add to basket
        minContentBytes:
          type: number
          description: >-
            Smallest body, in bytes, a real page has. A 2xx below it is retried
            through another proxy, like expectContent.
          minimum: 1
          maximum: 10485760
          example: 10240
        captureWhenReady:
          type: string
          description: >-
            CSS selector marking the target content is present. On
            server-rendered pages the runtime captures the moment it appears —
            before the anti-bot challenge JS can replace the content — and
            returns immediately, racing a Cloudflare managed challenge.
          example: .product_pod
        blockResources:
          type: boolean
          description: Block heavy resources.
          example: true
        humanInteraction:
          type: boolean
          description: >-
            Run human-like cursor/scroll/pause interaction before extraction
            (default true). Set false only for targets whose content is in the
            initial document and need no behavioral anti-bot clearance, to
            reduce render latency.
          example: false
        blockAds:
          type: boolean
          description: Enable ad-blocking rules.
          example: true
        blockUrls:
          description: URL patterns to block (`*` matches any substring).
          maxItems: 50
          example:
            - '*google-analytics.com*'
            - '*.woff2'
          type: array
          items:
            type: string
        jsRendering:
          description: >-
            `auto` (the default when omitted): plain HTTP fetch first, a real
            browser only when the request or the fetched page needs one, billed
            by the runtime that produced the result. `true` always renders in a
            browser; `false` starts on the fetch.
          oneOf:
            - type: boolean
            - type: string
              enum:
                - auto
          example: auto
        jsScenario:
          description: >-
            Browser automation steps run before extraction: wait, wait_for,
            click, fill, scroll, press, select and evaluate (an expression run
            in the target page; its JSON result is returned in
            content.scenarioResults). A scenario always renders in a browser.
          example:
            - action: click
              selector: '#load-more'
            - action: wait
              durationMs: 1000
            - action: scroll
              target: bottom
          type: array
          items:
            type: string
        headers:
          type: object
          description: >-
            Target request headers (string values), at most 50 headers and 16384
            bytes in total.
          example:
            Accept-Language: de-DE
        cookies:
          description: >-
            Target cookies, at most 50 cookies and 16384 bytes of names and
            values in total.
          example:
            - name: currency
              value: EUR
          type: array
          items:
            $ref: '#/components/schemas/ScrapeCookieDto'
        outputFormat:
          type: array
          description: Requested output formats.
          example:
            - html
            - markdown
          items:
            type: string
            enum:
              - html
              - text
              - markdown
              - json
        timeoutMs:
          type: number
          description: End-to-end timeout in milliseconds.
          example: 60000
        captureNetwork:
          description: Capture the page’s own JSON API traffic during render.
          example:
            enabled: true
            urlIncludes:
              - /api/
          allOf:
            - $ref: '#/components/schemas/CaptureNetworkOptionsDto'
        urls:
          description: >-
            Target URLs. The service enforces hard limit 50000 and plan
            max_batch_urls.
          example:
            - https://example.com
            - https://example.org
          type: array
          items:
            type: array
      required:
        - urls
    CreateWebhookEndpointDto:
      type: object
      properties:
        url:
          type: string
          description: Public HTTPS/HTTP endpoint URL receiving webhook events.
        subscribedEvents:
          type: array
          description: Subscribed event types.
          items:
            type: string
            enum:
              - scrape.request.finished
              - scrape.request.failed
              - batch.job.started
              - batch.job.finished
              - scraper.job.started
              - scraper.job.finished
              - scraper.job.failed
      required:
        - url
        - subscribedEvents
    RequestWebhookSigningSecretDto:
      type: object
      properties:
        signing_secret:
          type: string
          description: >-
            Raw whsec_… secret verifying webhookUrl deliveries. Returned only
            here; ScrapeIt keeps its hash and ciphertext.
        rotated_at:
          type: string
          format: date-time
          description: When this secret was created or rotated.
      required:
        - signing_secret
        - rotated_at
    RequestWebhookSigningSecretResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RequestWebhookSigningSecretDto'
      required:
        - data
    UpdateWebhookEndpointDto:
      type: object
      properties:
        url:
          type: string
          description: Public HTTPS/HTTP endpoint URL receiving webhook events.
        subscribedEvents:
          type: array
          description: Subscribed event types.
          items:
            type: string
            enum:
              - scrape.request.finished
              - scrape.request.failed
              - batch.job.started
              - batch.job.finished
              - scraper.job.started
              - scraper.job.finished
              - scraper.job.failed
        status:
          type: string
          description: Webhook endpoint status.
          enum:
            - active
            - disabled
    CreateCrawlerJobDto:
      type: object
      properties:
        urls:
          description: Seed URLs that initialize the crawler frontier.
          example:
            - https://example.com
          type: array
          items:
            type: array
        maxDepth:
          type: number
          description: Maximum link depth from seed URLs.
          minimum: 0
          example: 2
        includePaths:
          description: >-
            URL path patterns allowed for discovered URLs (`*` matches any
            substring).
          maxItems: 100
          example:
            - /catalogue/*
          type: array
          items:
            type: string
        excludePaths:
          description: >-
            URL path patterns excluded from crawling (`*` matches any
            substring).
          maxItems: 100
          example:
            - /catalogue/category/*
          type: array
          items:
            type: string
        limit:
          type: number
          description: Maximum number of pages to process.
          maximum: 10000
          example: 100
        outputFormat:
          type: array
          description: Requested output formats.
          example:
            - html
            - markdown
          items:
            type: string
            enum:
              - html
              - text
              - markdown
              - json
        jsRendering:
          type: boolean
          description: >-
            Render every page in the remote browser (pricier). Off when omitted:
            pages load over the plain HTTP fetch, and a page that comes back
            empty still moves to the browser, billed at the render price.
            Required by waitFor.
          example: false
        waitFor:
          type: string
          description: Selector or condition to wait for on rendered pages.
          example: .product_pod
        extractRules:
          type: object
          description: >-
            CSS extraction rules applied to every page, as in the Web Scraping
            API: selector strings or { selector, type?, output?, attribute? }
            rule objects.
          example:
            title: h1
            price:
              selector: .price_color
              type: list
        aiExtractRules:
          type: object
          description: >-
            AI extraction schema. The Website Crawler does not run AI extraction
            yet: a job with it is rejected with AI_EXTRACTION_DISABLED.
          example:
            product_name:
              type: string
              description: the product title
            price:
              type: string
              description: the price with currency
        proxyType:
          type: string
          description: Proxy network class.
          enum:
            - datacenter
            - residential
          example: residential
        proxyCountry:
          type: string
          description: Proxy country ISO code.
          example: DE
      required:
        - urls
    ScrapeRequestCacheOptionsDto:
      type: object
      properties:
        enabled:
          type: boolean
          description: Enable cache lookup/write for this request.
          example: true
        strategy:
          type: string
          description: Cache strategy.
          enum:
            - prefer_cache
            - fresh
            - stale_while_revalidate
          example: prefer_cache
        maxAgeSeconds:
          type: number
          description: Maximum accepted cache age in seconds.
          example: 3600
        shareScope:
          type: string
          description: Maximum cache share scope.
          enum:
            - private
            - organization
            - global
          example: organization
    ScrapeWebDto:
      type: object
      properties:
        url:
          type: string
          description: Absolute target URL.
          example: https://books.toscrape.com/catalogue/page-2.html
        proxyType:
          type: string
          description: >-
            Proxy network class: `datacenter` (default), `residential`, or
            `auto` (the tier this domain already answered on, else datacenter,
            escalating to residential inside the same request; billed by the
            tier that served it).
          enum:
            - datacenter
            - residential
            - auto
          example: residential
        proxyCountry:
          type: string
          description: >-
            Proxy country ISO 3166-1 alpha-2 code (case-insensitive, e.g. "us"
            or "US").
          example: DE
        sessionId:
          type: string
          description: >-
            Sticky session id (letters, digits, `_`, `-`). Requests of your
            organization with the same id leave through the same proxy exit and
            keep the session cookies, until the session expires or its
            proxyType/country changes. Synchronous requests only.
          maxLength: 64
          example: checkout-flow-42
        waitUntil:
          type: string
          description: >-
            Rendered mode: page event to wait for after navigation.
            `domcontentloaded` (default), `load`, or `networkidle` (no network
            activity for 500 ms, capped so a page that never goes quiet does not
            use up the attempt). Ignored by the plain fetch.
          enum:
            - load
            - domcontentloaded
            - networkidle
          example: load
        device:
          type: string
          description: Device class for the non-rendered (fetch) persona.
          enum:
            - mobile
            - desktop
          example: desktop
        extractRules:
          type: object
          description: >-
            CSS extraction rules: field name → selector string (text of the
            first match) or { selector, type?: "item" | "list", output?: "text"
            | "html" | "attribute" | { nested rules }, attribute? }.
          example:
            title: h1
            price:
              selector: .price_color
              type: list
        aiExtractRules:
          type: object
          description: >-
            AI extraction: field name → { type, description?, required? }. An
            LLM fills the schema from the page and returns it as ai_extraction.
            +40 credits; paid plans only (feature ai_extraction).
          example:
            product_name:
              type: string
              description: the product title
            price:
              type: string
              description: the price with currency
        screenshot:
          type: boolean
          description: Capture screenshot artifact.
          example: true
        extractEmails:
          type: boolean
          description: Extract emails from page.
          example: true
        extractLinks:
          type: boolean
          description: Extract links from page.
          example: true
        includeOnlyTags:
          description: HTML tags allow-list.
          example:
            - main
            - article
          type: array
          items:
            type: string
        excludeTags:
          description: HTML tags deny-list.
          example:
            - script
            - style
            - footer
          type: array
          items:
            type: string
        removeBase64Images:
          type: boolean
          description: Remove inline base64 images.
          example: true
        wait:
          type: number
          description: >-
            Additional wait in milliseconds after navigation. When omitted, the
            wait is chosen per target: 3000 ms on a page that carries anti-bot
            protection, and none on a page without it (its content is already
            rendered). Pass an explicit value — including 0 — to override.
          example: 2000
        waitFor:
          type: string
          description: Selector or condition to wait for.
          example: .product_pod
        expectContent:
          type: string
          description: >-
            Literal text the real page always contains. A 2xx without it is
            treated as a stripped page and retried through another proxy; after
            the last attempt it is returned as is.
          maxLength: 256
          example: Add to basket
        minContentBytes:
          type: number
          description: >-
            Smallest body, in bytes, a real page has. A 2xx below it is retried
            through another proxy, like expectContent.
          minimum: 1
          maximum: 10485760
          example: 10240
        captureWhenReady:
          type: string
          description: >-
            CSS selector marking the target content is present. On
            server-rendered pages the runtime captures the moment it appears —
            before the anti-bot challenge JS can replace the content — and
            returns immediately, racing a Cloudflare managed challenge.
          example: .product_pod
        blockResources:
          type: boolean
          description: Block heavy resources.
          example: true
        humanInteraction:
          type: boolean
          description: >-
            Run human-like cursor/scroll/pause interaction before extraction
            (default true). Set false only for targets whose content is in the
            initial document and need no behavioral anti-bot clearance, to
            reduce render latency.
          example: false
        blockAds:
          type: boolean
          description: Enable ad-blocking rules.
          example: true
        blockUrls:
          description: URL patterns to block (`*` matches any substring).
          maxItems: 50
          example:
            - '*google-analytics.com*'
            - '*.woff2'
          type: array
          items:
            type: string
        jsRendering:
          description: >-
            `auto` (the default when omitted): plain HTTP fetch first, a real
            browser only when the request or the fetched page needs one, billed
            by the runtime that produced the result. `true` always renders in a
            browser; `false` starts on the fetch.
          oneOf:
            - type: boolean
            - type: string
              enum:
                - auto
          example: auto
        jsScenario:
          description: >-
            Browser automation steps run before extraction: wait, wait_for,
            click, fill, scroll, press, select and evaluate (an expression run
            in the target page; its JSON result is returned in
            content.scenarioResults). A scenario always renders in a browser.
          example:
            - action: click
              selector: '#load-more'
            - action: wait
              durationMs: 1000
            - action: scroll
              target: bottom
          type: array
          items:
            type: string
        headers:
          type: object
          description: >-
            Target request headers (string values), at most 50 headers and 16384
            bytes in total.
          example:
            Accept-Language: de-DE
        cookies:
          description: >-
            Target cookies, at most 50 cookies and 16384 bytes of names and
            values in total.
          example:
            - name: currency
              value: EUR
          type: array
          items:
            $ref: '#/components/schemas/ScrapeCookieDto'
        outputFormat:
          type: array
          description: Requested output formats.
          example:
            - html
            - markdown
          items:
            type: string
            enum:
              - html
              - text
              - markdown
              - json
        timeoutMs:
          type: number
          description: End-to-end timeout in milliseconds.
          example: 60000
        cache:
          description: Cache policy.
          example:
            enabled: true
            maxAgeSeconds: 3600
          allOf:
            - $ref: '#/components/schemas/ScrapeRequestCacheOptionsDto'
        captureNetwork:
          description: Capture the page’s own JSON API traffic during render.
          example:
            enabled: true
            urlIncludes:
              - /api/
          allOf:
            - $ref: '#/components/schemas/CaptureNetworkOptionsDto'
      required:
        - url
    ZillowBulkDto:
      type: object
      properties:
        city:
          type: string
          description: Target city, e.g. Chicago.
          example: Chicago
        state:
          type: string
          description: Two-letter US state code, e.g. IL.
          example: IL
        neighborhood:
          type: string
          description: Optional neighborhood, e.g. Lincoln Park.
          example: Lincoln Park
        listing_status:
          type: string
          description: Market to search. Defaults to for_sale.
          enum:
            - for_sale
            - for_rent
            - sold
          example: for_sale
        home_types:
          type: array
          description: Home categories to include.
          example:
            - houses
            - condos
          items:
            type: string
            enum:
              - houses
              - apartments
              - condos
              - townhomes
              - manufactured
              - lots_land
              - multi_family
        min_price:
          type: number
          description: Minimum price in USD (monthly rent for rentals).
          example: 250000
        max_price:
          type: number
          description: Maximum price in USD (monthly rent for rentals).
          example: 500000
        min_bedrooms:
          type: number
          description: Minimum bedrooms (0 = studio).
          example: 2
        max_bedrooms:
          type: number
          description: Maximum bedrooms.
          example: 4
        min_bathrooms:
          type: number
          description: Minimum bathrooms.
          example: 2
        page:
          type: number
          description: 1-based result page. Defaults to 1.
          example: 2
        limit:
          type: number
          description: Maximum listings to return (1..41).
          example: 41
        include_detail:
          type: boolean
          description: Also scrape each listing detail page (billed extra per card).
          example: true
        min_square_feet:
          type: number
          description: Minimum living area in square feet.
          example: 1200
        max_square_feet:
          type: number
          description: Maximum living area in square feet.
          example: 2500
        min_lot_size:
          type: number
          description: Minimum lot size in square feet.
          example: 3000
        max_lot_size:
          type: number
          description: Maximum lot size in square feet.
          example: 10000
        min_year_built:
          type: number
          description: Earliest construction year.
          example: 1990
        max_year_built:
          type: number
          description: Latest construction year.
          example: 2024
        max_hoa_fee:
          type: number
          description: Maximum monthly HOA fee in USD.
          example: 300
        max_days_on_zillow:
          type: number
          description: Only listings published within this many days.
          example: 30
        sort:
          type: string
          description: Result ordering.
          enum:
            - relevance
            - newest
            - price_high_low
            - price_low_high
            - bedrooms
            - bathrooms
            - square_feet
            - lot_size
          example: newest
        keywords:
          type: string
          description: Free-text keyword filter, e.g. garage.
          example: garage
        has_pool:
          type: boolean
          description: Only listings with a pool.
          example: true
        has_garage:
          type: boolean
          description: Only listings with a garage.
          example: true
        has_air_conditioning:
          type: boolean
          description: Only listings with air conditioning.
          example: true
        is_waterfront:
          type: boolean
          description: Only waterfront listings.
          example: true
        is_new_construction:
          type: boolean
          description: Only new-construction listings.
          example: true
        has_open_house:
          type: boolean
          description: Only listings with a scheduled open house.
          example: true
        price_reduced:
          type: boolean
          description: Only listings whose price was recently reduced.
          example: true
        pets_allowed:
          type: boolean
          description: 'Rentals only: listings that allow pets.'
          example: true
        output_format:
          type: array
          description: Result files to generate.
          default:
            - json
          example:
            - json
            - csv
          items:
            type: string
            enum:
              - json
              - csv
              - xml
        max_pages:
          type: number
          description: Maximum listing pages to sweep (1..20). Defaults to 5.
          example: 10
    ApartmentsBulkDto:
      type: object
      properties:
        city:
          type: string
          description: Target city, e.g. Chicago.
          example: Miami
        state:
          type: string
          description: Two-letter US state code, e.g. IL.
          example: FL
        neighborhood:
          type: string
          description: Optional neighborhood, e.g. Lincoln Park.
          example: Brickell
        min_price:
          type: number
          description: Minimum monthly rent in USD.
          example: 1500
        max_price:
          type: number
          description: Maximum monthly rent in USD.
          example: 3000
        min_bedrooms:
          type: number
          description: Minimum bedrooms (0 = studio).
          example: 1
        max_bedrooms:
          type: number
          description: Maximum bedrooms (0 = studio).
          example: 2
        min_bathrooms:
          type: number
          description: Minimum bathrooms.
          example: 1
        property_type:
          type: string
          description: Property category to search.
          enum:
            - apartments
            - houses
            - condos
            - townhomes
          example: apartments
        amenities:
          description: Amenity slugs (e.g. pet-friendly, pool).
          example:
            - pool
            - in-unit-washer-dryer
          type: array
          items:
            type: string
        space:
          type: string
          description: Whole place vs a single room.
          enum:
            - entire_place
            - room_for_rent
          example: entire_place
        home_styles:
          type: array
          description: Home-style refinements.
          example:
            - new_construction
          items:
            type: string
            enum:
              - duplex
              - new_construction
              - fewer_than_50_units
        housing_type:
          type: string
          description: Specialty-housing slug (e.g. student, senior).
          example: student
        short_term:
          type: boolean
          description: Short-term / furnished rentals only.
          example: true
        income_restricted:
          type: boolean
          description: Income-restricted / affordable housing only.
          example: true
        pet_policy:
          type: string
          description: Pet policy requirement.
          enum:
            - dog
            - cat
            - dog_and_cat
            - none
          example: dog
        page:
          type: number
          description: 1-based result page. Defaults to 1.
          example: 2
        limit:
          type: number
          description: Maximum listings to return (1..40). Defaults to 40.
          example: 20
        include_detail:
          type: boolean
          description: Also scrape each listing detail page (billed extra per card).
          example: true
        output_format:
          type: array
          description: Result files to generate.
          default:
            - json
          example:
            - json
            - csv
          items:
            type: string
            enum:
              - json
              - csv
              - xml
        max_pages:
          type: number
          description: Maximum listing pages to sweep (1..20). Defaults to 5.
          example: 10
    AllegroBulkDto:
      type: object
      properties:
        phrase:
          type: string
          description: Search phrase, e.g. makita ddf484. An EAN/GTIN barcode also works.
          example: makita ddf484
        category_id:
          type: string
          description: Allegro category id to browse, e.g. 85166.
          example: '85166'
        url:
          type: string
          description: >-
            An existing allegro.pl listing URL whose filters are reused
            verbatim.
          example: https://allegro.pl/kategoria/sluchawki-bezprzewodowe-85166?marka=Guess
        product_id:
          type: string
          description: >-
            product_id of a product card. Lists every seller offer of that
            product; combines only with limit, page_token and include_detail.
          example: 6f05b1ef-a2b3-4075-938a-263472745ccc
        page_token:
          type: string
          description: >-
            Cursor of the next page, copied from next_page_token of the previous
            response. Omit for the first page.
          example: MTAwfHwwfDB8MTJ8MHwwfDF8MHwwfDB8MHw3Mg
        limit:
          type: number
          description: Maximum offers to return (1..100).
          example: 100
        sort:
          type: string
          description: Result ordering.
          enum:
            - relevance
            - price_low_high
            - price_high_low
            - price_with_delivery_low_high
            - price_with_delivery_high_low
            - popularity
            - newest
            - ending_soon
          example: price_low_high
        min_price:
          type: number
          description: Minimum price in PLN.
          example: 200
        max_price:
          type: number
          description: Maximum price in PLN.
          example: 500
        include_detail:
          type: boolean
          description: Also fetch each offer card (billed per fetched offer).
          example: true
        conditions:
          type: array
          description: Item conditions to include.
          example:
            - new
            - refurbished
          items:
            type: string
            enum:
              - new
              - used
              - refurbished
              - damaged
              - incomplete
        formats:
          type: array
          description: Sale formats to include.
          example:
            - buy_now
          items:
            type: string
            enum:
              - buy_now
              - auction
              - advertisement
        free_delivery:
          type: boolean
          description: Only offers with free delivery.
          example: true
        vat_invoice:
          type: boolean
          description: Only offers whose seller issues a VAT invoice.
          example: true
        shipping_from_poland:
          type: boolean
          description: Only offers dispatched from Poland.
          example: true
        smart_delivery:
          type: boolean
          description: Only offers in the Allegro Smart! programme.
          example: true
        super_seller:
          type: boolean
          description: Only offers from Allegro Super Sellers.
          example: true
        personal_pickup:
          type: boolean
          description: Only offers that can be collected in person.
          example: true
        seller_logins:
          description: Restrict the search to these seller logins.
          example:
            - 2karma
            - bombazlavapl
          type: array
          items:
            type: array
        excluded_category_ids:
          description: Category ids to keep out of the results.
          example:
            - '66887'
          type: array
          items:
            type: array
        output_format:
          type: array
          description: Result files to generate.
          default:
            - json
          example:
            - json
            - csv
          items:
            type: string
            enum:
              - json
              - csv
              - xml
        max_pages:
          type: number
          description: Maximum listing pages to sweep (1..20). Defaults to 5.
          example: 10