> ## 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.

# HTTP requests from the session

Send an arbitrary HTTP request through the session's own Chrome, sometimes called browser-curl. The request carries the browser's cookies, its TLS and HTTP/2 fingerprint, and the session's exit IP, so it is indistinguishable from a request the page itself would make. The common use is replaying a site's own API, the JSON or GraphQL endpoint its front end calls, once a page on that origin has loaded.

The request runs in the session's current tab, so navigate to the site first, then call the site's API with the cookies that page holds.

## POST /v1/session/\{session\_id}/request

Request:

| Field | Type | Default | Meaning |
| - | - | - | - |
| `url` | string, max 8192, required | | `http` or `https` only. Private, loopback and cloud metadata addresses answer 400. |
| `method` | string | `GET` | `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. |
| `headers` | object | `{}` | Caller headers, merged over the browser's own. The browser still sends the headers the fetch standard forbids a caller from setting: `User-Agent`, `Cookie`, `Origin`, `Referer`, `sec-ch-*` and `Sec-Fetch-*`. Set those through the page, not here. |
| `body` | string | none | The request body, as text or base64 (see `bodyEncoding`). Ignored for `GET` and `HEAD`. |
| `bodyEncoding` | string | `text` | `text` or `base64`. Use `base64` for binary bodies. |
| `cacheBypass` | boolean | `false` | Skip the browser's HTTP cache for this request. |
| `followRedirects` | boolean | `true` | Follow redirects. `false` returns the redirect response as the browser reports it. |
| `timeoutMs` | integer | 30000 | Per-request deadline. Bounded by the managed gate, so a very long value is clamped. |
| `maxBytes` | integer | 10 MiB | Response-size cap. A larger response answers 413. The cap cannot exceed 10 MiB. |
| `context` | string | `default` | Run the request in an isolated browser context (its own cookie jar). See [Separate cookie jars](#separate-cookie-jars). |

```bash theme={"dark"}
curl -X POST https://back.tilion.dev/v1/session/sess_3d245e56b86d4bc8ae32095b644117d4/request \
  -H "Authorization: Bearer ph_live_..." -H "Content-Type: application/json" \
  -d '{"method": "POST", "url": "https://www.example.com/graphql",
       "headers": {"content-type": "application/json"},
       "body": "{\"query\":\"{ me { id } }\"}"}'
```

Response (200):

```json theme={"dark"}
{
  "status": 200,
  "headers": { "content-type": "application/json", "...": "..." },
  "body": "{\"data\":{\"me\":{\"id\":\"42\"}}}",
  "bodyEncoding": "text",
  "finalUrl": "https://www.example.com/graphql",
  "fromCache": false,
  "timingMs": 184
}
```

The body comes back as UTF-8 text for textual content types, otherwise base64 with `bodyEncoding: "base64"`.

| Status | `detail.error` | Handling |
| - | - | - |
| 403 | `browser_request_not_enabled` | The session request API is not enabled for this key. It is on for every key on a current release; if you see this, your worker is behind. |
| 409 | `session_driven_by_client` | A main CDP, native Playwright or VNC client holds the session. Disconnect it, or drive the request through that client. |
| 413 | `too_large` | The response exceeded `maxBytes` (or the 10 MiB cap). `detail` includes `size`. |
| 502 | `fetch_failed` | The browser could not complete the request. A same-origin call blocked by the page's Content Security Policy fails this way; see [Pages that block the request](#pages-that-block-the-request). |
| 504 | `request_timeout` | The request passed `timeoutMs`. Retryable. |

## Billing

The request bills the response bytes as egress at the session's exit tier (datacenter, ISP, residential or your own proxy), and the open session bills browser time as usual. There is no per-request fee.

## Parallel requests

Requests on one session run concurrently. Fire many at once and the browser issues them in parallel, as a page's own `fetch()` does. One exception is outside our control: Chrome coalesces several in-flight requests to the exact same URL into one, so a burst of identical URLs still returns one at a time. Give each a distinct URL (a cache-busting query parameter is enough) when you need identical requests to run in parallel.

## Pages that block the request

A page whose Content Security Policy `connect-src` does not include its own origin blocks a same-origin request made from that page, which answers `502 fetch_failed`. Create the session with `bypassCSP: true` to run it outside the page's CSP:

```bash theme={"dark"}
curl -X POST https://back.tilion.dev/v1/session \
  -H "Authorization: Bearer ph_live_..." -H "Content-Type: application/json" \
  -d '{"bypassCSP": true}'
```

The flag is armed before each navigation, so the page loads without CSP enforcement and a later same-origin request is not blocked. It is off by default and scoped to the session. It lifts the page's CSP only; a cross-origin request with no CORS headers is still an opaque response, as in any browser.

## Separate cookie jars

By default every request and navigation in a session shares one cookie jar, so one session serves one signed-in account. Pass a `context` id to run in an isolated browser context with its own jar and storage. Navigate a context to establish its session, then send requests in the same context:

```bash theme={"dark"}
# Sign acctA in, in its own jar
curl -X POST https://back.tilion.dev/v1/session/$SID/navigate \
  -H "Authorization: Bearer ph_live_..." -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com/login", "context": "acctA"}'

# Sign acctB in, in a separate jar
curl -X POST https://back.tilion.dev/v1/session/$SID/navigate \
  -H "Authorization: Bearer ph_live_..." -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com/login", "context": "acctB"}'

# Each request replays with its own context's session
curl -X POST https://back.tilion.dev/v1/session/$SID/request \
  -H "Authorization: Bearer ph_live_..." -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com/api/me", "context": "acctA"}'
```

The `default` context is the session's main tab and runs the full managed anti-bot ladder on navigation. A non-default context is a plain guarded navigation, meant for holding an account rather than clearing a wall. A session holds up to 32 contexts.


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