> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilion.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a browser

> Configure a session's lifetime, region, and proxy exit.

`POST /v1/session` creates an isolated Chrome instance. An empty JSON body uses the defaults. Set `TILION_API_KEY` before running an example.

```python Python theme={"dark"}
import os
import uuid
import requests

response = requests.post(
    "https://back.tilion.dev/v1/session",
    headers={
        "Authorization": f"Bearer {os.environ['TILION_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"ttl": 600, "idle_timeout": 120}, timeout=200,
)
response.raise_for_status()
print(response.json()["session_id"])
```

```javascript Node.js theme={"dark"}
import { randomUUID } from "node:crypto";

const response = await fetch("https://back.tilion.dev/v1/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TILION_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({ ttl: 600, idle_timeout: 120 }),
  signal: AbortSignal.timeout(200_000),
});
if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).session_id);
```

```bash curl theme={"dark"}
curl --fail-with-body https://back.tilion.dev/v1/session \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ttl": 600, "idle_timeout": 120}'
```

The response includes `session_id`, `state`, `connect_url`, and `playwright_url`. These examples leave the browser running. Export its ID for the other guides:

```bash theme={"dark"}
export TILION_SESSION_ID="sess_..."
```

## Configure the session

| Field | Behavior |
| - | - |
| `ttl` | Maximum session lifetime in seconds, subject to your plan's limit. |
| `idle_timeout` | Ends an inactive session. Browser actions and CDP activity reset this timer. Reading session metadata does not. |
| `region` | Browser region from `GET /v1/regions`. |
| `residential` | Enables a residential exit, billed as premium egress. |
| `geo` | Requests an exit location when residential routing is enabled. |
| `full_browser` | Requests a visible Chrome desktop for VNC. |

To request a US residential exit, use this creation body:

```json theme={"dark"}
{"residential": true, "geo": {"country": "us"}}
```

Check `geo_applied` and `geo_unsupported` in the response to confirm which location settings were applied.

To route browser traffic through your own provider, see [Use your own proxy](https://docs.tilion.dev/guides/custom-proxy.md). Custom proxies use a separate `proxy` object and cannot be combined with `geo` or Tilion exit-selection fields.

> [!NOTE]
>
> For retries, reuse the original `Idempotency-Key` value. Generate a new value for each new session. The server retains this association for about an hour.

## Close the browser

```bash theme={"dark"}
curl --fail-with-body -X DELETE \
  "https://back.tilion.dev/v1/session/$TILION_SESSION_ID" \
  -H "Authorization: Bearer $TILION_API_KEY"
```

Deletion returns `204`. See the [session reference](https://docs.tilion.dev/sessions/sessions.md) for all creation fields and the [quickstart](https://docs.tilion.dev/guides/quickstart.md) for automatic cleanup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.