Hyperbrowser Extract API
Structured data extraction jobs that pull typed records from one or more pages using prompts and JSON schemas.
OpenAPI Specification
openapi: 3.0.1
info:
title: Hyperbrowser Extract API
version: 1.0.0
description: Structured data extraction jobs that pull typed records from one or more pages using prompts and JSON schemas.
contact:
name: Hyperbrowser
url: https://hyperbrowser.ai
license:
name: Hyperbrowser Terms
url: https://hyperbrowser.ai/terms
servers:
- url: https://api.hyperbrowser.ai
description: Production server
security:
- ApiKeyAuth: []
paths:
/api/extract:
post:
operationId: post-api-extract
summary: Start an Extract Job
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StartExtractJobParams'
responses:
'200':
description: Extract job started successfully
content:
application/json:
schema:
$ref: '#/components/schemas/StartExtractJobResponse'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- ApiKeyAuth: []
tags:
- Extract
/api/extract/{id}:
get:
operationId: get-api-extract-id
summary: Get Extract Job Status and Results
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Extract job details
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractJobResponse'
'404':
description: Extract job not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- ApiKeyAuth: []
tags:
- Extract
/api/extract/{id}/status:
get:
operationId: get-api-extract-id-status
summary: Get Extract Job Status
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Extract job status
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
'404':
description: Extract job not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- ApiKeyAuth: []
tags:
- Extract
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Account API key from app.hyperbrowser.ai
schemas:
CreateSessionParams:
type: object
properties:
useUltraStealth:
type: boolean
default: false
useStealth:
type: boolean
default: false
useProxy:
type: boolean
default: false
proxyServer:
type: string
proxyServerPassword:
type: string
proxyServerUsername:
type: string
proxyCountry:
$ref: '#/components/schemas/ProxyCountry'
proxyState:
$ref: '#/components/schemas/ProxyState'
proxyCity:
type: string
example: new york
nullable: true
description: Desired Country. Is mutually exclusive with proxyState. Some cities might not be supported, so before
using a new city, we recommend trying it out
region:
$ref: '#/components/schemas/SessionRegion'
operatingSystems:
type: array
items:
$ref: '#/components/schemas/OperatingSystem'
device:
type: array
items:
$ref: '#/components/schemas/Device'
platform:
type: array
items:
$ref: '#/components/schemas/Platform'
locales:
type: array
items:
$ref: '#/components/schemas/ISO639_1'
default:
- en
screen:
$ref: '#/components/schemas/ScreenConfig'
solveCaptchas:
type: boolean
default: false
solverType:
type: string
enum:
- visual
description: Optional CAPTCHA solver mode. Set to visual to use the visual reCAPTCHA solver.
adblock:
type: boolean
default: false
trackers:
type: boolean
default: false
annoyances:
type: boolean
default: false
enableWebRecording:
type: boolean
enableVideoWebRecording:
type: boolean
default: false
description: enableWebRecording must also be true for this to work
profile:
$ref: '#/components/schemas/CreateSessionProfile'
acceptCookies:
type: boolean
staticIpId:
type: string
format: uuid
saveDownloads:
type: boolean
default: false
extensionIds:
type: array
items:
type: string
format: uuid
nullable: false
default: []
urlBlocklist:
type: array
items:
type: string
nullable: false
default: []
browserArgs:
type: array
items:
type: string
nullable: false
default: []
imageCaptchaParams:
type: array
items:
type: object
properties:
imageSelector:
type: string
inputSelector:
type: string
nullable: true
timeoutMinutes:
type: number
minimum: 1
maximum: 720
enableWindowManager:
type: boolean
default: false
enableWindowManagerTaskbar:
type: boolean
default: false
viewOnlyLiveView:
type: boolean
default: false
disablePasswordManager:
type: boolean
default: false
enableAlwaysOpenPdfExternally:
type: boolean
default: false
disablePostQuantumKeyAgreement:
type: boolean
default: false
default:
useStealth: false
useProxy: false
acceptCookies: false
CreateSessionProfile:
type: object
properties:
id:
type: string
persistChanges:
type: boolean
persistNetworkCache:
type: boolean
description: When persisting profile changes, also persist the browser's network cache (HTTP cache).
Device:
type: string
enum:
- desktop
- mobile
ErrorResponse:
type: object
properties:
message:
type: string
ExtractJobResponse:
type: object
properties:
jobId:
type: string
status:
$ref: '#/components/schemas/JobStatus'
data:
type: object
error:
type: string
additionalProperties: false
required:
- jobId
- status
ISO639_1:
type: string
enum:
- aa
- ab
- ae
- af
- ak
- am
- an
- ar
- as
- av
- ay
- az
- ba
- be
- bg
- bh
- bi
- bm
- bn
- bo
- br
- bs
- ca
- ce
- ch
- co
- cr
- cs
- cu
- cv
- cy
- da
- de
- dv
- dz
- ee
- el
- en
- eo
- es
- et
- eu
- fa
- ff
- fi
- fj
- fo
- fr
- fy
- ga
- gd
- gl
- gn
- gu
- gv
- ha
- he
- hi
- ho
- hr
- ht
- hu
- hy
- hz
- ia
- id
- ie
- ig
- ii
- ik
- io
- is
- it
- iu
- ja
- jv
- ka
- kg
- ki
- kj
- kk
- kl
- km
- kn
- ko
- kr
- ks
- ku
- kv
- kw
- ky
- la
- lb
- lg
- li
- ln
- lo
- lt
- lu
- lv
- mg
- mh
- mi
- mk
- ml
- mn
- mo
- mr
- ms
- mt
- my
- na
- nb
- nd
- ne
- ng
- nl
- nn
- 'no'
- nr
- nv
- ny
- oc
- oj
- om
- or
- os
- pa
- pi
- pl
- ps
- pt
- qu
- rm
- rn
- ro
- ru
- rw
- sa
- sc
- sd
- se
- sg
- si
- sk
- sl
- sm
- sn
- so
- sq
- sr
- ss
- st
- su
- sv
- sw
- ta
- te
- tg
- th
- ti
- tk
- tl
- tn
- to
- tr
- ts
- tt
- tw
- ty
- ug
- uk
- ur
- uz
- ve
- vi
- vo
- wa
- wo
- xh
- yi
- yo
- za
- zh
- zu
JobStatus:
type: string
enum:
- pending
- running
- completed
- failed
- stopped
JobStatusResponse:
type: object
properties:
status:
$ref: '#/components/schemas/JobStatus'
required:
- status
OperatingSystem:
type: string
enum:
- windows
- android
- macos
- linux
- ios
Platform:
type: string
enum:
- chrome
- firefox
- safari
- edge
ProxyCountry:
type: string
enum:
- AD
- AE
- AF
- AL
- AM
- AO
- AR
- AT
- AU
- AW
- AZ
- BA
- BD
- BE
- BG
- BH
- BJ
- BO
- BR
- BS
- BT
- BY
- BZ
- CA
- CF
- CH
- CI
- CL
- CM
- CN
- CO
- CR
- CU
- CY
- CZ
- DE
- DJ
- DK
- DM
- EC
- EE
- EG
- ES
- ET
- EU
- FI
- FJ
- FR
- GB
- GE
- GH
- GM
- GR
- HK
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IN
- IQ
- IR
- IS
- IT
- JM
- JO
- JP
- KE
- KH
- KR
- KW
- KZ
- LB
- LI
- LR
- LT
- LU
- LV
- MA
- MC
- MD
- ME
- MG
- MK
- ML
- MM
- MN
- MR
- MT
- MU
- MV
- MX
- MY
- MZ
- NG
- NL
- 'NO'
- NZ
- OM
- PA
- PE
- PH
- PK
- PL
- PR
- PT
- PY
- QA
- RANDOM_COUNTRY
- RO
- RS
- RU
- SA
- SC
- SD
- SE
- SG
- SI
- SK
- SN
- SS
- TD
- TG
- TH
- TM
- TN
- TR
- TT
- TW
- UA
- UG
- US
- UY
- UZ
- VE
- VG
- VN
- YE
- ZA
- ZM
- ZW
- ad
- ae
- af
- al
- am
- ao
- ar
- at
- au
- aw
- az
- ba
- bd
- be
- bg
- bh
- bj
- bo
- br
- bs
- bt
- by
- bz
- ca
- cf
- ch
- ci
- cl
- cm
- cn
- co
- cr
- cu
- cy
- cz
- de
- dj
- dk
- dm
- ec
- ee
- eg
- es
- et
- eu
- fi
- fj
- fr
- gb
- ge
- gh
- gm
- gr
- hk
- hn
- hr
- ht
- hu
- id
- ie
- il
- in
- iq
- ir
- is
- it
- jm
- jo
- jp
- ke
- kh
- kr
- kw
- kz
- lb
- li
- lr
- lt
- lu
- lv
- ma
- mc
- md
- me
- mg
- mk
- ml
- mm
- mn
- mr
- mt
- mu
- mv
- mx
- my
- mz
- ng
- nl
- 'no'
- nz
- om
- pa
- pe
- ph
- pk
- pl
- pr
- pt
- py
- qa
- ro
- rs
- ru
- sa
- sc
- sd
- se
- sg
- si
- sk
- sn
- ss
- td
- tg
- th
- tm
- tn
- tr
- tt
- tw
- ua
- ug
- us
- uy
- uz
- ve
- vg
- vn
- ye
- za
- zm
- zw
ProxyState:
type: string
enum:
- AL
- AK
- AZ
- AR
- CA
- CO
- CT
- DE
- FL
- GA
- HI
- ID
- IL
- IN
- IA
- KS
- KY
- LA
- ME
- MD
- MA
- MI
- MN
- MS
- MO
- MT
- NE
- NV
- NH
- NJ
- NM
- NY
- NC
- ND
- OH
- OK
- OR
- PA
- RI
- SC
- SD
- TN
- TX
- UT
- VT
- VA
- WA
- WV
- WI
- WY
- al
- ak
- az
- ar
- ca
- co
- ct
- de
- fl
- ga
- hi
- id
- il
- in
- ia
- ks
- ky
- la
- me
- md
- ma
- mi
- mn
- ms
- mo
- mt
- ne
- nv
- nh
- nj
- nm
- ny
- nc
- nd
- oh
- ok
- or
- pa
- ri
- sc
- sd
- tn
- tx
- ut
- vt
- va
- wa
- wv
- wi
- wy
nullable: true
description: Optional state code for proxies to US states. Is mutually exclusive with proxyCity. Takes in two letter
state code.
ScreenConfig:
type: object
properties:
width:
type: number
default: 1280
height:
type: number
default: 720
SessionRegion:
type: string
enum:
- us-central
- us-west
- us-east
- asia-south
- europe-west
StartExtractJobParams:
type: object
properties:
urls:
type: array
items:
type: string
systemPrompt:
type: string
maxLinks:
type: number
prompt:
type: string
schema:
type: object
sessionOptions:
$ref: '#/components/schemas/CreateSessionParams'
waitFor:
default: 0
type: number
additionalProperties: false
required:
- urls
StartExtractJobResponse:
type: object
properties:
jobId:
type: string
required:
- jobId