openapi: 3.0.1 info: title: Hyperbrowser Scrape API version: 1.0.0 description: Single-page and batch scrape jobs returning HTML, Markdown, links, and screenshots with status polling. 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/scrape: post: operationId: post-api-scrape summary: Create New Scrape Job requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartScrapeJobParams' responses: '200': description: Scrape job created content: application/json: schema: $ref: '#/components/schemas/StartScrapeJobResponse' '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: - Scrape /api/scrape/{id}: get: operationId: get-api-scrape-id summary: Get Scrape Job Status and Result parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Scrape job details content: application/json: schema: $ref: '#/components/schemas/ScrapeJobResponse' '404': description: 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: - Scrape /api/scrape/{id}/status: get: operationId: get-api-scrape-id-status summary: Get Scrape Job Status parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Scrape job status content: application/json: schema: $ref: '#/components/schemas/JobStatusResponse' '404': description: 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: - Scrape /api/scrape/batch: post: operationId: post-api-scrape-batch summary: Start a Batch Scrape Job requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartBatchScrapeJobParams' responses: '200': description: Batch scrape job started successfully content: application/json: schema: $ref: '#/components/schemas/StartBatchScrapeJobResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: Insufficient plan content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many concurrent batch scrape jobs content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] tags: - Scrape /api/scrape/batch/{id}: get: operationId: get-api-scrape-batch-id summary: Get Batch Scrape Job Status and Results parameters: - name: id in: path required: true schema: type: string responses: '200': description: Batch scrape job details content: application/json: schema: $ref: '#/components/schemas/BatchScrapeJobResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Batch scrape 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: - Scrape /api/scrape/batch/{id}/status: get: operationId: get-api-scrape-batch-id-status summary: Get Batch Scrape Job Status parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Batch scrape job status content: application/json: schema: $ref: '#/components/schemas/JobStatusResponse' '404': description: Batch scrape 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: - Scrape components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Account API key from app.hyperbrowser.ai schemas: BatchScrapeJobResponse: type: object properties: jobId: type: string status: $ref: '#/components/schemas/JobStatus' data: type: array items: $ref: '#/components/schemas/ScrapedPage' error: type: string totalScrapedPages: type: number totalPageBatches: type: number currentPageBatch: type: number batchSize: type: number 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 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. ScrapeJobData: type: object properties: metadata: type: object additionalProperties: oneOf: - type: string - type: array items: type: string markdown: type: string html: type: string links: type: array items: type: string screenshot: type: string ScrapeJobResponse: type: object properties: jobId: type: string status: $ref: '#/components/schemas/JobStatus' data: $ref: '#/components/schemas/ScrapeJobData' error: type: string required: - jobId - status ScrapeOptions: type: object properties: formats: type: array items: type: string enum: - html - links - markdown - screenshot default: - markdown includeTags: type: array items: type: string excludeTags: type: array items: type: string onlyMainContent: type: boolean default: true waitFor: type: number default: 0 timeout: type: number default: 30000 waitUntil: type: string enum: - load - domcontentloaded - networkidle default: load screenshotOptions: type: object description: Options for the screenshot. Both `fullPage` and `cropToContent` cannot be true at the same time. properties: fullPage: type: boolean default: false format: type: string enum: - jpeg - png - webp default: webp cropToContent: type: boolean default: false description: Automatically adjusts the screenshot height to match the page's actual content. If the page is shorter than the viewport, the screenshot is trimmed to remove any empty space below the content. If the page is taller than the viewport, the screenshot is cropped to the height of the viewport. cropToContentMaxHeight: type: number description: The maximum height of the screenshot when `cropToContent` is true. Overrides the height set in the `screen` configuration. cropToContentMinHeight: type: number description: The minimum height of the screenshot when `cropToContent` is true. Overrides the height set in the `screen` configuration. storageState: type: object properties: localStorage: type: object additionalProperties: type: string sessionStorage: type: object additionalProperties: type: string ScrapedPage: type: object properties: url: type: string status: $ref: '#/components/schemas/JobStatus' error: type: string nullable: true metadata: type: object additionalProperties: oneOf: - type: string - type: array items: type: string markdown: type: string html: type: string links: type: array items: type: string screenshot: type: string required: - url - status 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 StartBatchScrapeJobParams: type: object properties: urls: type: array items: type: string sessionOptions: $ref: '#/components/schemas/CreateSessionParams' scrapeOptions: $ref: '#/components/schemas/ScrapeOptions' required: - urls StartBatchScrapeJobResponse: type: object properties: jobId: type: string required: - jobId StartScrapeJobParams: type: object required: - url properties: url: type: string minLength: 1 sessionOptions: $ref: '#/components/schemas/CreateSessionParams' scrapeOptions: $ref: '#/components/schemas/ScrapeOptions' StartScrapeJobResponse: type: object properties: jobId: type: string