unbrowse-ai Pages API

openapi: 3.2.0
info:
  title: Unbrowse Ai Pages API
  version: 1.0.0
  contact:
    name: Unbrowse
    email: hello@unbrowse.ai
    url: https://unbrowse.ai
  termsOfService: https://unbrowse.ai/terms
  description: 'Operations tagged Pages across 2 of this provider''s published API definitions: unbrowse-ai-openapi.json, unbrowse-ai-openapi2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.unbrowse.ai
  description: Unbrowse
- url: https://unbrowse.ai
  description: Unbrowse
security:
- oauth2:
  - unbrowse
- apiKey: []
tags:
- name: Pages
  description: 'Read any page by URL (scrape): HTML, markdown, text or links, with its real status and timing.'
paths:
  /api/v1/scrape:
    post:
      tags:
      - Pages
      operationId: scrape
      summary: Read one page (scrape)
      description: 'One page by URL, for drop-in migration from hosted scrape APIs. The same path as the `unbrowse_scrape` MCP tool: plain HTTP when the server''s HTML carries the content, else Unbrowse''s cloud browser renders it. Charged as one verified call only on success. It never runs past `deadlineMs` (default 45 s, clamped 5–120 s). Every answer carries `metadata.statusCode` / `metadata.status` (the page''s real HTTP status, also when rendered), `timing` (ms, httpMs, renderMs, queuedMs) and `attempts` (HTTP tries); every error carries the same in `error.details`, with `stage` (http or render), `reason`, `httpStatus` and `renderStatus`.


        Errors: 400 invalid input; 402 out of calls; 429 `blocked` (a bot check or an empty page over HTTP and in the browser) with a `Retry-After` header when the page is remembered as walled — for 10 minutes the same host, country and path answer 429 at once; 504 `scrape_timeout` when the deadline passed.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  description: The page, e.g. https://example.com/pricing (https:// is assumed when missing).
                country:
                  type: string
                  description: 'Exit country: a two-letter ISO code (US, GB, DE…) or GLOBAL.'
                formats:
                  type: array
                  items:
                    type: string
                    enum:
                    - markdown
                    - html
                    - text
                    - links
                    - raw
                  description: 'What to return (default ["html"]). raw: the body as sent, over HTTP only.'
                format:
                  type: string
                  enum:
                  - raw_html
                  description: 'Convenience: the whole page''s HTML (formats ["html"] with onlyMainContent false).'
                onlyMainContent:
                  type: boolean
                  description: Drop navigation, headers, footers and asides (default true).
                render:
                  type: string
                  enum:
                  - auto
                  - always
                  - never
                  description: 'auto (default): HTTP first, the browser only when the page needs it.'
                deadlineMs:
                  type: number
                  minimum: 5000
                  maximum: 120000
                  description: Overall time budget in ms (default 45000).
      responses:
        '200':
          description: The page
          content:
            application/json:
              schema:
                type: object
                properties:
                  html:
                    type: string
                  markdown:
                    type: string
                  text:
                    type: string
                  links:
                    type: array
                    items:
                      type: string
                  raw:
                    type: string
                  via:
                    type: string
                    enum:
                    - http
                    - rendered
                  metadata:
                    type: object
                    properties:
                      statusCode:
                        type: integer
                      status:
                        type: integer
                      url:
                        type: string
                      finalUrl:
                        type: string
                      title:
                        type: string
                    additionalProperties: true
                  timing:
                    type: object
                    properties:
                      ms:
                        type: number
                      httpMs:
                        type: number
                      renderMs:
                        type: number
                      queuedMs:
                        type: number
                  attempts:
                    type: integer
                    description: HTTP tries (fresh IPs).
        '400':
          $ref: '#/components/responses/Error'
        '401':
          description: 'Either the Unbrowse credentials are missing or invalid (`error.code` `unauthorized`; the WWW-Authenticate header names the protected-resource metadata), or the page is behind a sign-in (`error.code` `login_required`, not billed): the read was sent to the site''s sign-in page or shown one at the address itself, and Unbrowse has no usable sign-in for the site. `error.details` carries `site`, `finalUrl`, `sessionSent`, `reason` (`login_wall`, `redirect_to_login`) and `next`, the fixes to relay (sync the user''s browser sign-in with `unbrowse cookies sync --domain <site>` or the extension, or save a login).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '504':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          additionalProperties: true
      additionalProperties: true
  responses:
    Error:
      description: An error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Authorization code with PKCE (S256). Clients may register dynamically at /oauth/register. Discovery: /.well-known/oauth-authorization-server; the REST API''s protected-resource metadata is /.well-known/oauth-protected-resource/api.'
      flows:
        authorizationCode:
          authorizationUrl: https://api.unbrowse.ai/authorize
          tokenUrl: https://api.unbrowse.ai/oauth/token
          refreshUrl: https://api.unbrowse.ai/oauth/token
          scopes:
            unbrowse: Run tasks and read results on the user's behalf, with their kept logins.
    apiKey:
      type: http
      scheme: bearer
      description: An Unbrowse API key (create one in the console at https://unbrowse.ai/app).
externalDocs:
  description: Docs
  url: https://docs.unbrowse.ai
x-refined-from:
- unbrowse-ai-openapi.json
- unbrowse-ai-openapi2.json