API
Every route, by what it is for. Each group's page says what each route does, every field it takes and answers, and shows it in your language. Send Authorization: Bearer vk_test_... on every call.
Account
Your company's account: who is calling, its keys, its caps, what it spent and the models it may use.
GET/v1/orgThe company account: name, status, the wallet in billed dollars, day and month caps, alert thresholds, allowed return URLs, allowed embed origins, default deployment.
PATCH/v1/orgChange the name, allowed return URLs, allowed embed origins, default deployment or default memory mode.
GET/v1/limitsThe day and month caps for the company and per user, the alert thresholds and the rate limits.
PATCH/v1/limitsSet the day and month caps for the company and per user, and the alert thresholds, within what Vestra allows.
GET/v1/usageExact billed spend and real task counts, by day, user, deployment, conversation, task, model or kind of spend, filtered by user, deployment or conversation.
GET/v1/usage/line-itemsThe charges behind one task or one conversation, newest first: the receipt you can show your user.
Users
Your users: set one up, read their spend, change their cap, export or erase them.
GET/v1/users/{user_id}One user: status, profile, memory mode, default deployment, and what they spent today and this month against their caps.
PATCH/v1/users/{user_id}Change name, language, time zone, metadata, day or month spend cap, default deployment, or status (active or disabled).
DELETE/v1/users/{user_id}Erase the user and everything Bash holds for them: computer, files, memory.
POST/v1/users/{user_id}/exportPackage everything held for the user into one download, for data-rights requests.
Conversations
Ask Bash in a conversation, follow its reply as it happens, and stop it.
GET/v1/conversationsConversations, newest first: one user's with user_id, or every one of the company's without it (the company's own Bash shows user_id null).
GET/v1/conversations/{conversation_id}One conversation: status (idle, replying, working, waiting), its open work, its open approvals.
GET/v1/conversations/{conversation_id}/messagesThe conversation, paged: your messages, Bash's replies, and summaries of the work it did.
GET/v1/conversations/{conversation_id}/eventsThe one stream (SSE): replies as they are typed, work started and finished, progress, approvals, tool calls, files.
POST/v1/conversations/{conversation_id}/stopStop the reply and every piece of work the conversation started.
Work
The work Bash does on its computer: list it, read it, stop it or delete it.
GET/v1/tasks/{task_id}Status, title, the progress list, the result (text, and data when an output_schema was set), the outcome, cost so far.
GET/v1/tasks/{task_id}/traceEvery step: tools called with a summary of inputs and outputs, timings, tokens and cost per turn.
Interactions
What Bash waits on (approvals, questions, apps to connect, hand-offs, calls to your tools) and the answers.
GET/v1/interactionsEverything Bash waits on, across your users: approvals, questions, app connections, hand-offs, and calls to your client tools (type tool_call).
GET/v1/interactions/{interaction_id}One item, by its int_ or call_ id: its type (approval, question, connect, handoff, tool_call), what Bash wants to do, the options, when it expires.
Files
Files Bash makes, and files you hand it.
GET/v1/filesFiles, each with its task and conversation: one user's (user_id) or the company's own Bash's, one task's outputs (task_id), or one conversation's, its tasks' outputs (conversation_id).
Connected apps
The apps each user connects through a sign-in link, and the apps they may choose from.
POST/v1/connectionsGet a connect link for one app, for one user (user_id) or the company's own Bash.
MCP servers and secrets
Your MCP servers and the tools they offer, and the secrets Bash uses but never shows.
POST/v1/mcp-serversRegister one: URL, auth (none, or headers using ${secret:NAME} or ${user_secret:NAME}), and its tool policy floor: tools never run and tools that always need approval, for every deployment in both modes.
PATCH/v1/mcp-servers/{server_id}Change URL, auth or the tool policy floor, for every deployment in both modes.
GET/v1/mcp-servers/{server_id}/toolsThe tools we found, each with its setting in the server's tool policy floor.
PUT/v1/secrets/{name}Store a secret, write-only: the company's (refer to it as ${secret:NAME}), or with user_id one user's own (${user_secret:NAME}), for example their travel account token.
Skills
Skills your Bash may use: upload one, give it new versions, list them.
Notebooks
Knowledge Bash reads before it answers: notebooks, and the documents in them.
Memory
What Bash remembers about each user: read it, search it, add to it, forget it.
GET/v1/memoryWhat Bash remembers about one user (user_id), or the company's own Bash: the profile and the memories, newest first.
POST/v1/memoryTell Bash a fact once, for example 'prefers window seats', for one user (user_id) or the company's own Bash.
GET/v1/memory/searchAsk the memory a question (q), for one user (user_id) or the company's own Bash.
Deployments
How your Bash is set up, in versions: apply a whole vestra.yaml, promote, roll back, and the interview that drafts the file.
GET/v1/deployments/{deployment_id}One deployment, by its id or its name: the live version and the draft.
PUT/v1/deployments/{deployment_id}Apply a whole vestra.yaml, sent as JSON, by the deployment's name: the first call makes it, and a file that changes nothing makes no version (changed: []).
POST/v1/deployments/{deployment_id}/versionsSave a new version: instructions, language, MCP servers and this version's own tool policy for them (mcp_tool_policy, on top of each server's floor), allowed apps, approval rules, model, memory mode, notebooks, limits per task.
POST/v1/deployments/interviewBuild a deployment by talking to Bash: describe the job, answer its questions, receive a draft version.
Tests
The scenarios a version must pass, drafted or written, and the runs that check it before your users see it.
POST/v1/deployments/{deployment_id}/scenariosAdd one: a pretend user, their goal, what success looks like, what must never happen.
POST/v1/deployments/{deployment_id}/scenarios/generateHave Bash draft scenarios from the deployment's instructions.
POST/v1/deployments/{deployment_id}/test-runsRun every scenario against a version: version, or the latest when left out.
Computer setup
Wake a user's computer before they need it.
POST/v1/users/{user_id}/warmWake the user's computer now (for example when they open your app), so their next task starts without waiting.
POST/v1/users/{user_id}/browser/fetchOpen one page in a background tab of the user's own browser, with no model, and get back the bodies of the page's own data calls that match capture.
GET/v1/users/{user_id}/browser/cookiesWhich cookies of some names the user's browser holds for one site, and until when: names, sites and expiry only, never a value.
Routines
Jobs Bash runs on a schedule in plain words, or whenever your system calls.
POST/v1/routinesCreate one: what to ask, and when: every (plain words such as "weekday at 08:00", read in the user's time zone), a cron schedule, or on "call" (your system posts to its trigger_url).
PATCH/v1/routines/{routine_id}Change what it asks, when it runs (every, schedule or timezone), its filters, or pause and resume it.
POST/v1/routines/{routine_id}/triggerFire it with a payload from your system: a train delayed, a refund posted.
Batches
Many users at once: one ask each, followed together.
POST/v1/batchesStart a batch: a deployment, a list of items (user_id optional, message, context, metadata) and a concurrency.
Webhooks and events
Where events go, how each delivery went, and the record of every event.
Sessions
Bash in a browser: its live screen, a voice call, or the whole of Bash inside your app.
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).
DELETE/v1/sessions/{session_id}End a session now: its token stops working, its streams close and its call hangs up.
GET/v1/sessions/{session_id}/screenWith the session's token: the stream credentials of the user's Bash browser, good for 5 minutes.
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.
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.
MCP server
Bash as an MCP server, for your editor or your own agents.
POST/v1/mcpOne MCP endpoint (streamable HTTP): the card's lines as tools, each with an optional user (with none, your company's own Bash).
A2A
Each deployment as an agent other agents can call, over the A2A protocol.
GET/v1/a2a/{deployment_id}/.well-known/agent-card.jsonWhat this deployment does and how to authenticate, for other agents to discover.
Contract
The contract itself, as OpenAPI.