Nimbleway Extract API
The Extract API from Nimbleway — 3 operation(s) for extract.
OpenAPI Specification
openapi: 3.1.0
info:
title: Nimble SDK Agents Extract API
version: 1.0.0
description: The AI-Native SDK for Real-Time Web Data at scale
servers:
- url: https://sdk.nimbleway.com
tags:
- name: Extract
paths:
/v1/extract:
post:
summary: Extract
tags:
- Extract
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ExtractPayload'
examples:
- url: https://www.example.com
render: true
country: US
locale: en-US
responses:
'200':
description: Successful Response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ExtractResponse'
examples:
- url: https://www.example.com/
task_id: e8ed8ef6-2657-43ba-98d5-a5c79ea7b551
status: success
status_code: 200
data:
html: '...'
markdown: MARKDOWN
parsing: {}
cookies: {}
screenshot: iVBORw0KGgoAAAANSUhEUgAAA...
fetch_request: []
network_capture: []
browser_actions: []
headers: {}
metadata:
query_time: '2026-02-09T10:26:05.817Z'
query_duration: 1877
response_parameters:
input_url: https://www.example.com/
driver: vx8
'400':
description: Unprocessable Entity - Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error402'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/v1/extract/async:
post:
summary: Extract Async
tags:
- Extract
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ExtractPayload'
- $ref: '#/components/schemas/AsyncOptions'
examples:
- url: https://www.example.com
render: true
country: US
locale: en-US
storage_url: s3://mu-s3-bucket.com/
storage_type: s3
callback_url: https://my-callback-url.com/
responses:
'200':
description: Async Task Created
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncResponse'
example:
status: success
task:
id: 8e8cfde8-345b-42b8-b3e2-0c61eb11e00f
state: pending
created_at: '2026-01-24T12:36:24.685Z'
modified_at: '2026-01-24T12:36:24.685Z'
input: {}
'400':
description: Unprocessable Entity - Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error402'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/v1/extract/batch:
post:
summary: Extract Batch
tags:
- Extract
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ExtractBatchPayload'
examples:
- inputs:
- url: https://www.example.com/page1
- url: https://www.example.com/page2
- url: https://www.example.com/page3
- url: https://www.example.com/page4
shared_inputs:
callback_url: https://example.com/webhook/callback
storage_type: s3
storage_url: s3://bucket-name/path/to/object
storage_compress: true
storage_object_name: result-2024-01-15.json
render: true
country: US
locale: en-US
responses:
'200':
description: Extract Batch Created
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponse'
example:
batch_id: 4b0a90bf-c951-42e4-95b3-a95a65ba69fc
batch_size: 1
tasks:
- id: 123e4567-e89b-12d3-a456-426614174000
state: pending
output_url: string
created_at: '2024-01-15T10:30:00Z'
modified_at: '2024-01-15T10:35:00Z'
account_name: string
input: null
batch_id: 4b0a90bf-c951-42e4-95b3-a95a65ba69fc
status_code: 200
api_type: extract
'400':
description: Unprocessable Entity - Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error402'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
components:
schemas:
ExtractPayload:
type: object
properties:
url:
type: string
format: uri
description: Target URL to scrape
examples:
- https://example.com/page
country:
description: Country used to access the target URL, use ISO Alpha-2 Codes
examples:
- US
type: string
state:
description: State used to access the target URL (US and CA only), use ISO Alpha-2 Codes
examples:
- NY
type: string
city:
description: City used to access the target URL
examples:
- new_york
type: string
locale:
description: LCID standard locale used for the URL request. Alternatively, user can use 'auto' for automatic locale based on geo-location
examples:
- en-US
type: string
render:
description: Whether to render JavaScript content using a browser. Use 'auto' to let Nimble automatically select the optimal driver configuration per target domain.
oneOf:
- type: boolean
- type: string
enum:
- auto
examples:
- true
- auto
parse:
description: Whether to parse the response content
type: boolean
parser:
$ref: '#/components/schemas/Parser'
formats:
description: Response format
examples:
- - html
- markdown
type: array
items:
type: string
enum:
- html
- markdown
- screenshot
- headers
- links
driver:
type: string
enum:
- vx6
- vx8
- vx8-pro
- vx10
- vx10-pro
- auto
examples:
- vx8
title: Driver
description: 'Browserless drivers available for web extraction. Use ''auto'' to let Nimble automatically select the optimal driver per target domain (equivalent to render: ''auto'').'
auto_driver_configuration:
type: object
description: 'Customize automatic driver selection: maps driver configuration names to the number of attempts (0-10) to spend on each before escalating to the next (0 skips it). Key order defines the escalation order; at least one configuration must have attempts > 0. Providing it opts the request into ''auto'' driver selection. Ignored when a specific driver is set.'
additionalProperties:
type: integer
minimum: 0
maximum: 10
propertyNames:
enum:
- vx6-fast
- vx6-stealth
- vx8
- vx8-pro
- vx10
- vx10-pro
examples:
- vx6-fast: 1
vx8: 3
vx10-pro: 2
network_capture:
description: Intercept and capture network requests made by the page
type: array
items:
$ref: '#/components/schemas/NetworkCaptureFilter'
browser_actions:
description: Array of actions to perform sequentially during browser rendering
examples:
- wait: 2s
- click:
selector: '#load-more'
timeout: 5s
type: array
items:
$ref: '#/components/schemas/BrowserAction'
browser:
anyOf:
- type: string
enum:
- chrome
- firefox
description: Browser type to emulate
examples:
- chrome
- type: object
properties:
name:
type: string
enum:
- chrome
- firefox
version:
description: Specific browser version to emulate
examples:
- 144.0.0
type: string
required:
- name
os:
description: Operating system to emulate
examples:
- windows
type: string
enum:
- windows
- mac os
- linux
- android
- ios
no_userbrowser:
description: Whether to disable browser-based rendering
examples:
- false
type: boolean
device:
description: Device type for browser emulation
examples:
- desktop
type: string
enum:
- desktop
- mobile
- tablet
tag:
description: User-defined tag for request identification
examples:
- campaign-2024-q1
type: string
is_xhr:
description: Whether to emulate XMLHttpRequest behavior
examples:
- true
type: boolean
http2:
description: Whether to use HTTP/2 protocol
examples:
- true
type: boolean
expected_status_codes:
description: Expected HTTP status codes for successful requests
examples:
- 200
- 201
type: array
items:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
referrer_type:
description: Referrer policy for the request
examples:
- no-referrer
anyOf:
- type: string
enum:
- random
- no-referer
- same-origin
- type: string
enum:
- google
- bing
- facebook
- twitter
- instagram
method:
description: HTTP method for the request
examples:
- GET
type: string
enum:
- GET
- POST
- PUT
- PATCH
- DELETE
render_options:
type: object
properties:
render_type:
description: Type of render completion to wait for
examples:
- idle2
type: string
enum:
- domready
- load
- idle0
- idle2
headless:
description: Whether to run browser in headless mode
examples:
- true
type: boolean
timeout:
description: Maximum time in milliseconds to wait for page render
examples:
- 30000
type: number
minimum: 1
userbrowser:
description: Whether to use a persistent browser session
examples:
- true
type: boolean
include_iframes:
description: Whether to include iframe content in the result
examples:
- true
type: boolean
disabled_resources:
description: Types of resources to block from loading
examples:
- image
- stylesheet
type: array
items:
type: string
enum:
- other
- document
- stylesheet
- image
- media
- font
- script
- texttrack
- xhr
- fetch
- eventsource
- websocket
- manifest
- signedexchange
- ping
- cspviolationreport
- prefetch
- preflight
- fedcm
adblock:
description: Whether to enable ad blocking
examples:
- true
type: boolean
blocked_domains:
description: Domains to block from loading
examples:
- ads.example.com
- tracker.com
minItems: 1
type: array
items:
type: string
minLength: 1
with_performance_metrics:
description: Whether to collect performance metrics during rendering
examples:
- true
type: boolean
no_accept_encoding:
description: Disable content encoding to avoid cached responses
examples:
- true
type: boolean
description: Request body model for the /extract endpoint
required:
- url
AsyncResponse:
type: object
properties:
status:
type: string
examples:
- success
task:
type: object
properties:
id:
type: string
format: uuid
description: Unique task identifier
examples:
- 8e8cfde8-345b-42b8-b3e2-0c61eb11e00f
state:
type: string
description: Current state of the task
enum:
- pending
- processing
- completed
- failed
examples:
- pending
created_at:
type: string
format: date-time
description: Task creation timestamp
examples:
- '2026-01-24T12:36:24.685Z'
account_name:
type: string
description: The user account name
examples:
- my-account
api_type:
type: string
description: The api endpoint used
enum:
- agent
- extract
examples:
- extract
modified_at:
type: string
format: date-time
description: Task last modification timestamp
examples:
- '2026-01-24T12:36:24.685Z'
input:
type: object
description: Original request input parameters
required:
- id
- state
- created_at
- modified_at
- input
required:
- status
- task
examples:
- status: success
task:
id: 8e8cfde8-345b-42b8-b3e2-0c61eb11e00f
state: pending
account_name: my-account
api_type: extract
created_at: '2026-01-24T12:36:24.685Z'
modified_at: '2026-01-24T12:36:24.685Z'
input: {}
Error400:
type: object
title: Error400
properties:
status:
type: string
example: failed
examples:
- failed
msg:
type: string
description: Validation error message describing what went wrong
example: Invalid request parameters
examples:
- Invalid request parameters
error:
type: string
description: The validation error type
example: PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR
examples:
- PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR
details:
type: object
description: Detailed validation error information
example:
schema_validation_errors:
- instancePath: ''
schemaPath: '#/required'
keyword: required
params:
missingProperty: search_engine
message: must have required property 'search_engine'
required:
- status
- msg
example:
status: failed
msg: Invalid request parameters
error: PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR
details:
schema_validation_errors:
- instancePath: ''
schemaPath: '#/required'
keyword: required
params:
missingProperty: search_engine
message: must have required property 'search_engine'
ExtractResponse:
type: object
properties:
url:
type: string
format: uri
description: The URL that was extracted
task_id:
type: string
format: uuid
description: Unique identifier for the extraction task
status:
type: string
description: Status of the extraction
enum:
- success
- failed
status_code:
type: integer
description: HTTP status code from the target website
data:
type: object
description: Data from the extraction
properties:
html:
type: string
description: Raw HTML content of the page
headers:
type: object
description: Response headers from the target website
parsing:
type: object
description: Parsed data when parsing is enabled
markdown:
type: string
description: Markdown content when markdown conversion is enabled
cookies:
type: object
description: Cookies when cookie capture is enabled
fetch_request:
type: array
description: Captured executed fetch requests when enabled
items:
type: object
network_capture:
type: array
description: Captured network activity when enabled
items:
type: object
browser_actions:
type: array
description: Browser actions results
items:
type: object
screenshot:
type: string
description: Base64 encoded screenshot when enabled (requires rendering)
metadata:
type: object
description: Metadata from the extraction
properties:
query_time:
type: string
format: date-time
description: Timestamp when the query was executed
input_url:
type: string
format: uri
description: The original input URL
driver:
type: string
description: Driver used for extraction (depends on target domain and rendering configuration)
examples:
- vx8
warnings:
type: array
description: List of warnings
items:
type: string
required:
- url
- task_id
- status
- status_code
- data
- metadata
ExtractBatchPayload:
type: object
properties:
inputs:
type: array
items:
anyOf:
- $ref: '#/components/schemas/ExtractPayload'
shared_inputs:
allOf:
- $ref: '#/components/schemas/AsyncOptions'
- $ref: '#/components/schemas/ExtractPayload'
required: []
Parser:
type: object
description: Custom extraction recipe defining what data to extract and how to structure it. Each property represents a field in the output.
additionalProperties:
oneOf:
- type: object
description: Terminal parser - extract a single value
properties:
type:
type: string
enum:
- terminal
selector:
$ref: '#/components/schemas/ParserSelector'
extractor:
$ref: '#/components/schemas/ParserExtractor'
required:
- type
- selector
- extractor
- type: object
description: Terminal list parser - extract multiple values
properties:
type:
type: string
enum:
- terminal_list
selector:
$ref: '#/components/schemas/ParserSelector'
extractor:
$ref: '#/components/schemas/ParserExtractor'
required:
- type
- selector
- extractor
- type: object
description: Schema parser - extract nested object
properties:
type:
type: string
enum:
- schema
selector:
$ref: '#/components/schemas/ParserSelector'
fields:
$ref: '#/components/schemas/Parser'
required:
- type
- fields
- type: object
description: Schema list parser - extract list of objects
properties:
type:
type: string
enum:
- schema_list
selector:
$ref: '#/components/schemas/ParserSelector'
fields:
$ref: '#/components/schemas/Parser'
required:
- type
- fields
- type: object
description: Or parser - try multiple strategies
properties:
type:
type: string
enum:
- or
parsers:
type: array
items:
$ref: '#/components/schemas/Parser'
required:
- type
- parsers
- type: object
description: Const parser - return fixed value
properties:
type:
type: string
enum:
- const
value:
description: Fixed value to return
required:
- type
- value
ParserExtractor:
oneOf:
- type: object
description: Extract text content
properties:
type:
type: string
enum:
- text
post_processor:
$ref: '#/components/schemas/PostProcessor'
required:
- type
- type: object
description: Extract attribute value
properties:
type:
type: string
enum:
- attr
attr:
type: string
description: Attribute name (e.g., href, src)
post_processor:
$ref: '#/components/schemas/PostProcessor'
required:
- type
- attr
- type: object
description: Extract as JSON
properties:
type:
type: string
enum:
- json
post_processor:
$ref: '#/components/schemas/PostProcessor'
required:
- type
- type: object
description: Extract raw HTML
properties:
type:
type: string
enum:
- raw
post_processor:
$ref: '#/components/schemas/PostProcessor'
required:
- type
PostProcessor:
type: object
description: Transform extracted data
properties:
type:
type: string
enum:
- number
- string
- date
- regex
- trim
- lowercase
- uppercase
required:
- type
Error429:
type: object
title: Error429
properties:
status:
type: string
example: failed
examples:
- failed
msg:
type: string
example: Rate limit exceeded
examples:
- Rate limit exceeded
required:
- status
- msg
example:
status: failed
msg: Rate limit exceeded
BrowserAction:
type: object
description: 'An action to perform in the browser (one of: goto, wait, wait_for_element, click, press, fill, scroll, auto_scroll, screenshot, get_cookies, fetch)'
properties:
goto:
description: Navigate to a URL
oneOf:
- type: string
format: uri
- type: object
properties:
url:
type: string
format: uri
timeout:
type: number
referer:
type: string
wait_until:
type: string
enum:
- load
- domcontentloaded
- networkidle
- commit
required:
- url
wait:
description: Pause for a duration
oneOf:
- type: string
examples:
- 2s
- type: object
properties:
duration:
type: string
examples:
- 2s
required:
type: boolean
required:
- duration
wait_for_element:
description: Wait for element(s) to appear
oneOf:
- type: string
description: CSS selector
- type: array
items:
type: string
description: Array of CSS selectors
- type: object
properties:
selector:
oneOf:
- type: string
- type: array
items:
type: string
timeout:
type: number
visible:
type: boolean
required:
- selector
click:
description: Click an element or coordinates
oneOf:
- type: string
description: CSS selector
- type: object
description: Click by selector or coordinates
properties:
selector:
type: string
x:
type: number
y:
type: number
relative_to:
type: string
timeout:
type: string
visible:
type: boolean
delay:
type: string
scroll:
type: boolean
count:
type: number
required:
type: boolean
press:
description: Press a keyboard key
oneOf:
- type: string
examples:
- Enter
- type: object
properties:
key:
type: string
examples:
- Enter
delay:
type: number
required:
- key
fill:
type: object
description: Fill an input field with text
properties:
selector:
type: string
description: CSS selector of input element
value:
type: string
description: Text to fill
mode:
type: string
enum:
- type
- paste
timeout:
type: number
typing_interval:
type: number
minimum: 10
maximum: 1000
click_on_element:
type: boolean
scroll:
type: boolean
visible:
type: boolean
delay:
type: number
required:
type: boolean
required:
- selector
- value
scroll:
description: Scroll the page
oneOf:
- type: number
description: Pixels to scroll (positive = down, negative = up)
- type: string
description: Scroll to bottom or CSS selector
- type: object
properties:
y:
type: number
x:
type: number
to:
type: string
description: CSS selector to scroll to
container:
type: string
description: CSS selector of container
visible:
type: boolean
required:
type: boolean
auto_scroll:
description: Automatically scroll to load dynamic content
oneOf:
- type: boolean
- type: number
description: Max duration in milliseconds
- type: object
properties:
max_duration:
type: number
delay_after_scroll:
type: number
step_size:
type: number
description: Pixels to scroll per step
click_selector:
type: string
description: CSS selector to click before scrolling
container:
type: string
description: CSS selector of container
idle_timeout:
type: number
pause_on_selector:
type: string
required:
type: boolean
screenshot:
description: Capture a screenshot
oneOf:
- type: boolean
- type: object
properties:
full_page:
type: boolean
format:
type: string
enum:
- png
- jpeg
- webp
quality:
type: number
minimum: 0
maximum: 100
get_cookies:
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nimbleway/refs/heads/main/openapi/nimbleway-extract-api-openapi.yml