> ## Documentation Index > Fetch the complete documentation index at: https://docs.driver.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a session > Create a browser session and wait for CDP readiness. hosted, hosted_stealth, and hosted_privacy are hosted browsers; hosted_stealth applies the conservative stealth policy and hosted_privacy the aggressive one. Hosted Canadian sessions without an explicit proxy egress from Driver's Canadian ISP network. Country defaults to US; omitted locale and proxy values are resolved coherently. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/browser/session openapi: 3.0.0 info: version: 1.0.0 title: Driver API description: API for interacting with the Driver.dev browser network. contact: name: Driver support email: alex@driver.dev servers: - url: https://api.driver.dev description: Production security: [] tags: - name: Sessions - name: Profiles - name: Account - name: Extensions - name: Pools externalDocs: url: https://docs.driver.dev description: Driver documentation paths: /v1/browser/session: post: tags: - Sessions summary: Create a session description: >- Create a browser session and wait for CDP readiness. hosted, hosted_stealth, and hosted_privacy are hosted browsers; hosted_stealth applies the conservative stealth policy and hosted_privacy the aggressive one. Hosted Canadian sessions without an explicit proxy egress from Driver's Canadian ISP network. Country defaults to US; omitted locale and proxy values are resolved coherently. requestBody: content: application/json: schema: type: object properties: nodeId: type: string description: >- The ID of the node to create a session on. Optional. If not provided, a random node will be selected. If provided, it takes precedence over country and type. example: this-node-id country: type: string minLength: 2 maxLength: 2 description: >- Two-letter country code used for placement and locale coherence. Defaults to US unless a SOCKS5 URL is supplied with neither language nor timezone, in which case Driver derives the country from the proxy exit. A supplied country must match that resolved exit. Driver otherwise selects a plausible primary language and dominant regional timezone. example: US type: type: string enum: - hosted - hosted_stealth - hosted_privacy default: hosted description: >- Browser execution class. hosted is the native browser, hosted_stealth applies the conservative stealth policy, and hosted_privacy the aggressive one. Defaults to hosted. example: hosted_privacy url: type: string minLength: 1 description: >- Initial URL opened by the browser after launch. Optional. Opened right after launch. example: https://example.com proxyUrl: type: string description: >- Explicit SOCKS5 or SOCKS5H URL for the session. A SOCKS URL supplied without language or timezone is geolocated before launch; Driver derives or validates country and uses the exit timezone. When omitted, the session egresses from Driver's ISP network in the requested country. HTTP proxies are not supported. One of the workspace's dedicated IPs is named here as dedicated://, dedicated://any or dedicated://any~country-XX; Driver resolves it to the address's own SOCKS URL and takes the country and timezone from it. example: socks5://user:pass@proxy.example.com:1080 windowSize: type: string description: >- Outer browser-window size in WIDTHxHEIGHT format. Width must be 320–16384 and height 200–16384. example: 1920x1040 displaySize: type: string description: >- Virtual display size in WIDTHxHEIGHT format. Width must be 320–16384 and height 200–16384. example: 1920x1080 timezone: type: string minLength: 1 maxLength: 128 description: >- IANA timezone for the browser. It must be listed for the selected country. When omitted, Driver selects a dominant regional timezone and, where Driver runs a managed network there, routes the session through that region. example: America/New_York language: type: string minLength: 2 maxLength: 64 description: >- BCP-47 browser language listed for the selected country. US sessions accept only en-US and omit both language launch fields so the browser uses its built-in en-US default. For other countries, Driver deterministically chooses the likely primary language the browser supports. Hosted sessions provision matching TTS when available; otherwise Web Speech is disabled for coherence. example: en-US duration: type: integer minimum: 60 maximum: 3600 description: >- The duration of the browser session in seconds. Optional. Default is 3600 seconds (1 hour). Cannot be greater than 3600 seconds (1 hour). Cannot be less than 60 seconds (1 minute). example: 600 profile: type: object properties: name: type: string example: example-session-1 description: The name of the browser profile. persist: type: boolean example: true description: >- Whether to save the browser profile from this session after its completed. required: - name additionalProperties: false description: >- A named full browser profile. Persistent profiles are kept between sessions. adblock: type: boolean description: >- Whether to enable ad-blocking in the browser session. Optional. Default is false. example: true captchaSolver: type: boolean description: >- Whether to enable the built-in CAPTCHA solver for the session. Optional. Default is false. example: true extensionIds: type: array items: type: string description: >- Internal extension IDs returned by the extensions API. Requires account-level extension access. example: - abc123def456 browserCheck: type: boolean description: >- Whether to run a browser validation check during session creation. Optional. Default is false. example: false note: type: string maxLength: 256 description: >- An optional note to attach to the session. Maximum 256 characters. example: Scraping product pages for client X additionalProperties: false example: type: hosted responses: '200': description: Successfully created a browser session. content: application/json: schema: type: object properties: sessionId: type: string description: >- The session id: an opaque string; do not validate its format. status: type: string enum: - starting - active - completed - error description: The status of the session. servedBy: type: string description: The node ID that is serving this session. createdAt: type: string description: The ISO 8601 timestamp when the session was created. stoppedAt: type: string nullable: true description: >- The ISO 8601 timestamp when the session was stopped, or null if it is still active. cdpUrl: type: string nullable: true format: uri description: >- The URL to access the Chrome DevTools Protocol for this session, or null if not available. note: type: string nullable: true description: >- An optional note attached to the session, or null if not set. required: - sessionId - status - servedBy - createdAt - stoppedAt - cdpUrl - note example: sessionId: example-session-id status: active servedBy: this-node-id createdAt: '2025-11-20T01:51:25.000Z' stoppedAt: null cdpUrl: >- wss://sessions.driver.dev/v1/session/example-session-id/devtools/browser/uuid note: null '400': description: >- Invalid country, language, timezone, dimensions, proxy, type, or incompatible option combination. content: application/json: schema: type: object properties: error: type: string description: Validation error required: - error '401': description: Missing or invalid token. content: application/json: schema: type: object properties: error: type: string description: Error message required: - error '402': description: Insufficient account balance. content: application/json: schema: type: object properties: error: type: string description: Error message required: - error '403': description: Session or account limit reached. content: application/json: schema: type: object properties: error: type: string description: Error message required: - error '429': description: Too many requests. content: application/json: schema: type: object properties: error: type: string description: Error message required: - error '500': description: Failed to create a browser session. content: application/json: schema: type: object properties: error: type: string description: Error message required: - error '503': description: Browser capacity is temporarily unavailable. content: application/json: schema: type: object properties: error: type: string description: Error message code: type: string description: >- Machine-readable cause; present when no browser capacity is available. enum: - browser_capacity_unavailable required: - error headers: Retry-After: description: Seconds to wait before trying again (2). schema: type: integer '504': description: >- A machine was selected but the browser did not become CDP-ready before the startup deadline. content: application/json: schema: type: object properties: error: type: string description: Startup timeout required: - error security: - Bearer: [] components: securitySchemes: Bearer: type: http scheme: bearer description: >- A workspace API key from Settings → API keys in the dashboard (https://app.driver.dev), sent as a bearer token. ````