Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Sessions

Use the sessions API to create, inspect, and close hosted browser sessions directly.
All routes on this page require x-api-key.

POST /v1/sessions/create

Start a hosted browser session.
Request fields:
  • timeout_seconds: optional session timeout, default 3600, max 7200
  • start_url: optional URL opened before CDP is returned
  • gpu: optional boolean GPU request
  • viewport: optional { width, height } viewport
  • headless: optional boolean browser mode
  • residential_proxy: optional residential proxy location object
  • disable_default_proxy: optional boolean; Kernel only. Disables Kernel's default residential stealth proxy so traffic uses direct egress. Mutually exclusive with residential_proxy.
Prefer start_url over navigating with Playwright immediately after connect. Use residential_proxy for location-sensitive sessions that need traffic to originate from a specific residential proxy country, US state, city, ZIP code, or ASN. See Residential proxy locations for the supported fields and combination rules.
Use disable_default_proxy when the default managed proxy cannot reach the target (for example ERR_TUNNEL_CONNECTION_FAILED). It cannot be combined with residential_proxy. When both start_url and disable_default_proxy are set, Libretto Cloud still opens start_url after switching to direct egress, so clients should treat the start URL as preloaded.
Response fields:
  • success
  • session_id
  • status
  • cdp_url
  • live_view_url
Example:
curl -X POST "https://api.libretto.sh/v1/sessions/create" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "timeout_seconds": 1800
    }
  }'

POST /v1/sessions/get

Inspect a hosted browser session.
Request fields:
  • session_id: session id returned from sessions/create
Response fields:
  • session_id
  • status
  • cdp_url
  • live_view_url
Use this route when sessions/create returned a queued or starting session and you need to poll for the CDP URL or live view URL.

POST /v1/sessions/close

Close a hosted browser session by session id.
Request fields:
  • session_id: session id returned from sessions/create
Response fields:
  • success
  • message
Example:
curl -X POST "https://api.libretto.sh/v1/sessions/close" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "session_id": "<session-id>"
    }
  }'
Libretto Cloud API overview
See the shared request format.
Jobs and Logs
Run workflows and inspect results.
Recordings
Generate recording URLs for jobs and browser sessions.
Deployments and Workflows
Deploy workflows before invoking them.
Powered byHolocron