> ## Documentation Index > Fetch the complete documentation index at: https://docs.notte.cc/llms.txt > Use this file to discover all available pages before exploring further. # Session Start ## OpenAPI ````yaml https://api.notte.cc/openapi.json post /sessions/start openapi: 3.1.0 info: title: Notte API description: >- Notte API is a REST API that allows you to interact with Notte. It is used to create cloud browser sessions, scrape webpages, and run web ai agents to act on your behalf on the internet. version: 1.4.40 x-logo: url: https://www.notte.cc/images/logo/logo-white.png servers: [] security: [] tags: - name: agents description: Web AI agents (start, stop, status, replay, etc.) - name: sessions description: Session management (start, stop, status, etc.) - name: debug description: Session debugging tools (replay,logs, recording, etc.) - name: page description: Page operations withing a session (observe, step, scrape, etc.) - name: storage description: File storage interface (upload, download, list, etc.) - name: network description: Network requests/responses withing a session (intercept, etc.) - name: vaults description: >- Vault & Credentials management (create/delete vaults, create/delete credentials, etc.) - name: personas description: Persona management (create, delete, list emails, list sms, etc.) - name: scrape description: >- Webpage scraping (scrape, screenshot, etc.) with automatic session management. - name: health description: Health check endpoint. - name: usage description: Usage logs (usage, logs, etc.) - name: functions description: Functions management (create, delete, list, etc.) paths: /sessions/start: post: tags: - sessions summary: Session Start operationId: session_start parameters: - name: x-notte-request-origin in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Notte-Request-Origin - name: x-notte-sdk-version in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Notte-Sdk-Version requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApiSessionStartRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SessionResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - OAuth2PasswordBearer: [] x-codeSamples: - lang: Python source: |- from notte_sdk import NotteClient, actions notte = NotteClient() # the simple way: create a session that gets stopped automatically with notte.Session() as session: _ = session.execute( actions.Goto(url="https://www.google.com") ) # for more control, start it manually session = notte.Session() session.start() label: python - lang: JavaScript source: |- import { NotteClient } from "notte-sdk"; const notte = new NotteClient(); // the simple way: create a session that gets stopped automatically await notte.Session().use(async (session) => { await session.execute({ type: "goto", url: "https://www.google.com", }); }); // for more control, start it manually const session = notte.Session(); await session.start(); label: node - lang: Curl source: |- curl -X POST "https://api.notte.cc/sessions/start" \ -H "Authorization: Bearer $NOTTE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "headless": true, "solve_captchas": false, "timeout_minutes": 3, "proxies": false, "browser_type": "chromium", "user_agent": null, "chrome_args": null, "viewport_width": null, "viewport_height": null, "cdp_url": null, "use_file_storage": false, "screenshot_type": "last_action" }' label: curl components: schemas: ApiSessionStartRequest: properties: headless: type: boolean title: Headless description: Whether to run the session in headless mode. default: true solve_captchas: type: boolean title: Solve Captchas description: Whether to try to automatically solve captchas default: false max_duration_minutes: type: integer maximum: 1440 exclusiveMinimum: 0 title: Max Duration Minutes description: >- Maximum session lifetime in minutes (absolute maximum, not affected by activity). default: 15 idle_timeout_minutes: type: integer maximum: 15 exclusiveMinimum: 0 title: Idle Timeout Minutes description: >- Idle timeout in minutes. Session closes after this period of inactivity (resets on each operation). default: 3 proxies: anyOf: - items: oneOf: - $ref: '#/components/schemas/NotteProxy' - $ref: '#/components/schemas/ExternalProxy' - $ref: '#/components/schemas/TailnetProxy' discriminator: propertyName: type mapping: external: $ref: '#/components/schemas/ExternalProxy' notte: $ref: '#/components/schemas/NotteProxy' tailnet: $ref: '#/components/schemas/TailnetProxy' type: array - type: boolean title: Proxies description: >- List of custom proxies to use for the session. If True, the default proxies will be used. default: false browser_type: type: string enum: - chromium - chrome - firefox - chrome-nightly - chrome-turbo title: Browser Type description: The browser type to use. Can be chromium, chrome or firefox. default: chromium user_agent: anyOf: - type: string - type: 'null' title: User Agent description: The user agent to use for the session chrome_args: anyOf: - items: type: string type: array - type: 'null' title: Chrome Args description: Overwrite the chrome instance arguments viewport_width: anyOf: - type: integer - type: 'null' title: Viewport Width description: The width of the viewport viewport_height: anyOf: - type: integer - type: 'null' title: Viewport Height description: The height of the viewport aspect_ratio: anyOf: - type: string enum: - '5:4' - '16:9' - type: 'null' title: Aspect Ratio description: >- Viewport shape preset. When set, the backend fits the largest rectangle of this aspect ratio inside the sampled available screen area. Cannot be combined with explicit viewport_width/viewport_height. cdp_url: anyOf: - type: string - type: 'null' title: Cdp Url description: The CDP URL of another remote session provider. use_file_storage: type: boolean title: Use File Storage description: Whether FileStorage should be attached to the session. default: true screenshot_type: type: string enum: - raw - full - last_action title: Screenshot Type description: The type of screenshot to use for the session. default: last_action profile: anyOf: - $ref: '#/components/schemas/SessionProfile' - type: 'null' description: Browser profile configuration for state persistence web_bot_auth: type: boolean title: Web Bot Auth description: Whether to use web bot authentication. default: false extra_http_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Extra Http Headers description: Extra HTTP headers to be sent with every request. vault_id: anyOf: - type: string - type: 'null' title: Vault Id description: The vault to use for the session additionalProperties: false type: object title: ApiSessionStartRequest SessionResponse: properties: session_id: type: string title: Session Id description: >- The ID of the session (created or existing). Use this ID to interact with the session for the next operation. idle_timeout_minutes: type: integer title: Idle Timeout Minutes description: >- Session idle timeout in minutes. Will timeout if now() > last access time + idle_timeout_minutes max_duration_minutes: type: integer title: Max Duration Minutes description: >- Session max duration in minutes. Will timeout if now() > creation time + max_duration_minutes default: 15 created_at: type: string format: date-time title: Created At description: Session creation time closed_at: anyOf: - type: string format: date-time - type: 'null' title: Closed At description: Session closing time last_accessed_at: type: string format: date-time title: Last Accessed At description: Last access time duration: type: string format: duration title: Duration description: Session duration status: type: string enum: - active - closed - error - timed_out title: Status description: Session status steps: items: additionalProperties: true type: object type: array title: Steps description: Steps of the session error: anyOf: - type: string - type: 'null' title: Error description: Error message if the operation failed to complete proxies: type: boolean title: Proxies description: >- Whether proxies were used for the session. True if any proxy was applied during session creation. default: false browser_type: type: string enum: - chromium - chrome - firefox - chrome-nightly - chrome-turbo title: Browser Type default: chromium use_file_storage: type: boolean title: Use File Storage description: Whether FileStorage was attached to the session. default: false network_request_bytes: type: integer title: Network Request Bytes description: Total byte usage for network requests. default: 0 network_response_bytes: type: integer title: Network Response Bytes description: Total byte usage for network responses. default: 0 user_agent: anyOf: - type: string - type: 'null' title: User Agent description: The user agent to use for the session viewport_width: anyOf: - type: integer - type: 'null' title: Viewport Width description: The width of the viewport viewport_height: anyOf: - type: integer - type: 'null' title: Viewport Height description: The height of the viewport headless: type: boolean title: Headless description: Whether to run the session in headless mode. default: true solve_captchas: anyOf: - type: boolean - type: 'null' title: Solve Captchas description: Whether to solve captchas. cdp_url: anyOf: - type: string - type: 'null' title: Cdp Url description: The URL to connect to the CDP server. viewer_url: anyOf: - type: string - type: 'null' title: Viewer Url description: The remote session viewer URL. web_bot_auth: type: boolean title: Web Bot Auth description: Whether to use web bot authentication. default: false timeout_minutes: type: integer title: Timeout Minutes deprecated: true readOnly: true type: object required: - session_id - idle_timeout_minutes - created_at - last_accessed_at - status - timeout_minutes title: SessionResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError NotteProxy: properties: type: type: string const: notte title: Type default: notte id: anyOf: - type: string - type: 'null' title: Id country: anyOf: - $ref: '#/components/schemas/ProxyGeolocationCountry' - type: 'null' additionalProperties: false type: object title: NotteProxy ExternalProxy: properties: type: type: string const: external title: Type default: external server: type: string title: Server username: anyOf: - type: string - type: 'null' title: Username password: anyOf: - type: string - type: 'null' title: Password bypass: anyOf: - type: string - type: 'null' title: Bypass additionalProperties: false type: object required: - server title: ExternalProxy TailnetProxy: properties: type: type: string const: tailnet title: Type default: tailnet oauth_client_id: type: string title: Oauth Client Id oauth_client_secret: anyOf: - type: string - type: 'null' title: Oauth Client Secret additionalProperties: false type: object required: - oauth_client_id title: TailnetProxy SessionProfile: properties: id: type: string title: Id description: Profile ID to use for this session persist: type: boolean title: Persist description: Whether to save browser state to profile on session close default: false additionalProperties: false type: object required: - id title: SessionProfile ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ProxyGeolocationCountry: type: string enum: - ad - ae - af - ag - ai - al - am - ao - ar - at - au - aw - az - ba - bb - bd - be - bf - bg - bh - bi - bj - bm - bn - bo - bq - br - bs - bt - bw - by - bz - ca - cd - cg - ch - ci - cl - cm - cn - co - cr - cu - cv - cw - cy - cz - de - dj - dk - dm - do - dz - ec - ee - eg - es - et - fi - fj - fr - ga - gb - gd - ge - gf - gg - gh - gi - gm - gn - gp - gq - gr - gt - gu - gw - gy - hk - hn - hr - ht - hu - id - ie - il - im - in - iq - ir - is - it - je - jm - jo - jp - ke - kg - kh - kn - kr - kw - ky - kz - la - lb - lc - lk - lr - ls - lt - lu - lv - ly - ma - md - me - mf - mg - mk - ml - mm - mn - mo - mq - mr - mt - mu - mv - mw - mx - my - mz - na - nc - ne - ng - ni - nl - 'no' - np - nz - om - pa - pe - pf - pg - ph - pk - pl - pr - ps - pt - py - qa - re - ro - rs - ru - rw - sa - sc - sd - se - sg - si - sk - sl - sm - sn - so - sr - ss - st - sv - sx - sy - sz - tc - tg - th - tj - tm - tn - tr - tt - tw - tz - ua - ug - us - uy - uz - vc - ve - vg - vi - vn - ye - za - zm - zw title: ProxyGeolocationCountry securitySchemes: OAuth2PasswordBearer: type: oauth2 flows: password: scopes: {} tokenUrl: token ````