openapi: 3.2.0
info:
title: Web Scraper API - JavaScript Rendering, Proxy Rotation & CAPTCHA Solving Scraping APIs API
version: 1.0.0
description: 'Executes a sequence of scraping instructions against a target URL and returns the extracted data. Two modes are available via the `jsEnabled` query parameter: `jsEnabled=true` renders the page in a real browser and supports `fill`, `click`, `wait`, iframe switching, image/audio CAPTCHA solving, and other interactive instructions, plus request-level `blockUrl` and `cookies`; `jsEnabled=false` fetches static HTML and supports `postForm`, `getForm`, `getPage`, and `extract`. Every mode''s response is an `extractedData` object keyed by the field names used in your `extract` instructions --- each value is a string when its selector matched exactly one element, or an array of strings when it matched more than one; a selector that matches nothing is omitted from the response entirely. The `text` query parameter strips HTML tags from extracted values; under `jsEnabled=true`, single-element matches are always returned as plain text regardless of `text`, while multi-element matches keep tags unless `text=true` is set.'
contact:
name: APIFreaks Support
url: https://apifreaks.com/contact
email: support@apifreaks.com
servers:
- url: https://api.apifreaks.com/v1.0
description: Web Scraper API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: Scraping APIs
paths:
/scraping:
post:
tags:
- Scraping APIs
summary: Execute a sequence of web scraping instructions against a target URL
description: Runs form-filling, clicking, data-extraction, and CAPTCHA-solving instructions against a target URL and returns the extracted data. Behavior and available instructions depend on the jsEnabled query parameter.
operationId: performScraping
parameters:
- name: url
in: query
required: true
description: Target URL to scrape.
schema:
type: string
format: uri
- name: text
in: query
required: false
description: Set to true to strip HTML tags from extracted values (plain text). Set to false to keep HTML tags. Default is false. Under jsEnabled=true, single-element matches are always plain text regardless of this flag.
schema:
type: boolean
default: false
- name: jsEnabled
in: query
required: false
description: Set to true to render the page in a real browser for dynamic/JavaScript-driven pages (enables fill, click, wait, CAPTCHA-solving, and related instructions). Set to false to fetch static HTML only (enables postForm, getForm, getPage, extract). Default is false.
schema:
type: boolean
default: false
- name: proxy
in: query
required: false
description: Use a proxy for the request. Pass true/false to toggle the default proxy pool, or a proxy URL string to use a specific proxy.
schema:
oneOf:
- type: boolean
- type: string
- name: sslIgnore
in: query
required: false
description: Set to true to ignore SSL certificate errors on the target site. Only works when jsEnabled is true.
schema:
type: boolean
- name: windowSize
in: query
required: false
description: Browser window size in the format 'width,height' (e.g. '1920,1080'). Only works when jsEnabled is true.
schema:
type: string
- name: adBlock
in: query
required: false
description: Set to true to block ads on the target page. Only works when jsEnabled is true.
schema:
type: boolean
- name: captcha
in: query
required: false
description: Set to true to allow CAPTCHA-solving instructions (generalImageCaptcha, fillImageCaptcha, resolveAudioCaptcha) in the request body. Only works when jsEnabled is true.
schema:
type: boolean
requestBody:
required: false
description: 'The request body shape depends on the jsEnabled query parameter, not on any field inside the body itself. Pass jsEnabled=true for the interactive/browser instruction set (JsEnabledTrueBody: fill, click, wait, blockUrl, cookies, CAPTCHA solving, and more). Pass jsEnabled=false (or omit it) for the static-HTML instruction set (JsEnabledFalseBody: postForm, getForm, getPage, extract). instructions is an ordered array executed sequentially.'
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/JsEnabledTrueBody'
- $ref: '#/components/schemas/JsEnabledFalseBody'
examples:
jsEnabledTrue:
summary: Example body for jsEnabled=true (fill, click, wait, extract)
value:
blockUrl:
- https://example.com/ads.js
- https://tracker.example.com/*
cookies:
- name: sessionid
value: abc123
instructions:
- fill:
place: '#username'
value: myuser
- fill:
place: '#password'
value: mypassword
- click: input[type=submit]
- wait: 1000
- extract:
pageTitle: title
welcomeText: h1
jsEnabledFalse:
summary: Example body for jsEnabled=false (extract only)
value:
instructions:
- extract:
pageTitle: title
paragraphs: p
responses:
'200':
description: Successful scraping operation
content:
application/json:
schema:
$ref: '#/components/schemas/ScrapingResponse'
examples:
jsEnabledFalseResult:
summary: Static HTML extract (jsEnabled=false)
value:
extractedData:
pageTitle: <title>Example Domain</title>
paragraphs:
- <p>This domain is for use in documentation examples without needing permission. Avoid use in operations.</p>
- <p><a href="https://iana.org/domains/example">Learn more</a></p>
jsEnabledTrueResult:
summary: Rendered-page extract with a single-match and a multi-match field (jsEnabled=true)
value:
extractedData:
firstQuote: “The world as we have created it is a process of our thinking. It cannot be changed without changing our thinking.”
authors:
- <small class="author" itemprop="author">Albert Einstein</small>
- <small class="author" itemprop="author">J.K. Rowling</small>
- <small class="author" itemprop="author">Albert Einstein</small>
- <small class="author" itemprop="author">Jane Austen</small>
- <small class="author" itemprop="author">Marilyn Monroe</small>
- <small class="author" itemprop="author">Albert Einstein</small>
- <small class="author" itemprop="author">André Gide</small>
- <small class="author" itemprop="author">Thomas A. Edison</small>
- <small class="author" itemprop="author">Eleanor Roosevelt</small>
- <small class="author" itemprop="author">Steve Martin</small>
'400':
description: Bad Request — Missing/invalid parameters, malformed request body, unparseable selectors, or the target URL could not be fetched
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingOrInvalidParams:
summary: Missing or invalid url parameter
value:
error: Invalid Param Exception
message: please pass correct parameters
path: /v1.0/scraping
status: 400
timestamp: '2026-07-23T11:50:14.427Z'
malformedRequestBody:
summary: Malformed JSON request body
value:
timestamp: '2026-07-23T11:47:47.907+00:00'
status: 400
error: JSON Parse Error
message: Invalid or malformed JSON. Please check your request body format and ensure it's valid JSON.
path: /v1/scraping/params
missingInstructions:
summary: Empty or missing instructions body
value:
timestamp: '2026-07-23T11:47:54.568+00:00'
status: 400
error: Bad Request
message: Arguments are missing or wrong
path: /v1/scraping/params
invalidSelector:
summary: Unparseable CSS or XPath selector
value:
timestamp: '2026-07-23T11:50:15.539+00:00'
status: 400
error: Bad Request
message: Check the Css Selectors or Xpath, Some of them are wrong
path: /v1/scraping/params
targetUnreachable:
summary: Target URL could not be reached (DNS/connection failure)
value:
timestamp: '2026-07-23T11:50:16.120+00:00'
status: 400
error: IO Exception
message: Error while reading the datathisdomaindoesnotexist12345xyz.com
path: /v1/scraping/params
targetNonOkStatus:
summary: Target URL returned a non-200 HTTP response
value:
timestamp: '2026-07-23T11:50:26.224+00:00'
status: 400
error: Bad Request
message: Check the url or links
path: /v1/scraping/params
'404':
description: Not Found — Wrong HTTP method or path used against this endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
wrongMethodOrPath:
summary: Endpoint called with a non-POST method
value:
error: Resource Not Found
message: The requested resource could not be found. Please verify the URL and try again.
path: /v1.0/scraping
status: 404
timestamp: '2026-07-23T11:51:33.926Z'
components:
schemas:
ScrapingResponse:
type: object
description: Result of running the scraping instructions against the target URL.
required:
- extractedData
properties:
extractedData:
type: object
description: Container keyed by the field names used in your extract instructions. A field is present only if its selector matched at least one element on the page.
$ref: '#/components/schemas/ExtractedField'
JsEnabledFalseBody:
type: object
description: 'Request body for jsEnabled=false (or omitted): fetches static HTML only, no browser rendering.'
properties:
instructions:
type: array
description: A list of sequential instructions to execute against the static HTML response. Each item is one StaticInstruction object, with exactly one action field set.
items:
$ref: '#/components/schemas/StaticInstruction'
ImageCaptchaInstruction:
type: object
description: Instructions for locating and solving a single image CAPTCHA challenge.
properties:
imagePath:
type: string
description: Selector for the CAPTCHA image element.
textField:
type: string
description: Selector for the field where the CAPTCHA text is entered.
imageUpdatePath:
type: string
description: Selector to refresh or update the CAPTCHA image.
captchaFailedPath:
type: string
description: Selector indicating a CAPTCHA failure so the solver can retry.
model:
type: string
description: Model used for CAPTCHA solving.
enum:
- Model_1
- Model_2
- Model_3
- Model_4
- Model_5
- Model_6
- basicTnImageProcessing
- basicPhImageProcessing
JsEnabledTrueBody:
type: object
description: 'Request body for jsEnabled=true: renders the page in a real browser and supports interactive instructions.'
properties:
blockUrl:
type: array
items:
type: string
description: List of script or URL patterns to block during network requests.
cookies:
type: array
items:
$ref: '#/components/schemas/Cookie'
description: List of cookies to be set in the browser session.
instructions:
type: array
description: An ordered list of step-by-step scraping instructions to be executed in the browser. Each item is one Instruction object, with exactly one action field set.
items:
$ref: '#/components/schemas/Instruction'
FormSubmission:
type: object
description: Form selector and field values to submit via postForm or getForm.
properties:
selector:
type: string
description: CSS or XPath selector identifying the form element.
data:
type: object
description: Form field name/value pairs to submit.
additionalProperties:
title: FormFieldValue
type: string
description: Value to submit for this form field.
ExtractInstruction:
type: object
description: Maps arbitrary output field names to CSS or XPath selectors. Each key becomes a field in the response's extractedData object.
additionalProperties:
title: SelectorForField
type: string
description: 'CSS selector or XPath identifying the element(s) to extract for this output field. Example: ''h1'' or ''/html/body/div/div[2]''.'
ErrorResponse:
type: object
description: Standard error response returned when a request fails.
required:
- error
- message
- path
- status
- timestamp
properties:
error:
type: string
description: Short error category or exception type.
message:
type: string
description: Human-readable error message describing the failure.
path:
type: string
description: API endpoint path that produced the error.
status:
type: integer
description: HTTP status code returned with the error.
timestamp:
type: string
format: date-time
description: Timestamp when the error occurred (ISO 8601).
Cookie:
type: object
description: A single cookie to set in the browser session before running instructions.
required:
- name
- value
properties:
name:
type: string
description: Cookie name.
value:
type: string
description: Cookie value.
ExtractedField:
type:
- string
- array
title: ExtractedField
description: The value scraped for one field of an extract instruction. A string when the selector matched exactly one element (content depends on the text query parameter and, under jsEnabled=true, is always plain text). An array of strings, in document order, when the selector matched more than one element (each entry keeps HTML tags unless text=true is set). A field whose selector matched nothing is omitted from extractedData entirely rather than appearing as an empty value.
items:
type: string
PlaceValue:
type: object
description: A selector/value pair used by fill, select, and clickButtonByValue instructions.
required:
- place
- value
properties:
place:
type: string
description: CSS or XPath selector identifying the target element.
value:
type: string
description: Value to fill, select, or match against.
Instruction:
type: object
description: A single browser scraping step. Exactly one of these action fields is set per instruction; every other field is absent.
properties:
fill:
$ref: '#/components/schemas/PlaceValue'
description: 'Fill action: fills an input field with a value using a CSS or XPath selector.'
click:
type: string
description: 'Click action: CSS selector or XPath identifying the element to click.'
clickIfExist:
type: string
description: 'Click if exists action: CSS selector or XPath identifying the element to click, only if it appears on the page within a short timeout.'
enter:
type: string
description: 'Enter key action: CSS selector or XPath identifying the element to send an Enter keystroke to.'
newTab:
type: boolean
description: 'New tab action: set to true to switch focus to a newly opened browser tab.'
moveToRelativeTab:
type: integer
description: 'Move to relative tab action: relative tab index to move to (e.g. 1 for the next tab, -1 for the previous tab).'
wait:
type: integer
description: 'Wait action: pauses execution for this many milliseconds.'
waitFor:
type: string
description: 'Wait for element action: CSS selector or XPath identifying the element to wait for before continuing.'
select:
$ref: '#/components/schemas/PlaceValue'
description: 'Select dropdown action: selects an option from a dropdown element by selector and matching value.'
jsExe:
type: string
description: 'Execute JavaScript action: JavaScript code to execute inside the page context.'
conditionalCheck:
type: array
description: 'Conditional check action: list of conditional steps, each supporting if-<method> and else-<method> keys with conditions, executed based on element state.'
items:
type: object
description: A single conditional step, supporting if-<method> and else-<method> keys with conditions.
clickButtonByValue:
$ref: '#/components/schemas/PlaceValue'
description: 'Click button by value action: clicks a button that matches a specific text or value attribute.'
generalImageCaptcha:
type: array
description: 'Image captcha solver action: instructions for solving image-based captchas using a selected model.'
items:
$ref: '#/components/schemas/ImageCaptchaInstruction'
blockElement:
type: array
description: 'Block element action: list of CSS selectors or XPaths for elements to block or hide on the page.'
items:
type: string
extract:
$ref: '#/components/schemas/ExtractInstruction'
description: 'Extract data action: defines what data to extract and how, keyed by whatever field names you choose.'
fillImageCaptcha:
type: array
description: 'Fill image captcha action: captures and fills image-based captcha values automatically.'
items:
$ref: '#/components/schemas/ImageCaptchaInstruction'
switchToIframe:
type: string
description: 'Switch to iframe action: switches the browser context into an iframe identified by name or ID.'
switchToParentFrame:
type: boolean
description: 'Switch to parent frame action: returns the browser context from an iframe back to its parent frame.'
resolveAudioCaptcha:
$ref: '#/components/schemas/AudioCaptchaInstruction'
description: 'Resolve audio captcha action: solves audio-based captcha challenges and fills the resolved text into the target field.'
screenshot:
type: string
description: 'Screenshot action: captures a screenshot of the current page state. Can be a boolean-like value or a selector.'
saveimage:
type: string
description: 'Save image action: saves an image from the page by CSS selector or element ID.'
AudioCaptchaInstruction:
type: object
description: Selectors for locating and solving a single audio CAPTCHA challenge.
properties:
audioPath:
type: string
description: Selector for the audio CAPTCHA element.
textField:
type: string
description: Selector for the field where the resolved audio CAPTCHA text is entered.
StaticInstruction:
type: object
description: A single static-HTML scraping step. Exactly one of these action fields is set per instruction; every other field is absent.
properties:
postForm:
$ref: '#/components/schemas/FormSubmission'
description: 'POST form action: submits a form using the POST method. Provide the form''s XPath/CSS selector and input values.'
getForm:
$ref: '#/components/schemas/FormSubmission'
description: 'GET form action: submits a form using the GET method. Provide the form''s XPath/CSS selector and input values.'
extract:
$ref: '#/components/schemas/ExtractInstruction'
description: 'Extract data action: defines what data to extract and how, keyed by whatever field names you choose.'
getPage:
type: string
description: 'Get page action: retrieves the full page content. Optionally provide a URL or selector to target a specific page.'
securitySchemes:
ApiKeyAuthHeader:
type: apiKey
in: header
name: X-apiKey
description: Pass your API key via the X-apiKey request header.
ApiKeyAuthQuery:
type: apiKey
in: query
name: apiKey
description: Pass your API key via the apiKey query parameter.