openapi: 3.2.0
info:
  title: AdsCrawl Browser tasks API
  version: 1.0.0
  description: Real-browser web scraping and browser automation.
  contact:
    name: AdsCrawl Support
    url: https://www.adscrawl.net/docs/
    email: support@adscrawl.net
  x-providerName: adscrawl.net
  x-categories:
  - developer_tools
  x-origin:
  - url: https://www.adscrawl.net/openapi.yaml
    format: openapi
    version: '3.0'
servers:
- url: https://api.adscrawl.net
  description: Production
security:
- ApiKey: []
tags:
- name: Browser tasks
  description: Synchronous rendered content, screenshots, and structured extraction.
paths:
  /html:
    post:
      operationId: renderHtml
      tags:
      - Browser tasks
      summary: Render HTML, Markdown, or article JSON
      description: Render a public HTTP(S) URL using a real browser. contentMode selects the response media type. Validation precedes billing and queueing. A missing readable article can return READABILITY_CONTENT_NOT_FOUND.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HtmlRequest'
            example:
              url: https://example.com/article
              contentMode: markdown
              waitUntil: domcontentloaded
      responses:
        '200':
          description: Rendered page or extracted article, not a task envelope.
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
            application/json:
              schema:
                type: object
                description: Structured article output; fields depend on the extracted page.
                additionalProperties: true
        default:
          $ref: '#/components/responses/TaskError'
  /screenshot:
    post:
      operationId: captureScreenshot
      tags:
      - Browser tasks
      summary: Capture a page or element as PNG
      description: Returns PNG bytes synchronously. selector capture takes precedence over fullPage. An unmatched selector returns 422.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenshotRequest'
            example:
              url: https://example.com
              fullPage: true
      responses:
        '200':
          description: PNG screenshot bytes.
          content:
            image/png:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/TaskError'
  /spa-extract:
    post:
      operationId: extractSpa
      tags:
      - Browser tasks
      summary: Inspect or extract structured data from a page
      description: Use DOM/network fields or a published site template. Custom extraction requires a public page URL. For google-trends-explore, keyword is recommended; when keyword is omitted, legacy url input is supported. Explicit null or an empty keyword is invalid. fields takes precedence over the legacy schema selector mapping. The schema field is not response JSON Schema validation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpaRequest'
            example:
              url: https://example.com
              mode: extract
              fields:
                title:
                  source: dom
                  selector: h1
                  value: text
      responses:
        '200':
          description: Page inspection or extracted data. The shape depends on mode, requested fields, and template. Google Trends also returns source, cached, stale, collectedAt, and attempts metadata.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/TaskError'
  /spa-extract/templates:
    get:
      operationId: listExtractionTemplates
      tags:
      - Browser tasks
      summary: List available extraction templates
      responses:
        '200':
          description: Templates with their inputs, output fields, and catalog metadata.
          content:
            application/json:
              schema:
                type: object
                required:
                - templates
                properties:
                  templates:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtractionTemplate'
        default:
          $ref: '#/components/responses/ApiError'
components:
  schemas:
    SpaRequest:
      allOf:
      - $ref: '#/components/schemas/TaskOptions'
      - type: object
        properties:
          keyword:
            type: string
            description: For google-trends-explore, 1-5 unique comma-separated keywords, each at most 100 Unicode characters.
          mode:
            type: string
            enum:
            - inspect
            - extract
          template:
            type: string
          parameters:
            type: object
            additionalProperties: true
          waitFor:
            $ref: '#/components/schemas/WaitFor'
          actions:
            type: array
            items:
              $ref: '#/components/schemas/Action'
          fields:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/ExtractionField'
          schema:
            type: object
            description: Legacy field mapping (string selectors or field objects), optionally wrapped in properties. Used only if fields is absent.
            additionalProperties: true
    ExtractionTemplate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        urlPattern:
          type: string
        exampleUrl:
          type: string
        version:
          type: integer
        updatedAt:
          type: string
          format: date-time
        outputFields:
          type: array
          items:
            type: string
        waitUntil:
          type: string
        input:
          type: object
          additionalProperties: true
        catalog:
          type: object
          additionalProperties: true
      additionalProperties: true
    HtmlRequest:
      allOf:
      - $ref: '#/components/schemas/TaskOptions'
      - type: object
        required:
        - url
        properties:
          contentMode:
            type: string
            enum:
            - html
            - markdown
            - json
            default: html
          selector:
            type: string
            description: Optional CSS selector for targeted content.
    Viewport:
      type: object
      required:
      - width
      - height
      properties:
        width:
          type: number
        height:
          type: number
    WaitFor:
      type: object
      properties:
        selector:
          type: string
        text:
          type: string
        timeoutMs:
          type: number
          default: 15000
    TaskOptions:
      allOf:
      - $ref: '#/components/schemas/BrowserSettings'
      - type: object
        properties:
          url:
            type: string
            description: Public HTTP(S) URL on port 80 or 443; template-specific rules may apply.
          waitUntil:
            type: string
            enum:
            - load
            - domcontentloaded
            - networkidle
            description: Navigation readiness. networkidle may time out on long-polling pages.
          timeoutMs:
            type: number
            description: Positive timeout up to 3600000 ms; invalid values use the server default.
    ScreenshotRequest:
      allOf:
      - $ref: '#/components/schemas/TaskOptions'
      - type: object
        required:
        - url
        properties:
          fullPage:
            type: boolean
            default: true
          selector:
            type: string
            description: Capture the first matching element; takes precedence over fullPage.
    Fingerprint:
      type: object
      description: Browser fingerprint modes. Defaults and supported combinations depend on the workflow; the server maintains a coherent identity and seed.
      properties:
        webRtc:
          type: string
          enum:
          - forward
          - real
          - disabled
        webGl:
          type: string
          enum:
          - random
          - real
        webGpu:
          type: string
          enum:
          - random
          - real
          - disabled
        webGlImage:
          type: string
          enum:
          - random
          - real
        canvas:
          type: string
          enum:
          - random
          - real
        audioContext:
          type: string
          enum:
          - random
          - real
        clientRects:
          type: string
          enum:
          - random
          - real
        speechVoices:
          type: string
          enum:
          - random
          - real
        fonts:
          type: string
          enum:
          - random
          - real
        hardware:
          type: string
          enum:
          - random
          - real
        doNotTrack:
          type: string
          enum:
          - random
          - enabled
          - disabled
        hardwareConcurrency:
          type: integer
          minimum: 1
          maximum: 64
        deviceMemory:
          type: integer
          minimum: 1
          maximum: 64
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        traceId:
          type: string
        retryable:
          type: boolean
      additionalProperties: true
    Cookie:
      type: object
      required:
      - name
      - domain
      description: Preset browser cookie. Use native JSON booleans. Legacy browser-task inputs also accept compatibility forms for some flags. Launch defaults an omitted value to an empty string. Expiry aliases are Unix seconds.
      properties:
        name:
          type: string
          minLength: 1
        value:
          type: string
          default: ''
        domain:
          type: string
          minLength: 1
        path:
          type: string
          default: /
        secure:
          type: boolean
        httpOnly:
          type: boolean
        hostOnly:
          type: boolean
        sameSite:
          type: string
          enum:
          - Strict
          - Lax
          - None
        session:
          type: boolean
        expires:
          type: number
        expirationDate:
          type: number
        expiry:
          type: number
    ExtractionField:
      type: object
      required:
      - source
      properties:
        source:
          type: string
          enum:
          - dom
          - network
        selector:
          type: string
        value:
          type: string
          enum:
          - text
          - html
          - attribute
          default: text
        attribute:
          type: string
        urlIncludes:
          type: string
        path:
          type: string
          description: JSON path for a matching network response.
        multiple:
          type: boolean
        parse:
          type: string
          enum:
          - string
          - number
          - integer
          - boolean
          - json
        regex:
          type: string
        required:
          type: boolean
    Geolocation:
      type: object
      required:
      - latitude
      - longitude
      properties:
        latitude:
          type: number
        longitude:
          type: number
    Proxy:
      type: object
      description: Use server OR protocol/host/port. server must be an http:// or socks5:// URL with an explicit port, without embedded credentials, query, fragment, or non-root path. Port range is 1-65535. Provide both non-empty username and password, or omit both. Custom proxy and countryCode are mutually exclusive. Proxy failures never fall back to a direct connection.
      properties:
        server:
          type: string
          example: http://proxy.example.com:8080
        protocol:
          type: string
          enum:
          - http
          - socks5
        host:
          type: string
        port:
          oneOf:
          - type: integer
            minimum: 1
            maximum: 65535
          - type: string
            pattern: ^[0-9]+$
        username:
          type: string
          minLength: 1
          writeOnly: true
        password:
          type: string
          minLength: 1
          writeOnly: true
      oneOf:
      - required:
        - server
        not:
          required:
          - host
      - required:
        - protocol
        - host
        - port
        not:
          required:
          - server
    Action:
      oneOf:
      - type: object
        required:
        - type
        - milliseconds
        properties:
          type:
            type: string
            enum:
            - wait
          milliseconds:
            type: number
      - type: object
        required:
        - type
        - selector
        properties:
          type:
            type: string
            enum:
            - waitForSelector
          selector:
            type: string
          timeoutMs:
            type: number
      - type: object
        required:
        - type
        - selector
        properties:
          type:
            type: string
            enum:
            - click
          selector:
            type: string
      - type: object
        required:
        - type
        - selector
        - value
        properties:
          type:
            type: string
            enum:
            - fill
          selector:
            type: string
          value:
            type: string
      - type: object
        required:
        - type
        - selector
        - key
        properties:
          type:
            type: string
            enum:
            - press
          selector:
            type: string
          key:
            type: string
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - scroll
          selector:
            type: string
          x:
            type: number
          y:
            type: number
    BrowserSettings:
      type: object
      description: Reusable browser options. proxy and countryCode cannot be supplied together. Browser tasks and temporary CDP sessions use a managed proxy when selection is omitted. Cloud browser API-key starts have stricter top-level custom proxy requirements described on their operations.
      properties:
        viewport:
          $ref: '#/components/schemas/Viewport'
        locale:
          type: string
          example: en-US
        timezoneId:
          type: string
          example: Asia/Shanghai
        geolocation:
          $ref: '#/components/schemas/Geolocation'
        proxy:
          $ref: '#/components/schemas/Proxy'
        countryCode:
          type: string
          description: GLOBAL or a two-letter region code; cannot be combined with proxy.
          example: US
        userAgent:
          type: string
        userAgentMode:
          type: string
          enum:
          - custom
          - random
        userAgentOs:
          type: string
          enum:
          - windows
          - macos
        fingerprint:
          $ref: '#/components/schemas/Fingerprint'
        cookies:
          type: array
          items:
            $ref: '#/components/schemas/Cookie'
  responses:
    TaskError:
      description: 'Browser-task failure. 400 invalid URL/options; 401 invalid API key; 402 INSUFFICIENT_CREDITS; 404 unavailable Chrome Web Store listing; 422 missing content/fields or invalid extraction configuration; 429 rate limit; 500 unclassified failure; 502 proxy/target failure; 503 queue/worker unavailable; 504 task/navigation/proxy timeout. A target HTTP 403 may be wrapped as a service HTTP 502: inspect code and upstreamStatus when supplied rather than assuming a proxy failure.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ApiError:
      description: Error response. Typical statuses are 400 invalid input, 401 invalid authentication, 402 payment/credits required, 403 ownership mismatch, 404 missing resource, 409 state or quota conflict, 410 expired session, 429 rate/concurrency limit, 500 internal failure, 502 upstream failure, 503 capacity/runtime unavailable, or 504 timeout. Not every status applies to every operation. Use HTTP status and code when present.
      headers:
        X-Trace-Id:
          description: Request correlation identifier.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Full API key created in the AdsCrawl dashboard.
    SessionBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Login session JWT. Do not put an API key in the Bearer header.
    SessionCookie:
      type: apiKey
      in: cookie
      name: access_token
      description: Owner login session; subject to browser cookie and origin policies.
    CdpDataToken:
      type: apiKey
      in: query
      name: token
      description: Scoped data token from cdpBaseUrl; not the account API key.
externalDocs:
  description: AdsCrawl documentation and WebSocket examples
  url: https://www.adscrawl.net/docs/
x-provenance:
  method: harvested
  publisher: AdsCrawl
  source: https://www.adscrawl.net/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)