Sessions

Bash in a browser: its live screen, a voice call, or the whole of Bash inside your app.

Send Authorization: Bearer vk_test_... on every call. Every route of Sessions.

POST/v1/sessions/{session_id}/screenWith the session's token, in control mode: the user takes the wheel or gives it back (action), or says they are driving (input), so Bash waits.

A session's token. On the card: watch. Every call here is a checked sample.

Request3 fields

Path

session_idstringrequiredThe session's id (ses_...).

Type: string

Body

Either { action }

action"take" | "give_back"requiredtake: the person takes the wheel and Bash waits. give_back: Bash drives again.

Type: "take" | "give_back"

Or { input }

inputtruerequiredThe person is typing or clicking now: Bash holds off while these keep coming, each good for a few seconds.

Type: true

Answers 2004 fields

Either { object, by }

object"screen_control"Always screen_control.

Type: "screen_control"

by"user" | "bash"Who drives the screen now: user, the person, or bash.

Type: "user" | "bash"

Or { object, delivered }

object"screen_input"Always screen_input.

Type: "screen_input"

deliveredbooleanWhether Bash's computer heard it; false when it is not connected.

Type: boolean

TypeScript

const session = await vestra.user('traveller-42').watch({ control: true });await session.take();

Python

session = vestra.user("traveller-42").watch(control=True)session.take()

HTTP

# Watch the screen live. Create a session with a screen to watch, and open its url in a browser tab or an iframe.curl "$VESTRA_BASE_URL/v1/sessions" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "user_id": "traveller-42", "screen": "view" }' # Let a person take control. In a session opened with "screen": "control", the person can take over from Bash,# using the session's own token.curl "$VESTRA_BASE_URL/v1/sessions/ses_8h2/screen" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{ "action": "take" }' # Take a screenshot. You get the latest frame of the user's browser as a JPEG.curl "$VESTRA_BASE_URL/v1/users/traveller-42/screenshot" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -o screen.jpg

MCP

{  "method": "tools/call",  "params": {    "name": "watch",    "arguments": { "user": "traveller-42", "control": true }  }}

HTTP

No sample in your language for this route, so here it is over HTTP.

# Watch the screen live. Create a session with a screen to watch, and open its url in a browser tab or an iframe.curl "$VESTRA_BASE_URL/v1/sessions" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "user_id": "traveller-42", "screen": "view" }' # Let a person take control. In a session opened with "screen": "control", the person can take over from Bash,# using the session's own token.curl "$VESTRA_BASE_URL/v1/sessions/ses_8h2/screen" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{ "action": "take" }' # Take a screenshot. You get the latest frame of the user's browser as a JPEG.curl "$VESTRA_BASE_URL/v1/users/traveller-42/screenshot" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -o screen.jpg