SDKs and CLI

Your company's door to Bash: your key from VESTRA_API_KEY, the base URL from VESTRA_BASE_URL, and your tools.

One of your users' Bash, by your own id for them. They are created the first time you act for them.

Bash interviews you and drafts vestra.yaml: iterate draft.questions(), then await draft.yaml().

The closing words of an interview run elsewhere (over MCP, say), by its deployment: as Draft.closing() gives them.

Apply vestra.yaml: a new version, promoted in the key's mode once its tests pass; .rollback(name).

Put an earlier version back live, at once: the one before, or { version }. Needs a live key.

Run vestra.yaml's tests and wait for the verdict: an edited file is applied first as a version of its own, not promoted (a live key applies nothing), and the summary's note says so; .generate(name) drafts more.

A run already started, followed to its verdict: the one a deploy started (its tests.id), which promotes when it passes, so the summary says what it promoted.

Scenarios drafted from the deployment's instructions, as vestra.yaml's tests: entries; from version, or else the version test mode runs.

A job in plain words. Returns a Run at once: iterate its events, stop() it, read text(), output() and cost().

Many users at once: a batch, one conversation each.

A job Bash runs on a schedule in plain words (every), as cron (schedule), or whenever your system calls (on: 'call').

A user's routines (or your company's own Bash's), with when each runs next.

One routine: what it asks, when it runs next, and when it last ran.

Change what it asks, when it runs, its filters or its name.

Stop its runs, and keep it.

Start its runs again.

Delete it: it never runs again.

Run it once, now.

Fire a routine that runs on a call, with your system's payload.

Its runs, newest first, each with the conversation it ran in.

Answer what Bash waits on, by its id, with the body its type takes: approve, answers, done, or your tool's output.

What Bash waits on: every user's, or one user's with user.

One interaction: what Bash waits on, its questions, its nonce, and how it settled.

Withdraw it: the task carries on without that action.

Its screen, live: watch only, or { control: true } so a person can take the wheel.

A voice call with Bash: open session.url and the page joins the call.

A conversation's events (conv_…), or one task's (task_…), as they happen: its kept rows first, then live. Stop by breaking out.

Every step of a task, afterwards, with tokens and cost per turn.

Send events to your server, signed. The signing secret is in the answer, shown once.

The record: the events your webhooks get, newest first.

The record from now on, oldest first, read every interval_ms.

A webhook handler: checks the signature, answers your tools' calls itself, and hands every other event to fn.

One webhook checked by hand, from its raw body and its Vestra-Signature header.

A user's files (or your company's own Bash's), one task's outputs, or one conversation's.

Its details, with a download link good for a short while.

Its bytes.

Hand Bash a file (10 MB at most) for this user, or for your company's own Bash.

Delete a file.

A sign-in link for one app: send it to your user, or open it yourself for your company's own Bash.

The apps a user has connected (or your company's own Bash has), with each one's status.

One connected app and its status.

Disconnect the app: Bash can no longer use it for this user.

Every app your users may connect, after your allowlist.

A written profile, and each memory, newest first.

Ask what Bash remembers: { found, text }.

Tell Bash a fact once.

Forget one memory.

Forget everything about this user, or your company's own Bash.

Bash inside your app: chat, approvals, the live screen and voice. memory: true adds the memory panel (PATCH /v1/org { memory_panel: true } first).

Your users, with this month's spend.

Set a user up before first use (a name, a default deployment, a cap). Safe to repeat.

What was spent between two dates, grouped by day, user, deployment, conversation, task, model or category.

The receipt: the charges behind one conversation or one task.

Set the day and month caps and the alert thresholds.

The caps and alert thresholds, with what is spent against each.

Your keys: names, modes, scopes and the last four characters, never the secret.

A new key in this key's mode (a test key makes test keys). Its secret is shown once.

Replace a key; the old one keeps working for grace_seconds (a day by default).

Revoke a key: it stops working at once.

Your company, and the key in use.

Store it, write-only: your company's, or one user's own. Storing it again replaces it.

Names only, never values.

Delete a secret: your company's, or one user's own.

A session's state: open or ended, and what it shows.

End a session now: its token stops working at once.

Read any route by its path, typed from the contract: { data, error, response }.

Write to any route by its path, typed from the contract: { data, error, response }.

Put to any route by its path, typed from the contract: { data, error, response }.

Change through any route by its path, typed from the contract: { data, error, response }.

Delete through any route by its path, typed from the contract: { data, error, response }.

Their profile, their spend this month and what they may still spend.

Change their name, email, locale, time zone, default deployment, cap or metadata, or switch them off.

Everything held for them, as one download link (a data-rights request).

Erase their Bash, computer, memory and files. It runs as a job; user.deleted says when it is done.

Wake their computer now, so their next task starts at once.

What their computer's screen shows now, as a JPEG.

The conversation (conv_…), once the server has named it.

How it ended: completed, failed or stopped. Null while it runs, or when it failed before it started.

Stop the reply and every piece of work the conversation started.

The answer, once the run has ended, trimmed: when Bash went to work, the work's answer, its final reply (task.completed's answer; from an older server without one, its summary, which joins every step's words); otherwise, and when the work ended with no final reply, the reply's answer, its final words (message.completed's answer; from an older server without one, the whole reply). Throws the turn's error when the turn failed (as output() does), so a failed turn never reads as an empty answer.

The result you asked for with output. Throws the turn's error when the turn failed or the answer did not fit it.

What this run cost, read once it has ended.

Carry on in the same conversation, once this run has ended, so the next message never meets a turn still running.

Waits up to ms for the answers this run is still sending to your tools' calls (each function's result, then the write that carries it), and returns the calls whose answers had not landed by then: Bash may still be waiting on those, so answer them with vestra.answer. The run never waits on its own answers, so await this before your process exits, on every way out, an error or an abort included.

The batch as the server answered its creation.

bat_…, once the batch exists.

The batch now: its status and how many items are queued, running, done or failed.

Every item, with its conversation, task and result, page by page.

Start no new item; the running ones finish.

Until the batch is no longer running; each read rides out a lost connection (a redeploy) for up to 5 minutes.

Open this in a tab or an iframe: chat, approvals, the screen and voice, as the session was opened.

The session's own token: it reaches this user (and this conversation) only, and never money.

The whole answer of POST /v1/sessions.

End it now: its token stops working at once, and its streams and calls close.

Take the wheel (a session opened with control).

Give the wheel back to Bash.

The screen's stream credentials, made per call, good for 5 minutes.

Bash's questions, one reply at a time. Answer each to go on; it ends once the draft is saved, or at a question left unanswered. An interview that says nothing for timeout_ms (INTERVIEW_WAIT_MS) ends with interview_failed.

Whether the interview has saved its draft (the draft moved past version 1).

vestra.yaml, as the interview drafted it (?format=yaml), once the draft is saved.

The interview's closing words, once its draft is saved: what the draft sets Bash up to do, the tools your code answers, the spending cap per task, the starter tests, and the next steps. Show them where init ends. Null when the draft version carries none.

The fetch every call goes through: yours from the options, or the global one.

The fetch every call goes through: yours from the options, or the global one.

The key's mode, from its prefix: a test key sees test users, test deployments and test money.

A route's whole URL, with its query.

A call whose answer is JSON, or nothing for a 204.

A GET whose answer is JSON, read on through a lost connection (Reconnects): what a wait polls.

A write whose answer is JSON, sent under one Idempotency-Key and sent again under it through a lost connection (Reconnects): a 503 while the server checks your key never ends it, and the server takes the write once.

A call whose answer the caller reads (a stream of events, or a file). Throws VestraError unless it is 2xx.

One call as every call is made (vestra.raw's too), with the key, the user agent and the tries above: its answer as it came, 2xx or not.

A non-2xx answer as a VestraError, from its /v1 error body when it has one.

Why a failed call is the connection lost: a redeploy's 502, 503 or 504, a transport failure, or a first try that died mid-call and left its key in progress (409 idempotency_in_progress: the server says retry in a moment, with the same key). Null for an answer to act on, an abort, or a bug.

A stream row, read for one user's conversation, as the one shape.

A webhook's body (or an item of GET /v1/events) as the one shape.

Your function's answer as the answer route takes it: { output } or { error }.

A tool your code answers: its name, what it does, its input in plain words or JSON Schema, and the function that runs it. It waits for your user's yes unless you mark it read_only (a lookup) or run_without_asking.

A shape in plain words, as vestra.yaml's tools write their input, as JSON Schema: each field's type is string, number, integer, boolean or object, with [] for a list and ? for optional, and a nested map for a nested object: { pnr: 'string', seats: 'integer?', legs: 'string[]', trip: { from: 'string' } }. An input with type: 'object', properties or $schema is JSON Schema and is kept as it is.

A deployment name from the start of a description: lowercase words and dashes, at most 63.

The closing words in plain words: the model wrote the summary and the tool descriptions, and the next steps name them. The server cleans them where it writes them; this is the second layer, where the developer reads them.

A test run's status in plain words: an error says why, from its error_code, and a run a restart interrupted says so: resumed, or interrupted once too often.

sha256 over each file's path, its byte length and its bytes (UTF-8), in path order: the server's Skill.sha256.

Split an SSE buffer into complete frames and the unfinished rest. Comment lines are skipped.

Follow a /v1 event stream. A dropped or closed connection, or one with nothing for 45 s, not even the server's 15 s ping, reconnects with Last-Event-ID, so nothing is missed and nothing repeats: through a redeploy too, for up to 5 minutes without a new event (RECONNECT), then connection_lost. Stop by breaking out of the loop or aborting the signal. A 410 means the resume point is gone (older than retention, or from another stream): read the resource, start over.

Hex HMAC-SHA256 of ${timestampSec}.${payload} with the endpoint's signing secret.

Check a webhook before trusting it. payload is the raw request body, exactly as received (never re-serialized JSON), as text or as bytes (read as UTF-8). Returns the parsed body.

One lost connection after another: ok() when it is back, lost(why) waits before the next try, or throws connection_lost once the budget is spent.

The connection is back (a new event, or an answer): the next loss starts a fresh 5 minutes, and short waits.

A 2xx connection stayed up past RECONNECT.heldOpenMs and said something: the next loss starts a fresh 5 minutes; the waits keep growing until a frame comes. One that answers and closes at once, or never says a word, does not count, so a server that only does that is given up on.

Lost again: wait before the next try (1 s doubling to 15 s, with jitter), or throw connection_lost once 5 minutes have passed.

The /v1 error body, { error: { type, code, message, param?, request_id } }, as an exception.

secret_missing: the secrets to store before the call can succeed.

mcp_server_shared: the other deployments that run the MCP server the file would change.

The events after your resume point are no longer kept: read the conversation again, and follow it from now.

The events after your resume point are no longer kept: read the conversation again, and follow it from now.

The stream answered an error that retrying cannot fix: a bad key, no access, no such stream, or a 429 that outlasted its waits.

A webhook failed its check: no signature header, a bad one, too old, or a signature that does not match.

The API's address when neither baseUrl nor VESTRA_BASE_URL is given.

How a reader rides out a lost connection (a redeploy answers 502 for a minute or two, or refuses the connection): waits that double from 1 s to at most 15 s, each with jitter, for up to 5 minutes in a row. Past that, it gives up with connection_lost.

This SDK's version, sent in its user agent.

Where each type is delivered: the stream carries what happens in a conversation, webhooks the durable events.

How long the interview may say nothing before init gives up (questions()), and how long yaml() waits for the draft.

Compile-time proof that every name above is a real route's answer: a moved route or a wrong status makes one never, and this line stops compiling.

api_key defaults to VESTRA_API_KEY, base_url to VESTRA_BASE_URL. tools answers Bash's calls to your tools.

End the client: the work still on its way is cancelled, its connections closed, and its loop stopped.

Your company's door to Bash, awaited: the same lines as Vestra. api_key defaults to VESTRA_API_KEY, base_url to VESTRA_BASE_URL.

Close the client's connections. async with AsyncVestra() as vestra: closes them for you.

One of your users' Bash, by your own id for them.

Bash interviews you and drafts vestra.yaml: iterate draft.questions(), then await draft.yaml().

Apply vestra.yaml: a new version, promoted in the key's mode once its tests pass (promote='now' or 'no' to choose).

Put an earlier version back live, at once: the one before, or version=. Needs a live key.

Run the tests and wait for the verdict: an edited vestra.yaml is applied first as a version of its own, not promoted (a live key applies nothing), and the summary's note says so.

Scenarios drafted from the deployment's instructions, as vestra.yaml's tests: entries; from version, or else the version test mode runs.

A run already started, followed to its verdict: the one a deploy started (its tests.id), which promotes when it passes, so the summary says what it promoted.

A job in plain words (an AsyncRun; user= names whose Bash), or a list of {"user", "message"} for many users at once (an AsyncBatch).

every: "weekday at 08:00", "mon, wed, fri at 18:30", "30 minutes". on="call": it runs whenever your system posts to its trigger_url.

Delete it: it never runs again.

One routine: what it asks, when it runs next, and when it last ran.

A user's routines (or your company's own Bash's), with when each runs next.

Stop its runs, and keep it.

Start its runs again.

Run it once, now.

Its runs, newest first, each with the conversation it ran in.

Fire a routine that runs on a call, with your system's payload.

Change what it asks, when it runs, its filters or its name.

Answer what Bash waits on, by its id, with the body its type takes: approve=, answers=, done=, or your tool's output=.

Withdraw it: the task carries on without that action.

One interaction: what Bash waits on, its questions, its nonce, and how it settled.

What Bash waits on (pending, unless you ask for another status): every user's, or one user's.

Its screen, live: watch only, or control=True so a person can take the wheel.

A voice call with Bash: open session.url and the page joins the call.

A conversation's events (conv_...) or one task's (task_...), its kept rows first, then live. Stop by breaking out.

A webhook handler: checks the signature, answers your tools' calls itself, and hands every other event to fn.

The record: the events your webhooks get, newest first, as the one shape (lists leave interaction None: read it with answer.get).

The record from now on (or after an evt_ id), oldest first, read every interval seconds. Stop by breaking out.

Send events to your server, signed. The signing secret is in the answer, shown once.

Every step of a task, afterwards, with tokens and cost per turn.

One webhook checked by hand, from its raw body and its Vestra-Signature header.

Delete a file.

Its bytes.

Its details, with a download link good for a short while.

A user's files (or your company's own Bash's), one task's outputs, or one conversation's.

Hand Bash a file (10 MB at most): bytes, a path, or an open file.

A sign-in link for one app: send it to your user, or open it yourself for your company's own Bash.

Every app your users may connect, after your allowlist.

One connected app and its status.

The apps a user has connected (or your company's own Bash has), with each one's status.

Disconnect the app: Bash can no longer use it for this user.

Tell Bash a fact once.

Forget one memory.

Forget everything about this user, or your company's own Bash.

A written profile (.profile), and each memory, newest first.

Ask what Bash remembers: .found and .text.

Bash inside your app; chat=, screen= and voice= choose what the page shows.

Set a user up before first use (a name, a default deployment, a cap). Safe to repeat.

Your users, with this month's spend.

from_ and to are dates (2026-10-01); group_by is day, user, deployment, conversation, task, model or category.

Set the caps and the alert thresholds: org_daily_usd, org_monthly_usd, user_daily_usd, user_monthly_usd, alert_thresholds.

The caps and alert thresholds, with what is spent against each.

The receipt: the charges behind one conversation or one task.

A new key in this key's mode (a test key makes test keys). Its secret is shown once.

Your keys: names, modes, scopes and the last four characters, never the secret.

Your company, and the key in use.

Revoke a key: it stops working at once.

Replace a key; the old one keeps working for grace_seconds (a day by default).

Delete a secret: your company's, or one user's own.

Names only, never values.

Store it, write-only: your company's, or one user's own. Storing it again replaces it.

Every /v1 route as a generated function: vestra._generated's AuthenticatedClient, sent through this client as every call is (your key, the user agent, a rate limit waited out). Use its asyncio functions. Needs httpx and attrs.

End a session now: its token stops working at once.

A session's state: open or ended, and what it shows.

Erase their Bash, computer, memory and files. It runs as a job; user.deleted says when it is done.

Everything held for them, as one download link (a data-rights request).

Their profile, their spend this month and what they may still spend.

What their computer's screen shows now, as JPEG bytes.

Change their name, email, locale, time zone, default deployment, cap or metadata, or switch them off.

Wake their computer now, so their next task starts at once.

Carry on in the same conversation, once this run has ended, so the next message never meets a turn still running.

What this run cost, read once it has ended.

The result you asked for with output=. Raises the turn's error when the turn failed or the answer did not fit it.

Stop the reply and every piece of work the conversation started.

The answer, once the run has ended, trimmed: when Bash went to work, the work's answer, its final reply (task.completed's answer; from an older server without one, its summary, which joins every step's words); otherwise, and when the work ended with no final reply, the reply's answer, its final words (message.completed's answer; from an older server without one, the whole reply). Raises the turn's error when the turn failed (as output() does), so a failed turn never reads as an empty answer.

Waits up to timeout seconds for the answers this run is still sending to your tools' calls (each function's result, then the write that carries it), and returns the calls whose answers had not landed by then: Bash may still be waiting on those, so answer them with vestra.answer. The run never waits on its own answers, so await this before your process exits, on every way out, an error or a cancel included.

Start no new item; the running ones finish.

The batch now: its status and how many items are queued, running, done or failed.

bat_..., once the batch exists.

Every item, with its conversation, task and result, page by page.

Until the batch is no longer running; each read rides out a lost connection (a redeploy) for up to 5 minutes.

End it now: its token stops working at once, and its streams and calls close.

Give the wheel back to Bash.

The screen's stream credentials, made per call, good for 5 minutes.

Take the wheel (a session opened with control).

The interview's closing words, once its draft is saved: what the draft sets Bash up to do, the tools your code answers, the spending cap per task, the starter tests, and the next steps. Show them where init ends. None when the draft version carries none.

Whether the interview has saved its draft (the draft moved past version 1).

Bash's questions, one reply at a time. Answer each to go on; it ends once the draft is saved, or at a question left unanswered. An interview that says nothing for timeout seconds ends with interview_failed.

vestra.yaml, as the interview drafted it (?format=yaml), once the draft is saved: looked for every interval seconds, or from 2 s growing to 5 s when none is given.

Answer what Bash waits on with the body its type takes: approve= (with present_user= or message=), answers=, done=, could_not=, not_now=, output= or error=. An approval that approves gets the interaction's nonce when it needs one.

@tool(description="Live status of a PNR", input={"pnr": "string"}, read_only=True) over a function makes it a declared tool. Unmarked, its call waits for your user's yes; read_only (a lookup) and run_without_asking don't.

Verify the raw body against the Vestra-Signature header and return it parsed.

Hex HMAC-SHA256 of '<timestamp>.<payload>' with the endpoint's signing secret.

The /v1 error body, {"error": {type, code, message, param?, request_id}}, as an exception.

A webhook failed its check: no signature header, a bad one, too old, or a signature that does not match.

Who and what a call is for, handed to your function as call when it takes one.