{ "openapi": "3.0.4", "info": { "title": "ScrapingDuck API", "description": "Web Scraping API with custom browser action flows.", "contact": { "name": "ScrapingDuck", "url": "https://scrapingduck.com/" }, "version": "v1.3.0+e6f9a0adc3d916ec63dd466329b25dc07e2b31b1" }, "paths": { "/v1/actions": { "get": { "tags": [ "Actions" ], "summary": "Returns example action objects for each available action.", "description": "The returned array items can be pasted directly into LaunchBrowserRequest.actions.\n \nPossible error codes:\n- 401 (unauthorized): The API key is missing or invalid.\n- 500 (unhandled_error): unexpected server failure", "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { } }, "example": [ { "type": "VisitUrlAction", "url": "https://news.ycombinator.com" }, { "type": "GetHtmlAction" }, { "type": "ExtractArticleAction" } ] }, "application/json": { "schema": { "type": "array", "items": { } }, "example": [ { "type": "VisitUrlAction", "url": "https://news.ycombinator.com" }, { "type": "GetHtmlAction" }, { "type": "ExtractArticleAction" } ] }, "text/json": { "schema": { "type": "array", "items": { } }, "example": [ { "type": "VisitUrlAction", "url": "https://news.ycombinator.com" }, { "type": "GetHtmlAction" }, { "type": "ExtractArticleAction" } ] } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/browser/actions/execute": { "post": { "tags": [ "Browser" ], "summary": "Executes a list of browser actions.", "description": "This endpoint allows for the execution of a sequence of actions in a specified browser environment.\n \nDefault Behavior:\n- A realistic, rotating browser fingerprint will be used.\n- The browser's locale and timezone will be matched to the proxy's IP address geolocation.\n \nOverrides:\n- Providing a `deviceName` uses that specific device profile.\n- Providing a `locale` or `timezone` will disable the automatic matching based on the proxy.\n \nInvariants:\n- The `actions` list must contain at least 1 and no more than 50 items.\n- Actions are executed sequentially.\n- Any URL provided in an action must be an absolute URL using the http or https scheme.\n \nExample Request:\n```json\n{\n \"actions\": [\n { \"type\": \"VisitUrlAction\", \"url\": \"https://example.com\" },\n { \"type\": \"GetHtmlAction\" }\n ]\n}\n```\n \nPossible error codes:\n- 400 (validation_error): The request body is invalid. This can happen if the `actions` array is missing, empty, or if the JSON is malformed.\n- 400 (too_many_actions): The number of actions in the `actions` array exceeds the server limit of 50.\n- 401 (unauthorized): The API key is missing or invalid.\n- 404 (device_not_found): The specified `deviceName` does not exist. A list of available devices can be retrieved from the `/devices` endpoint.\n- 400 (unsupported_action): The `type` of an action in the `actions` array is not a recognized action.\n- 400 (invalid_url_scheme): An action contains a URL that is not a valid HTTP or HTTPS URL.\n- 500 (unhandled_error): An unexpected server-side error occurred during the execution of the request.", "parameters": [ { "name": "deviceName", "in": "query", "description": "The device to emulate. Example: \"Desktop Chrome\"", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "The BCP-47 language tag to set in the browser. Example: \"en-US\"", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "The IANA time zone ID to set in the browser. Example: \"America/New_York\"", "schema": { "type": "string" } }, { "name": "disableResourceExclusion", "in": "query", "description": "Disables default rules that block tracking and ad resources. Set to true to load all page resources.\nDefault: false", "schema": { "type": "boolean" } }, { "name": "useAdvancedSpoofing", "in": "query", "description": "Enables advanced techniques to avoid bot detection.\nWhen enabled, it can happen that the device name will be ignored.\nDefault: true", "schema": { "type": "boolean" } }, { "name": "disableJavaScript", "in": "query", "description": "Disables JavaScript rendering and executes the request using a faster, non-interactive mechanism.\nUseful for scraping static content at lower cost.\nDefault: false", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBrowserAutomationRequest" }, "example": { "actions": [ { "type": "VisitUrlAction", "url": "https://news.ycombinator.com" }, { "type": "VisitRandomLinkAction", "viewTime": 5, "stayOnDomain": true, "goBack": true }, { "type": "GetHtmlAction" } ] } }, "text/json": { "schema": { "$ref": "#/components/schemas/PublicBrowserAutomationRequest" }, "example": { "actions": [ { "type": "VisitUrlAction", "url": "https://news.ycombinator.com" }, { "type": "VisitRandomLinkAction", "viewTime": 5, "stayOnDomain": true, "goBack": true }, { "type": "GetHtmlAction" } ] } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PublicBrowserAutomationRequest" }, "example": { "actions": [ { "type": "VisitUrlAction", "url": "https://news.ycombinator.com" }, { "type": "VisitRandomLinkAction", "viewTime": 5, "stayOnDomain": true, "goBack": true }, { "type": "GetHtmlAction" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" }, "example": { "executionId": "myApiKey_a1b2c3d4", "results": [ { "type": "VisitUrlActionResult", "success": true, "data": { "status": 200 } }, { "type": "GetHtmlActionResult", "success": true, "data": { "html": "..." } } ], "meta": { "actionsRequested": 2, "actionsSucceeded": 2, "startedAtUtc": "2025-01-01T12:00:00Z", "finishedAtUtc": "2025-01-01T12:00:02Z", "durationMs": 2000, "responseSizeBytes": 1234, "maxActionsAllowed": 50 } } }, "application/json": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" }, "example": { "executionId": "myApiKey_a1b2c3d4", "results": [ { "type": "VisitUrlActionResult", "success": true, "data": { "status": 200 } }, { "type": "GetHtmlActionResult", "success": true, "data": { "html": "..." } } ], "meta": { "actionsRequested": 2, "actionsSucceeded": 2, "startedAtUtc": "2025-01-01T12:00:00Z", "finishedAtUtc": "2025-01-01T12:00:02Z", "durationMs": 2000, "responseSizeBytes": 1234, "maxActionsAllowed": 50 } } }, "text/json": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" }, "example": { "executionId": "myApiKey_a1b2c3d4", "results": [ { "type": "VisitUrlActionResult", "success": true, "data": { "status": 200 } }, { "type": "GetHtmlActionResult", "success": true, "data": { "html": "..." } } ], "meta": { "actionsRequested": 2, "actionsSucceeded": 2, "startedAtUtc": "2025-01-01T12:00:00Z", "finishedAtUtc": "2025-01-01T12:00:02Z", "durationMs": 2000, "responseSizeBytes": 1234, "maxActionsAllowed": 50 } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://httpstatuses.com/400", "title": "Invalid request body", "status": 400, "detail": "At least one action is required.", "code": "validation_error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://httpstatuses.com/400", "title": "Invalid request body", "status": 400, "detail": "At least one action is required.", "code": "validation_error" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://httpstatuses.com/400", "title": "Invalid request body", "status": 400, "detail": "At least one action is required.", "code": "validation_error" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } } } } } } }, "/v1/browser/actions/execute-extended": { "post": { "tags": [ "Browser" ], "summary": "Executes a list of browser actions with customizable browser and view settings. For internal use.", "parameters": [ { "name": "deviceName", "in": "query", "description": "The device to emulate. Example: \"Desktop Chrome\"", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "The BCP-47 language tag to set in the browser. Example: \"en-US\"", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "The IANA time zone ID to set in the browser. Example: \"America/New_York\"", "schema": { "type": "string" } }, { "name": "disableResourceExclusion", "in": "query", "description": "Disables default rules that block tracking and ad resources. Set to true to load all page resources.\nDefault: false", "schema": { "type": "boolean" } }, { "name": "useAdvancedSpoofing", "in": "query", "description": "Enables advanced techniques to avoid bot detection.\nWhen enabled, it can happen that the device name will be ignored.\nDefault: true", "schema": { "type": "boolean" } }, { "name": "disableJavaScript", "in": "query", "description": "Disables JavaScript rendering and executes the request using a faster, non-interactive mechanism.\nUseful for scraping static content at lower cost.\nDefault: false", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAutomationRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/BrowserAutomationRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/BrowserAutomationRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/browser/html": { "get": { "tags": [ "Browser" ], "summary": "Fetches the full HTML content of a web page.", "description": "A convenience endpoint that visits the specified URL and returns its HTML.\nBrowser behavior can be customized using the optional query parameters.\n \nDefault Behavior:\n- If `deviceName` is omitted, a realistic, rotating browser fingerprint will be used.\n- If `locale` and `timezone` are omitted, the browser's locale and timezone will be matched to the proxy's IP address geolocation.\n \nOverrides:\n- Providing a `deviceName` uses that specific device profile.\n- Providing a `locale` or `timezone` will disable the automatic matching based on the proxy.\n \nExample Request:\n`GET /browser/html?url=https://example.com`\n \nPossible error codes:\n- 400 (validation_error): The `url` query parameter is missing or invalid.\n- 401 (unauthorized): The API key is missing or invalid.\n- 404 (device_not_found): The specified `deviceName` does not exist. A list of available devices can be retrieved from the `/devices` endpoint.\n- 400 (invalid_url_scheme): The `url` parameter is not a valid HTTP or HTTPS URL.\n- 500 (unhandled_error): An unexpected server-side error occurred during the execution of the request.", "parameters": [ { "name": "url", "in": "query", "description": "The absolute URL of the page to retrieve.", "required": true, "schema": { "type": "string" } }, { "name": "deviceName", "in": "query", "description": "The device to emulate. Example: \"Desktop Chrome\"", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "The BCP-47 language tag to set in the browser. Example: \"en-US\"", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "The IANA time zone ID to set in the browser. Example: \"America/New_York\"", "schema": { "type": "string" } }, { "name": "disableResourceExclusion", "in": "query", "description": "Disables default rules that block tracking and ad resources. Set to true to load all page resources.\nDefault: false", "schema": { "type": "boolean" } }, { "name": "useAdvancedSpoofing", "in": "query", "description": "Enables advanced techniques to avoid bot detection.\nWhen enabled, it can happen that the device name will be ignored.\nDefault: true", "schema": { "type": "boolean" } }, { "name": "disableJavaScript", "in": "query", "description": "Disables JavaScript rendering and executes the request using a faster, non-interactive mechanism.\nUseful for scraping static content at lower cost.\nDefault: false", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" }, "example": { "executionId": "myApiKey_a1b2c3d4", "results": [ { "type": "VisitUrlActionResult", "success": true, "data": { "status": 200 } }, { "type": "GetHtmlActionResult", "success": true, "data": { "html": "..." } } ], "meta": { "actionsRequested": 2, "actionsSucceeded": 2, "startedAtUtc": "2025-01-01T12:00:00Z", "finishedAtUtc": "2025-01-01T12:00:02Z", "durationMs": 2000, "responseSizeBytes": 1234, "maxActionsAllowed": 50 } } }, "application/json": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" }, "example": { "executionId": "myApiKey_a1b2c3d4", "results": [ { "type": "VisitUrlActionResult", "success": true, "data": { "status": 200 } }, { "type": "GetHtmlActionResult", "success": true, "data": { "html": "..." } } ], "meta": { "actionsRequested": 2, "actionsSucceeded": 2, "startedAtUtc": "2025-01-01T12:00:00Z", "finishedAtUtc": "2025-01-01T12:00:02Z", "durationMs": 2000, "responseSizeBytes": 1234, "maxActionsAllowed": 50 } } }, "text/json": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" }, "example": { "executionId": "myApiKey_a1b2c3d4", "results": [ { "type": "VisitUrlActionResult", "success": true, "data": { "status": 200 } }, { "type": "GetHtmlActionResult", "success": true, "data": { "html": "..." } } ], "meta": { "actionsRequested": 2, "actionsSucceeded": 2, "startedAtUtc": "2025-01-01T12:00:00Z", "finishedAtUtc": "2025-01-01T12:00:02Z", "durationMs": 2000, "responseSizeBytes": 1234, "maxActionsAllowed": 50 } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } } } } }, "deprecated": true } }, "/v1/browser/article": { "get": { "tags": [ "Browser" ], "summary": "Extracts the main article content from a web page.", "description": "A convenience endpoint that visits the specified URL, extracts the main article text, and returns it as clean HTML.\nBrowser behavior can be customized using the optional query parameters.\n \nDefault Behavior:\n- If `deviceName` is omitted, a realistic, rotating browser fingerprint will be used.\n- If `locale` and `timezone` are omitted, the browser's locale and timezone will be matched to the proxy's IP address geolocation.\n \nOverrides:\n- Providing a `deviceName` uses that specific device profile.\n- Providing a `locale` or `timezone` will disable the automatic matching based on the proxy.\n \nExample Request:\n`GET /browser/article?url=https://example.com/news/story`\n \nPossible error codes:\n- 400 (validation_error): The `url` query parameter is missing or invalid.\n- 401 (unauthorized): The API key is missing or invalid.\n- 404 (device_not_found): The specified `deviceName` does not exist. A list of available devices can be retrieved from the `/devices` endpoint.\n- 400 (invalid_url_scheme): The `url` parameter is not a valid HTTP or HTTPS URL.\n- 500 (unhandled_error): An unexpected server-side error occurred during the execution of the request.", "parameters": [ { "name": "url", "in": "query", "description": "The absolute URL of the page to extract the article from.", "required": true, "schema": { "type": "string" } }, { "name": "deviceName", "in": "query", "description": "The device to emulate. Example: \"Desktop Chrome\"", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "The BCP-47 language tag to set in the browser. Example: \"en-US\"", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "The IANA time zone ID to set in the browser. Example: \"America/New_York\"", "schema": { "type": "string" } }, { "name": "disableResourceExclusion", "in": "query", "description": "Disables default rules that block tracking and ad resources. Set to true to load all page resources.\nDefault: false", "schema": { "type": "boolean" } }, { "name": "useAdvancedSpoofing", "in": "query", "description": "Enables advanced techniques to avoid bot detection.\nWhen enabled, it can happen that the device name will be ignored.\nDefault: true", "schema": { "type": "boolean" } }, { "name": "disableJavaScript", "in": "query", "description": "Disables JavaScript rendering and executes the request using a faster, non-interactive mechanism.\nUseful for scraping static content at lower cost.\nDefault: false", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" }, "example": { "executionId": "myApiKey_a1b2c3d4", "results": [ { "type": "VisitUrlActionResult", "success": true, "data": { "status": 200 } }, { "type": "ExtractArticleActionResult", "success": true, "data": { "article": { "uri": "https://news.ycombinator.com/item?id=40825098", "title": "Extracted Article Title", "byline": "John Doe", "content": "

This is the main content of the article.

", "textContent": "This is the main content of the article.", "excerpt": "A short summary of the article content.", "author": "John Doe", "siteName": "Hacker News", "publicationDate": "2025-01-01T12:00:00Z", "featuredImage": "https://via.placeholder.com/1200x630.png", "language": "en", "timeToRead": "00:05:00", "isReadable": true } } } ], "meta": { "actionsRequested": 2, "actionsSucceeded": 2, "startedAtUtc": "2025-01-01T12:00:00Z", "finishedAtUtc": "2025-01-01T12:00:02Z", "durationMs": 2000, "responseSizeBytes": 1234, "maxActionsAllowed": 50 } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } } } } }, "deprecated": true } }, "/v1/devices": { "get": { "tags": [ "Devices" ], "summary": "Gets the list of all available device names.", "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Desktop Chrome", "Mobile Safari" ] }, "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Desktop Chrome", "Mobile Safari" ] }, "text/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Desktop Chrome", "Mobile Safari" ] } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/devices/{name}": { "get": { "tags": [ "Devices" ], "summary": "Gets detailed information for a specific device.", "parameters": [ { "name": "name", "in": "path", "description": "The name/key of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeviceDetailDto" }, "example": { "name": "Desktop Chrome", "context": { "locale": "en-US", "timezoneId": "America/New_York", "userAgent": "Mozilla/5.0 (...)", "viewportWidth": 1920, "viewportHeight": 1080 } } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDetailDto" }, "example": { "name": "Desktop Chrome", "context": { "locale": "en-US", "timezoneId": "America/New_York", "userAgent": "Mozilla/5.0 (...)", "viewportWidth": 1920, "viewportHeight": 1080 } } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeviceDetailDto" }, "example": { "name": "Desktop Chrome", "context": { "locale": "en-US", "timezoneId": "America/New_York", "userAgent": "Mozilla/5.0 (...)", "viewportWidth": 1920, "viewportHeight": 1080 } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'Unknown' not found.", "code": "device_not_found" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'Unknown' not found.", "code": "device_not_found" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'Unknown' not found.", "code": "device_not_found" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/scrape/source": { "get": { "tags": [ "Scrape" ], "summary": "Fetches the raw HTML source of a web page as a direct text/html response.", "description": "This endpoint returns the raw source code of the page.\nReturns the standard HTTP error codes and ProblemDetails JSON on failure, but raw HTML on success.\n\nTo perform a fast HTTP fetch (skipping the full browser render), pass `disableJavaScript=true` in the query string.\n\nExample Request:\n`GET /scrape/source?url=https://example.com`", "parameters": [ { "name": "url", "in": "query", "description": "The absolute URL of the page to retrieve.", "required": true, "schema": { "type": "string" } }, { "name": "deviceName", "in": "query", "description": "The device to emulate. Example: \"Desktop Chrome\"", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "The BCP-47 language tag to set in the browser. Example: \"en-US\"", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "The IANA time zone ID to set in the browser. Example: \"America/New_York\"", "schema": { "type": "string" } }, { "name": "disableResourceExclusion", "in": "query", "description": "Disables default rules that block tracking and ad resources. Set to true to load all page resources.\nDefault: false", "schema": { "type": "boolean" } }, { "name": "useAdvancedSpoofing", "in": "query", "description": "Enables advanced techniques to avoid bot detection.\nWhen enabled, it can happen that the device name will be ignored.\nDefault: true", "schema": { "type": "boolean" } }, { "name": "disableJavaScript", "in": "query", "description": "Disables JavaScript rendering and executes the request using a faster, non-interactive mechanism.\nUseful for scraping static content at lower cost.\nDefault: false", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/scrape/result": { "get": { "tags": [ "Scrape" ], "summary": "Fetches the full scraping result including HTML content and metadata (JSON response).", "description": "Returns the HTML content wrapped in a JSON envelope with metadata (execution time, cost, etc.).\nUse this endpoint when you need execution details along with the content.", "parameters": [ { "name": "url", "in": "query", "description": "The absolute URL of the page to retrieve.", "required": true, "schema": { "type": "string" } }, { "name": "deviceName", "in": "query", "description": "The device to emulate. Example: \"Desktop Chrome\"", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "The BCP-47 language tag to set in the browser. Example: \"en-US\"", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "The IANA time zone ID to set in the browser. Example: \"America/New_York\"", "schema": { "type": "string" } }, { "name": "disableResourceExclusion", "in": "query", "description": "Disables default rules that block tracking and ad resources. Set to true to load all page resources.\nDefault: false", "schema": { "type": "boolean" } }, { "name": "useAdvancedSpoofing", "in": "query", "description": "Enables advanced techniques to avoid bot detection.\nWhen enabled, it can happen that the device name will be ignored.\nDefault: true", "schema": { "type": "boolean" } }, { "name": "disableJavaScript", "in": "query", "description": "Disables JavaScript rendering and executes the request using a faster, non-interactive mechanism.\nUseful for scraping static content at lower cost.\nDefault: false", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/scrape/article": { "get": { "tags": [ "Scrape" ], "summary": "Extracts the main article content from a web page.", "description": "Visits the specified URL, extracts the main article text, and returns it as clean HTML within a JSON envelope.", "parameters": [ { "name": "url", "in": "query", "description": "The absolute URL of the page to extract the article from.", "required": true, "schema": { "type": "string" } }, { "name": "deviceName", "in": "query", "description": "The device to emulate. Example: \"Desktop Chrome\"", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "The BCP-47 language tag to set in the browser. Example: \"en-US\"", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "The IANA time zone ID to set in the browser. Example: \"America/New_York\"", "schema": { "type": "string" } }, { "name": "disableResourceExclusion", "in": "query", "description": "Disables default rules that block tracking and ad resources. Set to true to load all page resources.\nDefault: false", "schema": { "type": "boolean" } }, { "name": "useAdvancedSpoofing", "in": "query", "description": "Enables advanced techniques to avoid bot detection.\nWhen enabled, it can happen that the device name will be ignored.\nDefault: true", "schema": { "type": "boolean" } }, { "name": "disableJavaScript", "in": "query", "description": "Disables JavaScript rendering and executes the request using a faster, non-interactive mechanism.\nUseful for scraping static content at lower cost.\nDefault: false", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/BrowserActionResultActionExecutionResponse" }, "example": { "executionId": "myApiKey_a1b2c3d4", "results": [ { "type": "VisitUrlActionResult", "success": true, "data": { "status": 200 } }, { "type": "ExtractArticleActionResult", "success": true, "data": { "article": { "uri": "https://news.ycombinator.com/item?id=40825098", "title": "Extracted Article Title", "byline": "John Doe", "content": "

This is the main content of the article.

", "textContent": "This is the main content of the article.", "excerpt": "A short summary of the article content.", "author": "John Doe", "siteName": "Hacker News", "publicationDate": "2025-01-01T12:00:00Z", "featuredImage": "https://via.placeholder.com/1200x630.png", "language": "en", "timeToRead": "00:05:00", "isReadable": true } } } ], "meta": { "actionsRequested": 2, "actionsSucceeded": 2, "startedAtUtc": "2025-01-01T12:00:00Z", "finishedAtUtc": "2025-01-01T12:00:02Z", "durationMs": 2000, "responseSizeBytes": 1234, "maxActionsAllowed": 50 } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "url": [ "The url field is required." ] } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/404", "title": "Device not found", "status": 404, "detail": "Device 'NonExistent' not found.", "code": "device_not_found" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://httpstatuses.com/500", "title": "Unhandled server error", "status": 500, "detail": "An unexpected error occurred.", "code": "unhandled_error" } } } } } } } }, "components": { "schemas": { "ActionExecutionMeta": { "type": "object", "properties": { "actionsRequested": { "type": "integer", "description": "Total number of actions requested in this execution.", "format": "int32" }, "actionsSucceeded": { "type": "integer", "description": "Total number of actions that reported success.", "format": "int32" }, "startedAtUtc": { "type": "string", "description": "UTC timestamp (ISO 8601) when execution started.", "format": "date-time" }, "finishedAtUtc": { "type": "string", "description": "UTC timestamp (ISO 8601) when execution finished.", "format": "date-time" }, "durationMs": { "type": "integer", "description": "Total execution duration in milliseconds.", "format": "int64", "readOnly": true }, "responseSizeBytes": { "type": "integer", "description": "Size in bytes of the serialized results payload (not including envelope overhead).", "format": "int64" }, "maxActionsAllowed": { "type": "integer", "description": "The maximum number of actions allowed for a single request at the time of execution.", "format": "int32" } }, "additionalProperties": false, "description": "Metadata describing an execution batch." }, "BrowserAction": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "type": "string", "nullable": true } }, "additionalProperties": false }, "BrowserActionResult": { "type": "object", "properties": { "action": { "type": "string", "nullable": true }, "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" }, "duration": { "type": "string", "format": "date-span" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResultData" }, "nullable": true } }, "additionalProperties": false }, "BrowserActionResultActionExecutionResponse": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Unique execution id (also echoed in X-Execution-Id header).", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserActionResult" }, "description": "List of individual action results in the order executed.", "nullable": true }, "meta": { "$ref": "#/components/schemas/ActionExecutionMeta" } }, "additionalProperties": false, "description": "Envelope returned by action execution endpoints providing results and metadata." }, "BrowserAutomationRequest": { "required": [ "actions" ], "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserAction" }, "description": "Ordered list of actions for the browser to perform.\nActions will be executed sequentially from the first to the last." }, "viewSettings": { "$ref": "#/components/schemas/ViewSettings" } }, "additionalProperties": false, "description": "Request payload for launching a browser session." }, "DeviceContextOptionsDto": { "type": "object", "properties": { "locale": { "type": "string", "description": "The UI locale, e.g. en-US.", "nullable": true }, "timezoneId": { "type": "string", "description": "Time zone ID, e.g. Europe/Berlin.", "nullable": true }, "userAgent": { "type": "string", "description": "The user agent string.", "nullable": true }, "viewportWidth": { "type": "integer", "description": "Viewport width in CSS pixels.", "format": "int32", "nullable": true }, "viewportHeight": { "type": "integer", "description": "Viewport height in CSS pixels.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Public-safe subset of Playwright BrowserNewContextOptions to keep the API surface small." }, "DeviceDetailDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "context": { "$ref": "#/components/schemas/DeviceContextOptionsDto" } }, "additionalProperties": false, "description": "Detailed information about a device (fingerprint), returned by GET /devices/{name}." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": { } }, "PublicBrowserAutomationRequest": { "required": [ "actions" ], "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserAction" }, "description": "Ordered list of actions for the browser to perform.\nActions will be executed sequentially from the first to the last." } }, "additionalProperties": false, "description": "Request payload for launching a browser session. This is the public-facing version without ViewSettings." }, "ResultData": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "data": { "nullable": true } }, "additionalProperties": false }, "TrafficSource": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "percentage": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "ValidationProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "nullable": true } }, "additionalProperties": { } }, "ViewSettings": { "type": "object", "properties": { "trafficSources": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficSource" }, "description": "Gets or sets the traffic sources for the campaign.", "nullable": true }, "keywordList": { "type": "array", "items": { "type": "string" }, "description": "Gets or sets the list of keywords to be used for organic traffic.", "nullable": true }, "referrerUrlList": { "type": "array", "items": { "type": "string" }, "description": "Gets or sets the list of referrer URLs to be used for referral traffic.", "nullable": true }, "socialProfileList": { "type": "array", "items": { "type": "string" }, "description": "Gets or sets the list of social media profiles to be used for social traffic.", "nullable": true }, "maxViewsPerHour": { "type": "integer", "description": "Gets or sets the maximum number of views per hour.", "format": "int64" }, "maxViewsPerDay": { "type": "integer", "description": "Gets or sets the maximum number of views per day.", "format": "int64" }, "viewTime": { "type": "integer", "description": "Gets or sets the time in seconds to stay on the target page.", "format": "int32" } }, "additionalProperties": false, "description": "Represents the view settings for a campaign.\nThis is a domain model and should not contain any UI-specific logic or dependencies." } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "API Key authentication for programmatic access. Enter your API key in the text input below.", "name": "apiKey", "in": "query" } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "Actions", "description": "Provides discovery of available browser actions and example payloads you can paste into the actions list of /browser/actions/execute." }, { "name": "Browser", "description": "Provides endpoints to launch a browser session and execute a list of browser actions." }, { "name": "Devices", "description": "Provides endpoints to list available fingerprint devices and retrieve details for a specific device." }, { "name": "Scrape", "description": "Provides simplified endpoints for scraping content from web pages." } ] }