---
title: "Create a reusable browser with optional project context"
method: POST
path: "/api/v1/organizations/{organization_id}/browser_sessions"
tags: ["organizations"]
---

# Create a reusable browser with optional project context

`POST /api/v1/organizations/{organization_id}/browser_sessions`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/organizations/{organization_id}/browser_sessions`
- Auth: HTTP bearer

Organization admins can open a standalone browser or select an owned project, environment and credential. Supply an Idempotency-Key header or idempotency_key in the JSON body. The browser runs until explicitly closed or its lifetime expires; replaying creation returns the same browser. Full CDP is available in external control, including with selected project credentials.

## Path parameters

- `organization_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `idempotency_key` string
  - `project_id` string: Optional project slug or public ID.
  - `environment_id` string: Optional ready website environment slug or public ID within the selected project.
  - `credential_id` string: Optional configured credential public ID within the selected project.
  - `url` string: Initial HTTP or HTTPS URL; defaults to the selected environment or project URL, otherwise a blank page.
  - `max_seconds` integer
  - `controller` 'idle' | 'agent' | 'external'

## Response `200`

Success

- object

## Other responses

- `202`: Admitted or previously created browser session
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: The idempotency key belongs to a different request.
- `422`: Invalid context, unavailable credential, exhausted capacity or funding, or paused admission.
- `502`: Bad gateway

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/74298a24e040?raw)