> ## Documentation Index > Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a Session ## OpenAPI ````yaml post /v1/sessions openapi: 3.0.0 info: title: Browserbase API description: Browserbase API for 3rd party developers version: v1 servers: - url: https://api.browserbase.com description: Public endpoint variables: {} security: - BrowserbaseAuth: [] tags: [] paths: /v1/sessions: post: summary: Create a Session operationId: Sessions_create requestBody: content: application/json: schema: type: object properties: projectId: description: >- The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key. type: string extensionId: description: >- The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension). type: string browserSettings: type: object properties: context: type: object properties: id: description: The Context ID. type: string persist: description: >- Whether or not to persist the context after browsing. Defaults to `false`. type: boolean required: - id extensionId: description: >- The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension). type: string viewport: type: object properties: width: description: The width of the browser. type: integer height: description: The height of the browser. type: integer blockAds: description: >- Enable or disable ad blocking in the browser. Defaults to `false`. type: boolean solveCaptchas: description: >- Enable or disable captcha solving in the browser. Defaults to `true`. type: boolean recordSession: description: Enable or disable session recording. Defaults to `true`. type: boolean logSession: description: Enable or disable session logging. Defaults to `true`. type: boolean advancedStealth: description: Advanced Browser Stealth Mode type: boolean verified: description: Verified Browser Mode type: boolean captchaImageSelector: description: >- Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving) type: string captchaInputSelector: description: >- Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving) type: string os: description: >- Operating system for stealth mode. Valid values: windows, mac, linux, mobile, tablet type: string enum: - windows - mac - linux - mobile - tablet ignoreCertificateErrors: description: >- Enable or disable ignoring of certificate errors in the browser. Defaults to `true`. type: boolean timeout: description: >- Duration in seconds after which the session will automatically end. Defaults to the Project's `defaultTimeout`. type: integer maximum: 21600 minimum: 60 keepAlive: description: >- Set to true to keep the session alive even after disconnections. Available on the Hobby Plan and above. type: boolean proxies: description: >- Proxy configuration. Can be true for default proxy, or an array of proxy configurations. anyOf: - type: array items: anyOf: - $ref: '#/components/schemas/BrowserbaseProxyConfig' - $ref: '#/components/schemas/ExternalProxyConfig' - $ref: '#/components/schemas/NoneProxyConfig' - type: boolean region: description: The region where the Session should run. type: string default: us-west-2 enum: - us-west-2 - us-east-1 - eu-central-1 - ap-southeast-1 userMetadata: description: >- Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata). type: object additionalProperties: true properties: {} responses: '201': description: >- The request has succeeded and a new resource has been created as a result. content: application/json: schema: allOf: - $ref: '#/components/schemas/Session' - type: object properties: connectUrl: description: WebSocket URL to connect to the Session. type: string format: uri seleniumRemoteUrl: description: HTTP URL to connect to the Session. type: string format: uri signingKey: description: >- Signing key to use when connecting to the Session via HTTP. type: string required: - connectUrl - seleniumRemoteUrl - signingKey x-codeSamples: - lang: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/sessions \ --header 'Content-Type: application/json' \ --header 'X-BB-API-Key: ' \ --data '{}' - lang: JavaScript source: |- fetch('https://api.browserbase.com/v1/sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-BB-API-Key': '' }, body: JSON.stringify({}) }) - lang: Python source: >- import requests url = "https://api.browserbase.com/v1/sessions" payload = {} headers = { "X-BB-API-Key": "", "Content-Type": "application/json" } response = requests.request("POST", url, json=payload, headers=headers) print(response.text) - lang: PHP source: |- "https://api.browserbase.com/v1/sessions", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => "{}", CURLOPT_HTTPHEADER => [ "Content-Type: application/json", "X-BB-API-Key: " ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.browserbase.com/v1/sessions\"\n\n\tpayload := strings.NewReader(\"{}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"X-BB-API-Key\", \"\")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: Java source: >- HttpResponse response = Unirest.post("https://api.browserbase.com/v1/sessions") .header("X-BB-API-Key", "") .header("Content-Type", "application/json") .body("{}") .asString(); components: schemas: BrowserbaseProxyConfig: type: object properties: type: description: >- Type of proxy. Always use 'browserbase' for the Browserbase managed proxy network. type: string enum: - browserbase geolocation: description: Geographic location for the proxy. Optional. type: object properties: city: description: >- Name of the city. Use spaces for multi-word city names. Optional. type: string state: description: >- US state code (2 characters). Must also specify US as the country. Optional. type: string maxLength: 2 minLength: 2 country: description: Country code in ISO 3166-1 alpha-2 format type: string maxLength: 2 minLength: 2 required: - country domainPattern: description: >- Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional. type: string required: - type ExternalProxyConfig: type: object properties: type: description: Type of proxy. Always 'external' for this config. type: string enum: - external server: description: Server URL for external proxy. Required. type: string domainPattern: description: >- Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional. type: string username: description: Username for external proxy authentication. Optional. type: string password: description: Password for external proxy authentication. Optional. type: string required: - type - server NoneProxyConfig: type: object properties: type: description: Type of proxy. Always 'none' for this config. type: string enum: - none domainPattern: description: >- Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional. type: string required: - type Session: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time projectId: description: The Project ID linked to the Session. type: string startedAt: type: string format: date-time endedAt: type: string format: date-time expiresAt: type: string format: date-time status: type: string enum: - PENDING - RUNNING - ERROR - TIMED_OUT - COMPLETED proxyBytes: description: >- Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips) type: integer keepAlive: description: >- Indicates if the Session was created to be kept alive upon disconnections type: boolean contextId: description: Optional. The Context linked to the Session. type: string region: description: The region where the Session is running. type: string enum: - us-west-2 - us-east-1 - eu-central-1 - ap-southeast-1 userMetadata: description: >- Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata). type: object additionalProperties: true properties: {} required: - id - createdAt - updatedAt - projectId - status - proxyBytes - keepAlive - region - startedAt - expiresAt securitySchemes: BrowserbaseAuth: type: apiKey in: header name: X-BB-API-Key description: Your [Browserbase API Key](https://www.browserbase.com/settings). ````