---
title: "Open a browser session"
method: POST
path: "/web/v1/session"
tags: ["Web Tools"]
---

# Open a browser session

`POST /web/v1/session`

## Request

- Base URL: `https://api.oassis.dev`
- URL: `https://api.oassis.dev/web/v1/session`
- Auth: one of:
  - HTTP bearer
  - none

Opens a session and navigates. Same fields as /scrape; `formats` defaults to ["controls"]. Returns `sessionId`. HTTP supports the same Bearer API key and shared credits as MCP, or an independent x402 wallet payment.

## Request body

- object
  - `url` string, uri, required: Page to process.
  - `formats` string[]: Outputs you want in the same response. `controls` is the map of what can be clicked; `elements` needs `selectors`; `json` needs `json.prompt` or `json.schema`.
  - `selectors` string[]: CSS selectors for the `elements` format.
  - `json` object: For the `json` format: a `prompt` describing what to pull out, a JSON `schema` to fill, or both.
    - `prompt` string
    - `schema` object
  - `screenshot` object: Options for the `screenshot` format: `fullPage` for the whole page, `type` (png, jpeg, webp), `quality` 1-100 (not with png), `omitBackground`, `selector` to capture one element, and its own `viewport`.
    - `fullPage` boolean
    - `type` 'png' | 'jpeg' | 'webp'
    - `quality` integer
    - `omitBackground` boolean
    - `selector` string
    - `viewport` object
      - `width` integer, required
      - `height` integer, required
      - `deviceScaleFactor` number
  - `pdf` object: Options for the `pdf` format: `format` (a4, letter, legal…), `landscape`, `printBackground`, `scale` 0.1 to 2.
    - `format` 'letter' | 'legal' | 'tabloid' | 'ledger' | 'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6'
    - `landscape` boolean
    - `printBackground` boolean
    - `scale` number
  - `controls` object: Options for the `controls` format: `visibleOnly`, and `limit` (1 to 1000) to cut the map.
    - `visibleOnly` boolean
    - `limit` integer
  - `links` object: Options for the `links` format: `visibleOnly`, `excludeExternal` to keep only internal links.
    - `visibleOnly` boolean
    - `excludeExternal` boolean
  - `wait` object: When to consider the page loaded: `until` (load, domcontentloaded, networkidle0, networkidle2), `selector` to wait for, `timeout` in ms.
    - `until` 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
    - `selector` string
    - `timeout` integer
  - `request` object: How to make the request: `headers`, `cookies`, `userAgent`, and `auth` for basic authentication.
    - `headers` object
    - `cookies` object[]
      - `name` string, required
      - `value` string, required
      - `domain` string
      - `path` string
      - `secure` boolean
      - `httpOnly` boolean
    - `userAgent` string
    - `auth` object
      - `username` string, required
      - `password` string, required
  - `block` object: What not to load, which makes a render faster and cheaper. `resourceTypes` takes image, font, stylesheet, media… and `urlPatterns` are regular expressions, not globs: `\.svg$`, not `*.svg`.
    - `resourceTypes` string[]
    - `urlPatterns` string[]
  - `maxAge` integer: Accept an answer up to this many milliseconds old. A cache hit costs $0.0002 instead of the format price. Leave it out to force a fresh render.
  - `binaryAs` 'base64': How a screenshot or a PDF comes back. `base64` is the only value today.
  - `viewport` object: The window to render in: `width`, `height`, `deviceScaleFactor`.
    - `width` integer, required
    - `height` integer, required
    - `deviceScaleFactor` number

## Response `200`

The result.

## Other responses

- `400`: Invalid request; nothing is executed.
- `401`: Invalid or revoked API key.
- `402`: Insufficient account credits, or x402 payment required. The wallet challenge travels in PAYMENT-REQUIRED; a 402 is not a payment or an execution.
- `503`: Operation temporarily unavailable.

---

[API](https://skmtc.dev/oassis/apis/oassis-web-scraping-crawling-and-browser-control-for-ai-agen.md) · [All operations](https://skmtc.dev/oassis/apis/oassis-web-scraping-crawling-and-browser-control-for-ai-agen/llms.txt) · [OpenAPI document](https://skmtc.dev/oassis/apis/oassis-web-scraping-crawling-and-browser-control-for-ai-agen/revisions/dedc2b717b91?raw)