Skip to main content
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
  • residential_proxy: optional residential proxy location object
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.