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/ 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)