Sessions and browser actions

Create a session, inspect its state, and control the hosted agent browser.

Create a session

POSThttps://skill.legba.xyz/api/v1/sessions

Create a routing session or hosted browser.

Request body

Request body
Parameter	Type	Description
`kind`	`string`	proxy for routing; browser for a hosted browser. Default: `browser (CLI)`
`country`	`string`	Requested country code. The client uses US by default. A complete country list is not published with the session contract. Default: `US (CLI)`
`browser`	`string`	agent for automation; chrome, brave, firefox, or tor for a person to operate. Default: `agent (CLI)`

These defaults come from the published client. Send all three fields in direct HTTP requests.

curl --fail-with-body --silent --show-error \
  -X POST "https://skill.legba.xyz/api/v1/sessions" \
  -H "Authorization: Bearer $LEGBA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"browser","country":"US","browser":"agent"}'

Creation returns the session object directly. Use its returned id in subsequent requests. Do not assume the browser is immediately ready.

Fields consumed by the published client

Fields consumed by the published client
Parameter	Type	Description
`id`	`string`	Session identifier used in action and deletion paths.
`kind, browser, state`	`string`	Session kind, browser selection, and current state. No exhaustive state enum is published.
`proxy_url`	`string, when present`	Routing URL for a proxy session. Treat its credentials as sensitive.
`view_url`	`string, when present`	Token-bearing link for a person to view the hosted browser.

The client does not define a complete response schema. Read only the fields your integration needs.

Inspect the current session

GEThttps://skill.legba.xyz/api/v1/sessions/current

Return the account's active session, if any.

curl --fail-with-body --silent --show-error \
  "https://skill.legba.xyz/api/v1/sessions/current" \
  -H "Authorization: Bearer $LEGBA_API_KEY"

The response wraps the result in session. A null value means no session is running. This differs from the direct creation response.

Inspect existing work before starting or ending a session. The published skill describes one active session per account.

Drive the agent browser

Set SESSION_ID from the creation response. These actions require kind: browser and browser: agent.

POSThttps://skill.legba.xyz/api/v1/sessions/{id}/browser/{action}

Send an action to the hosted agent browser.

Actions and JSON bodies

Actions and JSON bodies
Parameter	Type	Description
`navigate`	`{"url":"https://example.com"}`	Navigate to the requested page.
`read`	`{}`	Read page text. The client consumes text, url, and title.
`click`	`{"selector":"","text":"More"}`	Click by CSS selector or visible text. The client sends both fields.
`type`	`{"selector":"#search","text":"example","enter":true}`	Enter text in the selected field. Keep personal authentication steps with the user.
`screenshot`	`{"full_page":false}`	Capture the page. Decode the returned png_base64 field to obtain a PNG.
`wait`	`{"ms":1000}`	Wait for the specified number of milliseconds.

SESSION_ID='PASTE_RETURNED_SESSION_ID'
curl --fail-with-body --silent --show-error \
  -X POST "https://skill.legba.xyz/api/v1/sessions/$SESSION_ID/browser/navigate" \
  -H "Authorization: Bearer $LEGBA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

curl --fail-with-body --silent --show-error \
  -X POST "https://skill.legba.xyz/api/v1/sessions/$SESSION_ID/browser/read" \
  -H "Authorization: Bearer $LEGBA_API_KEY" \
  -H 'Content-Type: application/json' -d '{}'

Browser startup can take about a minute. The CLI retries navigation, reading, and screenshots during startup. It waits 5 seconds between attempts, up to 150 seconds. Direct HTTP clients must handle readiness themselves.

Hand control to a person

POSThttps://skill.legba.xyz/api/v1/sessions/{id}/handoff

Request human control of the existing agent browser.

curl --fail-with-body --silent --show-error \
  -X POST "https://skill.legba.xyz/api/v1/sessions/$SESSION_ID/handoff" \
  -H "Authorization: Bearer $LEGBA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Please complete the sign-in step."}'

Share the returned view_url with the intended person. The response also includes reason. While they hold control, browser writes are refused. Reads remain available.

The CLI polls current state every 5 seconds. It waits while state equals needs_human. There is no separate HTTP wait-for-human endpoint in this client.

POSThttps://skill.legba.xyz/api/v1/sessions/{id}/resume

Resume agent control after the person finishes.

curl --fail-with-body --silent --show-error \
  -X POST "https://skill.legba.xyz/api/v1/sessions/$SESSION_ID/resume" \
  -H "Authorization: Bearer $LEGBA_API_KEY"

Resume sends no request body. Confirm the person has finished before taking control.

End the session

DELETEhttps://skill.legba.xyz/api/v1/sessions/{id}

Close the session and free its capacity.

curl --fail-with-body --silent --show-error \
  -X DELETE "https://skill.legba.xyz/api/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $LEGBA_API_KEY"

Put cleanup in your application's completion and failure paths. End only the session your task owns. See the HTTP lifecycle example.

Request shapes follow the published session client.