Sessions
Bash in a browser: its live screen, a voice call, or the whole of Bash inside your app.
RoutesOpen one for every field it takes and answers.
POST/v1/sessionsOpen a session for one of your users (user_id), or for the company's own Bash: chat, a screen to watch or drive, a voice call, and what Bash remembers (memory, when your company turned the panel on).
Answers a 15 minute token for the user's browser, a ready page url and the sites allowed to frame it. The token reaches only that user, and only the session's conversation.
Request7 fields
Body
user_idstringYour id for the user this session is for. Absent: your company's own Bash.
- Example
traveller-42
conversation_idstringA conversation of that user's to open it in (conv_...). Absent, with chat or voice: a new conversation on the user's default deployment, then your company's.
- Limits
- At least 1 character.
chatbooleanShow the conversation, so your user can talk to Bash and answer its approvals. Default: false.
- Default
false
screenfalse | "view" | "control"Show Bash's screen: view to watch it, control to also take the wheel. Default: false, no screen.
- Default
false
voiceboolean | objectLet your user talk to Bash by voice: true, or a voice by name. Default: false.
- Default
false
memorybooleanShow what Bash remembers about your user. Your company must turn it on first (PATCH /v1/org, memory_panel: true). Default: false.
- Default
false
driver"bash" | "user"With screen: control, who drives when the screen opens. bash (the default): your user watches and taps Take control. user: your user drives from the first frame the page shows, with no Take control and nothing to give back, for a page that is theirs to use (a sign-in Bash opened for them).
- Type
"bash" | "user"
Answers 20112 fields
idstringThe session (ses_...).
- Example
ses_8h2
object"session"Always session.
- Type
"session"
user_idstring | nullYour id for its user; null on your company's own Bash.
- Type
string | null
conversation_idstring | nullIts conversation (conv_...); null for a screen opened alone.
- Type
string | null
chatbooleanWhether it shows the conversation.
- Type
boolean
screenfalse | "view" | "control"Its screen: view, control, or false for none.
- Type
false | "view" | "control"
voicebooleanWhether your user can talk by voice.
- Type
boolean
memorybooleanWhether it shows what Bash remembers.
- Type
boolean
tokenstringThe session's own token, shown this once and good for 15 minutes. It reaches this user's session and conversation only: messages, events, approvals, files and memory. Never your account, keys or usage.
- Type
string
urlstringThe page to show your user, in a tab or an iframe; it carries the token.
- Type
string
frame_ancestorsstring[]The sites that may frame the page: your company's allowed_embed_origins. Empty: it opens only as a page of its own.
- Type
string[]
expires_atstringWhen the token stops working, 15 minutes after it was made, as an ISO 8601 time.
- Type
string
const session = await vestra.user('traveller-42').embed();session = vestra.user("traveller-42").embed()vestra embed --user traveller-42# Open a session on your server. Do this for the user signed in to your app. It gives them chat, approvals,# the live screen and voice. The response has a url and a token, valid for 15 minutes. Put the url in an# iframe with allow="microphone".curl "$VESTRA_BASE_URL/v1/sessions" \ -H "Authorization: Bearer $VESTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "user_id": "traveller-42", "chat": true, "screen": "view", "voice": true }' # Check the session. See whether it is still open.curl "$VESTRA_BASE_URL/v1/sessions/ses_8h2" \ -H "Authorization: Bearer $VESTRA_API_KEY" # End the session. Its token stops working at once.curl -X DELETE "$VESTRA_BASE_URL/v1/sessions/ses_8h2" \ -H "Authorization: Bearer $VESTRA_API_KEY"{ "method": "tools/call", "params": { "name": "embed", "arguments": { "user": "traveller-42", "memory": true } }}GET/v1/sessions/{session_id}Whether a session is still open, and what it was opened with.
Your key, or the session's own token.
DELETE/v1/sessions/{session_id}End a session now: its token stops working, its streams close and its call hangs up.
Your key, or the session's own token.
GET/v1/sessions/{session_id}/frame-policyWhich sites may show a session's page.
The page asks this itself; you never need to.
GET/v1/sessions/{session_id}/screenWith the session's token: the stream credentials of the user's Bash browser, good for 5 minutes.
For a session opened with a screen. 409 payment_in_progress while the person pays for something in their browser.
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.
GET/v1/users/{user_id}/screenshotThe latest frame of the user's browser, as a JPEG.
409 browser_in_use while a person finishes a sign-in on it (a browser fetch with front open): its page is for them alone. 409 payment_in_progress while the person pays for something in their browser, or just after.
POST/v1/sessions/{session_id}/voiceCalled from the user's browser with the session's token and its WebRTC offer; answers the model's answer.
Audio then flows straight to the voice model, and everything said lands in the session's conversation. For a session opened with voice.