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