> ## Documentation Index > Fetch the complete documentation index at: https://sidenet.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Open a browser session > Opens a browser for a person, with no agent: a remote browser running in the EU that they watch and drive through its live view (`GET /v1/browser-sessions/{id}/live-view`). `url` is the page it opens on. `saved_login` (`{ ref, host }`, from `POST /v1/browser-sessions/{id}/keep-sign-in`) signs the first tab in to that website; one saved login is open in one session at a time (409 otherwise), and `url` must then be on that website. `metadata` is kept and returned as given. `thread_id` names the conversation the session is meant for and is kept in `metadata.thread_id`; the session joins a conversation when it is handed to an agent (`POST /v1/browser-sessions/{id}/attach`). The session belongs to the user of the call — a session token's, or the `X-User-Id` sent with an API key — and ends when it is stopped or after ten minutes without activity. An agent's own session is not opened here: an agent whose version has `browser.enabled` opens one on its first browser step. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/browser-sessions openapi: 3.1.0 info: title: Sidenet API version: 1.0.0 description: >- Sidenet HTTP endpoints exposed by the Sidenet Studio. All routes require an api key that can be generated through the studio in studio.sidenet.ai. servers: - url: https://api.sidenet.ai security: - bearerAuth: [] paths: /v1/browser-sessions: post: tags: - Browser summary: Open a browser session description: >- Opens a browser for a person, with no agent: a remote browser running in the EU that they watch and drive through its live view (`GET /v1/browser-sessions/{id}/live-view`). `url` is the page it opens on. `saved_login` (`{ ref, host }`, from `POST /v1/browser-sessions/{id}/keep-sign-in`) signs the first tab in to that website; one saved login is open in one session at a time (409 otherwise), and `url` must then be on that website. `metadata` is kept and returned as given. `thread_id` names the conversation the session is meant for and is kept in `metadata.thread_id`; the session joins a conversation when it is handed to an agent (`POST /v1/browser-sessions/{id}/attach`). The session belongs to the user of the call — a session token's, or the `X-User-Id` sent with an API key — and ends when it is stopped or after ten minutes without activity. An agent's own session is not opened here: an agent whose version has `browser.enabled` opens one on its first browser step. parameters: [] requestBody: required: false content: application/json: schema: type: object properties: url: type: string example: https://admin.booking.com description: The page to open. thread_id: type: string description: >- The conversation this session is meant for (kept in `metadata.thread_id`). saved_login: type: object nullable: true properties: ref: type: string host: type: string description: A saved login to sign the first tab in with. viewport: type: object properties: width: type: integer height: type: integer description: The size of the browser window (default 1280 × 800). metadata: type: object description: Anything the caller wants back with the session. example: url: https://admin.booking.com metadata: property_id: 5b0f… object: kind: reservation id: … responses: '201': description: The session content: application/json: schema: type: object properties: id: type: string description: >- The session id. Sidenet's own: it is what every route here takes. status: type: string enum: - live - waiting_person - waiting_approval - done - stopped - failed description: >- `waiting_person`: the agent waits for a person (a take-over, a pause, a code or a sign-in it asked for). `waiting_approval`: something it wants to send waits for a yes. The last three are ended sessions. control: type: string enum: - person - agent description: Who may act on the page now. drivers: type: array items: type: object properties: kind: type: string enum: - person - agent user_id: type: string agent_id: type: string name: type: string description: Who works in the session. thread_id: type: string nullable: true description: >- The conversation the session works for; null for a session a person opened with no agent. run_id: type: string nullable: true description: >- The request of the agent turn using it (its id in the requests list). host: type: string nullable: true description: The website of the active tab. saved_login: type: object nullable: true properties: ref: type: string host: type: string description: The saved login the session is signed in with, if any. tabs: type: array items: type: object properties: index: type: integer url: type: string title: type: string active: type: boolean agent: type: boolean description: The tab the agent works in. steps: type: array items: type: object properties: 'n': type: integer of: type: integer nullable: true sentence: type: string description: What the agent did, in plain words. tab: type: integer at: type: string format: date-time description: The agent's steps, oldest first (the last 200). needs_person: type: string nullable: true enum: - code - captcha - sign_in - null description: What the agent asked a person for. pending_submit: type: object nullable: true properties: description: type: string host: type: string asked_at: type: string format: date-time decision_ref: type: string nullable: true description: What waits for a yes before it is sent. end: type: object nullable: true properties: outcome: type: string enum: - done - stopped - failed sentence: type: string metadata: type: object description: Kept and returned as given at creation. started_at: type: string format: date-time ended_at: type: string format: date-time nullable: true updated_at: type: string format: date-time example: id: bs_3f9a1c0e5b7d2a4c6e8f0b1d status: live control: person drivers: - kind: person user_id: user_42 name: Person thread_id: null run_id: null host: admin.booking.com saved_login: ref: sl_0c9e4b7a1d3f5a6b8c2e4d6f host: admin.booking.com tabs: - index: 0 url: https://admin.booking.com/hotel/hoteladmin/ title: Booking.com extranet active: true agent: true steps: [] needs_person: null pending_submit: null end: null metadata: property_id: 5b0f… started_at: '2026-11-12T10:00:00.000Z' ended_at: null updated_at: '2026-11-12T10:00:03.000Z' '400': description: >- Not a web address, an unknown field, or `url` outside the saved login's website '404': description: No saved login with that reference '409': description: The saved login is open in another session '502': description: The browser could not be opened '503': description: The browser is not set up on this platform security: - bearerAuth: [] - sessionToken: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Organization API key, generated in studio.sidenet.ai. Backend only — never in a browser. sessionToken: type: http scheme: bearer description: >- Session token (`snat_…`) minted by POST /v1/token. Carries the organization and the end user; safe in a browser. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.