> ## 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 Browser Session

> Create a new hosted browser session.



## 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 creating Driver browser sessions and scraping pages.
  contact:
    name: Contact Us
    email: hello@driver.dev
    url: https://driver.dev
servers:
  - url: https://api.driver.dev
security: []
externalDocs:
  description: Learn more
  url: https://docs.driver.dev
paths:
  /v1/browser/session:
    post:
      summary: Create Browser Session
      description: Create a new hosted browser session.
      operationId: createBrowserSession
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - hosted
                  description: Use hosted Driver infrastructure for the session.
                  example: hosted
                country:
                  type: string
                  minLength: 2
                  maxLength: 2
                  description: >-
                    Start a session in a specific country using its 2-letter ISO
                    code. Optional.
                  example: US
                nodeId:
                  type: string
                  description: >-
                    Create the hosted session on a specific previously used
                    hosted node. Optional. Overrides country.
                  example: node-id-from-servedBy
                duration:
                  type: integer
                  minimum: 60
                  exclusiveMinimum: true
                  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
                windowSize:
                  type: string
                  description: >-
                    The window size for the browser session in the format
                    WIDTHxHEIGHT (e.g., 1920x1080). Optional.
                  example: 1920x1080
                proxyUrl:
                  type: string
                  description: >-
                    SOCKS5 proxy URL for the session. Optional. Requires hosted
                    sessions and cannot be used with nodeId.
                  example: socks5://user:pass@proxy.example.com:1080
                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 browser state for reuse after the
                        session stops.
                  required:
                    - name
                  description: The browser profile to use for the session. Optional.
                fast:
                  type: boolean
                  description: >-
                    Attempt faster startup when the request is eligible.
                    Optional.
                  example: true
                captchaSolver:
                  type: boolean
                  description: >-
                    Enable the built-in CAPTCHA solver for the session.
                    Optional. Default is false.
                  example: true
                extensionIds:
                  type: array
                  items:
                    type: string
                  description: >-
                    Chrome extension IDs to load into the browser session.
                    Optional. Requires extension access for your account.
                  example:
                    - abc123def456
        required: false
      responses:
        '200':
          description: Successfully created a browser session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    description: The ID of the created browser session.
                  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
        '401':
          description: Missing or invalid token.
          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
      security:
        - Bearer: []
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: Your Driver API key. Get one at https://app.driver.dev

````