openapi: 3.2.0
info:
  title: AdsCrawl Cloud browsers 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: Cloud browsers
  description: Persistent profiles and browser lifecycle. Starting requires a paid plan.
paths:
  /cloud-browsers:
    get:
      operationId: listCloudBrowsers
      tags:
      - Cloud browsers
      summary: List saved profiles and account-wide quotas
      security:
      - ApiKey: []
      - SessionBearer: []
      - SessionCookie: []
      parameters:
      - name: page
        in: query
        description: Defaults to 1; capped at 10000. Invalid or non-positive values use the default.
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        description: Defaults to and is capped at 10. Invalid or non-positive values use the default.
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Profiles owned by the authenticated user. limit is saved-profile capacity; runningCount includes starting/running/stopping sessions across all pages and API keys. Temporary CDP sessions are separate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CloudBrowser'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      pageSize:
                        type: integer
                      total:
                        type: integer
                      totalPages:
                        type: integer
                  limit:
                    type: integer
                  runningLimit:
                    type: integer
                  runningCount:
                    type: integer
        default:
          $ref: '#/components/responses/ApiError'
    post:
      operationId: createCloudBrowser
      tags:
      - Cloud browsers
      summary: Save a cloud browser profile without starting it
      description: An empty object is valid. Creating a profile consumes saved-profile allowance, not running allowance. A saved proxy does not replace the required top-level proxy on every API-key-authenticated start.
      security:
      - ApiKey: []
      - SessionBearer: []
      - SessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                remark:
                  type: string
                  maxLength: 255
                browserSettings:
                  $ref: '#/components/schemas/BrowserSettings'
            example:
              remark: API profile
      responses:
        '201':
          description: Profile saved; its runtime is stopped.
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - id
                properties:
                  ok:
                    type: boolean
                  id:
                    type: string
                    format: uuid
        default:
          $ref: '#/components/responses/ApiError'
  /cloud-browsers/launch:
    post:
      operationId: launchCloudBrowser
      tags:
      - Cloud browsers
      summary: Create a profile and start its browser
      description: 'Requires an explicit custom proxy for every authentication method. Returns 201 only after running is confirmed. Each call creates a new profile without an idempotency key: do not automatically repeat launch. On failure after creation, inspect the returned id and retry stop with a bound. Stop retains the profile and snapshots; closing a viewer does not stop the browser or billing. Startup can wait 60 seconds and cleanup confirmation can take up to 120 additional seconds.'
      security:
      - ApiKey: []
      - SessionBearer: []
      - SessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloudLaunchRequest'
            example:
              proxy:
                server: http://proxy.example.com:8080
              tabs:
              - https://example.com
      responses:
        '201':
          description: Profile created with a confirmed running browser.
          headers:
            Location:
              description: Profile detail API URL, not the interactive viewer.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudLifecycleResult'
        default:
          $ref: '#/components/responses/CloudStartError'
  /cloud-browsers/{id}:
    parameters:
    - $ref: '#/components/parameters/CloudBrowserId'
    get:
      operationId: getCloudBrowser
      tags:
      - Cloud browsers
      summary: Read a saved profile and actual runtime state
      description: Returns the profile directly without a data wrapper. Use runtime.status as returned. A missing node or connection URL does not confirm shutdown. Proxy credentials are removed from responses; saved cookies remain readable by their owner. Viewer access requires the owner's login session.
      security:
      - ApiKey: []
      - SessionBearer: []
      - SessionCookie: []
      responses:
        '200':
          description: Saved profile and runtime status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudBrowser'
        default:
          $ref: '#/components/responses/ApiError'
  /cloud-browsers/{id}/start:
    parameters:
    - $ref: '#/components/parameters/CloudBrowserId'
    post:
      operationId: startCloudBrowser
      tags:
      - Cloud browsers
      summary: Start a saved profile
      description: With API-key authentication, send a valid top-level proxy on every start; saved settings, countryCode, or source=web cannot replace it. Session authentication requires apiKeyId and may use an explicit managed region or saved proxy selection. Start overrides apply to this run only. Both authentication paths require a proxy; failures never fall back to a direct connection. Starting/running/stopping reserve running allowance. Starting an active profile returns 409.
      security:
      - ApiKey: []
      - SessionBearer: []
      - SessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloudStartRequest'
            example:
              proxy:
                server: http://proxy.example.com:8080
      responses:
        '200':
          description: Runtime confirmed running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudLifecycleResult'
        default:
          $ref: '#/components/responses/CloudStartError'
  /cloud-browsers/{id}/stop:
    parameters:
    - $ref: '#/components/parameters/CloudBrowserId'
    post:
      operationId: stopCloudBrowser
      tags:
      - Cloud browsers
      summary: Stop a browser while retaining its profile
      description: A 202 response means shutdown is pending, not complete. Poll profile detail until runtime.status is stopped. Stopping still occupies a running slot; confirmed stopped releases it. Saved-profile count is unchanged. Stopping an already stopped profile returns 200.
      security:
      - ApiKey: []
      - SessionBearer: []
      - SessionCookie: []
      responses:
        '200':
          description: Runtime stopped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudLifecycleResult'
        '202':
          description: Shutdown pending; query detail to confirm stopped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudLifecycleResult'
        default:
          $ref: '#/components/responses/ApiError'
components:
  parameters:
    CloudBrowserId:
      name: id
      in: path
      required: true
      description: Saved profile ID; distinct from its runtime session ID.
      schema:
        type: string
        format: uuid
  schemas:
    CloudLaunchRequest:
      type: object
      required:
      - proxy
      additionalProperties: false
      properties:
        proxy:
          $ref: '#/components/schemas/Proxy'
        apiKeyId:
          type: string
          format: uuid
          description: Required with session authentication. With API-key authentication, any supplied ID must match that key.
        tabs:
          type: array
          maxItems: 8
          description: HTTP(S) URLs; at most one tab may be active. When none is active, the first is selected.
          items:
            oneOf:
            - type: string
              format: uri
            - type: object
              required:
              - url
              properties:
                url:
                  type: string
                  format: uri
                active:
                  type: boolean
                  default: false
        cookies:
          type: array
          maxItems: 10000
          items:
            $ref: '#/components/schemas/Cookie'
        fingerprint:
          $ref: '#/components/schemas/Fingerprint'
    Viewport:
      type: object
      required:
      - width
      - height
      properties:
        width:
          type: number
        height:
          type: number
    CloudStartRequest:
      type: object
      description: API-key callers must provide proxy; session callers must provide apiKeyId. These requirements depend on authentication.
      properties:
        proxy:
          $ref: '#/components/schemas/Proxy'
        apiKeyId:
          type: string
          format: uuid
        countryCode:
          type: string
          description: Session authentication only; cannot be combined with proxy.
        cookies:
          type: array
          items:
            $ref: '#/components/schemas/Cookie'
        fingerprint:
          $ref: '#/components/schemas/Fingerprint'
    CloudLifecycleResult:
      type: object
      properties:
        ok:
          type: boolean
        id:
          type: string
          format: uuid
        source:
          type: string
          enum:
          - manual
          - launch
        deleteOnStop:
          type: boolean
        deleted:
          type: boolean
        runtime:
          $ref: '#/components/schemas/CloudRuntime'
        traceId:
          type: string
    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
    CloudBrowser:
      type: object
      properties:
        id:
          type: string
          format: uuid
        source:
          type: string
          enum:
          - manual
          - launch
        deleteOnStop:
          type: boolean
          description: Current profiles are retained on stop; false.
        deleted:
          type: boolean
        remark:
          type: string
        browserSettings:
          type: object
          description: Saved browser settings with proxy credentials removed; may include owner-readable cookies and snapshots.
          additionalProperties: true
        proxyDisplayIp:
          type:
          - string
          - 'null'
        proxyDisplayRegion:
          type:
          - string
          - 'null'
        lastOpenedAt:
          type:
          - string
          - 'null'
          format: date-time
        updatedAt:
          type: string
          format: date-time
        runtime:
          $ref: '#/components/schemas/CloudRuntime'
    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'
    CloudRuntime:
      type: object
      required:
      - status
      properties:
        runtimeKind:
          type: string
          enum:
          - neko
          - worker_cdp
        status:
          type: string
          enum:
          - starting
          - running
          - stopping
          - stopped
        sessionId:
          type: string
        expiresAt:
          type: string
          format: date-time
        connectUrl:
          type: string
          format: uri
          description: Optional interactive viewer URL when running; requires the profile owner's login session.
        cdpBaseUrl:
          type: string
          format: uri
          description: Only worker_cdp may return this; neko omits it.
  responses:
    CloudStartError:
      description: Start/launch failed. Includes 400 PROXY_REQUIRED or INVALID_PROXY, 402 PAID_PLAN_REQUIRED or INSUFFICIENT_CREDITS, 409 CLOUD_BROWSER_CONCURRENCY_LIMIT, and runtime 5xx failures. Errors after profile creation may include id, source, deleted, runtime, and Location. An unconfirmed cleanup remains stopping and reserves quota. Do not automatically repeat launch; inspect the existing profile and stop it.
      headers:
        Location:
          description: Profile detail URL if a profile was created.
          schema:
            type: string
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/Error'
            - $ref: '#/components/schemas/CloudLifecycleResult'
    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)