AdsCrawl Remote CDP API

openapi: 3.2.0
info:
  title: AdsCrawl Remote CDP 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: Remote CDP
  description: Temporary browser sessions and scoped connection tokens.
paths:
  /cdp/sessions:
    post:
      operationId: createCdpSession
      tags:
      - Remote CDP
      summary: Create a temporary browser session
      description: Returns cdpBaseUrl with a scoped data token. Pass that URL directly to Playwright connectOverCDP, or fetch discovery to obtain the protocol WebSocket URL. Do not replace the embedded data token with an API key. Session lifetime and idle timeout are bounded by server configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                idleTimeoutMs:
                  type: number
                maxSessionMs:
                  type: number
                browserSettings:
                  $ref: '#/components/schemas/BrowserSettings'
            example:
              browserSettings:
                viewport:
                  width: 1440
                  height: 900
      responses:
        '201':
          description: Session connection information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CdpSession'
        default:
          $ref: '#/components/responses/ApiError'
    get:
      operationId: listCdpSessions
      tags:
      - Remote CDP
      summary: List temporary sessions for the current API key
      responses:
        '200':
          description: Sessions wrapped in ok and data.
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - data
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CdpSession'
        default:
          $ref: '#/components/responses/ApiError'
  /cdp/sessions/{sessionId}:
    parameters:
    - $ref: '#/components/parameters/SessionId'
    delete:
      operationId: deleteCdpSession
      tags:
      - Remote CDP
      summary: Terminate a temporary session
      description: The session must belong to the current API key.
      responses:
        '200':
          description: Session terminated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
        default:
          $ref: '#/components/responses/ApiError'
  /cdp/sessions/{sessionId}/json/version:
    parameters:
    - $ref: '#/components/parameters/SessionId'
    get:
      operationId: getCdpDiscovery
      tags:
      - Remote CDP
      summary: Read Chrome DevTools Protocol discovery
      description: Authenticate using the data token already embedded in cdpBaseUrl. webSocketDebuggerUrl is rewritten to a public session-scoped URL. Use returned URLs rather than constructing connection URLs manually.
      security:
      - CdpDataToken: []
      responses:
        '200':
          description: Chrome discovery metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Browser:
                    type: string
                  Protocol-Version:
                    type: string
                  User-Agent:
                    type: string
                  webSocketDebuggerUrl:
                    type: string
                    format: uri
                additionalProperties: true
        default:
          $ref: '#/components/responses/ApiError'
  /cdp/live-token:
    post:
      operationId: createLiveControlToken
      tags:
      - Remote CDP
      summary: Issue a single-use live-control token
      description: The API key must own the session. Returns a controlUrl containing a single-use controlToken, valid for 30 seconds. Connect to that WebSocket URL using the live-control protocol documented on the website.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sessionId
              properties:
                sessionId:
                  type: string
      responses:
        '200':
          description: Live-control connection information.
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - controlUrl
                - expiresAt
                properties:
                  ok:
                    type: boolean
                  controlUrl:
                    type: string
                    format: uri
                  expiresAt:
                    type: integer
                    format: int64
                    description: Token expiry as Unix milliseconds, not an RFC3339 string.
        default:
          $ref: '#/components/responses/ApiError'
components:
  schemas:
    Viewport:
      type: object
      required:
      - width
      - height
      properties:
        width:
          type: number
        height:
          type: number
    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
    CdpSession:
      type: object
      required:
      - sessionId
      - expiresAt
      - cdpBaseUrl
      properties:
        sessionId:
          type: string
        expiresAt:
          type: string
          format: date-time
        cdpBaseUrl:
          type: string
          format: uri
          description: Use as returned. Contains a scoped data token and must be treated as sensitive.
      additionalProperties: true
    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
    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
    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'
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      description: Temporary CDP session ID returned by create or list.
      schema:
        type: string
  responses:
    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/