# API reference

> 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](https://vestra.ai/developers/reference/api/account.md)

Your company's account: who is calling, its keys, its caps, what it spent and the models it may use.

- `GET` [/v1/me](https://vestra.ai/developers/reference/api/account/get-v1-me.md): Who is calling: the company, the key, and whether it is test or live.
- `GET` [/v1/org](https://vestra.ai/developers/reference/api/account/get-v1-org.md): The 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/org](https://vestra.ai/developers/reference/api/account/patch-v1-org.md): Change the name, allowed return URLs, allowed embed origins, default deployment or default memory mode.
- `GET` [/v1/keys](https://vestra.ai/developers/reference/api/account/get-v1-keys.md): List keys.
- `POST` [/v1/keys](https://vestra.ai/developers/reference/api/account/post-v1-keys.md): Create a test or live key.
- `POST` [/v1/keys/{key_id}/roll](https://vestra.ai/developers/reference/api/account/post-v1-keys-key-id-roll.md): Replace a key.
- `DELETE` [/v1/keys/{key_id}](https://vestra.ai/developers/reference/api/account/delete-v1-keys-key-id.md): Revoke a key immediately.
- `GET` [/v1/limits](https://vestra.ai/developers/reference/api/account/get-v1-limits.md): The day and month caps for the company and per user, the alert thresholds and the rate limits.
- `PATCH` [/v1/limits](https://vestra.ai/developers/reference/api/account/patch-v1-limits.md): Set the day and month caps for the company and per user, and the alert thresholds, within what Vestra allows.
- `GET` [/v1/usage](https://vestra.ai/developers/reference/api/account/get-v1-usage.md): Exact 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-items](https://vestra.ai/developers/reference/api/account/get-v1-usage-line-items.md): The charges behind one task or one conversation, newest first: the receipt you can show your user.
- `GET` [/v1/audit-log](https://vestra.ai/developers/reference/api/account/get-v1-audit-log.md): Every key use, settings change and approval answer, newest first.
- `GET` [/v1/models](https://vestra.ai/developers/reference/api/account/get-v1-models.md): The models a deployment may choose from.
- `GET` [/v1/health](https://vestra.ai/developers/reference/api/account/get-v1-health.md): Is the API up.

## [Users](https://vestra.ai/developers/reference/api/users.md)

Your users: set one up, read their spend, change their cap, export or erase them.

- `POST` [/v1/users](https://vestra.ai/developers/reference/api/users/post-v1-users.md): Create one of your users, or return the existing one.
- `GET` [/v1/users](https://vestra.ai/developers/reference/api/users/get-v1-users.md): List your users.
- `GET` [/v1/users/{user_id}](https://vestra.ai/developers/reference/api/users/get-v1-users-user-id.md): One user: status, profile, memory mode, default deployment, and what they spent today and this month against their caps.
- `PATCH` [/v1/users/{user_id}](https://vestra.ai/developers/reference/api/users/patch-v1-users-user-id.md): Change name, language, time zone, metadata, day or month spend cap, default deployment, or status (active or disabled).
- `DELETE` [/v1/users/{user_id}](https://vestra.ai/developers/reference/api/users/delete-v1-users-user-id.md): Erase the user and everything Bash holds for them: computer, files, memory.
- `POST` [/v1/users/{user_id}/export](https://vestra.ai/developers/reference/api/users/post-v1-users-user-id-export.md): Package everything held for the user into one download, for data-rights requests.

## [Conversations](https://vestra.ai/developers/reference/api/conversations.md)

Ask Bash in a conversation, follow its reply as it happens, and stop it.

- `POST` [/v1/conversations](https://vestra.ai/developers/reference/api/conversations/post-v1-conversations.md): Ask.
- `GET` [/v1/conversations](https://vestra.ai/developers/reference/api/conversations/get-v1-conversations.md): Conversations, 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}](https://vestra.ai/developers/reference/api/conversations/get-v1-conversations-conversation-id.md): One conversation: status (idle, replying, working, waiting), its open work, its open approvals.
- `POST` [/v1/conversations/{conversation_id}/messages](https://vestra.ai/developers/reference/api/conversations/post-v1-conversations-conversation-id-messages.md): Send a message.
- `GET` [/v1/conversations/{conversation_id}/messages](https://vestra.ai/developers/reference/api/conversations/get-v1-conversations-conversation-id-messages.md): The conversation, paged: your messages, Bash's replies, and summaries of the work it did.
- `GET` [/v1/conversations/{conversation_id}/events](https://vestra.ai/developers/reference/api/conversations/get-v1-conversations-conversation-id-events.md): The one stream (SSE): replies as they are typed, work started and finished, progress, approvals, tool calls, files.
- `POST` [/v1/conversations/{conversation_id}/stop](https://vestra.ai/developers/reference/api/conversations/post-v1-conversations-conversation-id-stop.md): Stop the reply and every piece of work the conversation started.

## [Work](https://vestra.ai/developers/reference/api/work.md)

The work Bash does on its computer: list it, read it, stop it or delete it.

- `GET` [/v1/tasks](https://vestra.ai/developers/reference/api/work/get-v1-tasks.md): All work across your users, or one user's with user_id.
- `GET` [/v1/tasks/{task_id}](https://vestra.ai/developers/reference/api/work/get-v1-tasks-task-id.md): Status, title, the progress list, the result (text, and data when an output_schema was set), the outcome, cost so far.
- `DELETE` [/v1/tasks/{task_id}](https://vestra.ai/developers/reference/api/work/delete-v1-tasks-task-id.md): Delete it and its outputs.
- `GET` [/v1/tasks/{task_id}/trace](https://vestra.ai/developers/reference/api/work/get-v1-tasks-task-id-trace.md): Every step: tools called with a summary of inputs and outputs, timings, tokens and cost per turn.
- `POST` [/v1/tasks/{task_id}/stop](https://vestra.ai/developers/reference/api/work/post-v1-tasks-task-id-stop.md): Stop this piece of work only.

## [Interactions](https://vestra.ai/developers/reference/api/interactions.md)

What Bash waits on (approvals, questions, apps to connect, hand-offs, calls to your tools) and the answers.

- `GET` [/v1/interactions](https://vestra.ai/developers/reference/api/interactions/get-v1-interactions.md): Everything 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}](https://vestra.ai/developers/reference/api/interactions/get-v1-interactions-interaction-id.md): 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.
- `POST` [/v1/interactions/{interaction_id}/answer](https://vestra.ai/developers/reference/api/interactions/post-v1-interactions-interaction-id-answer.md): Answer it, whatever it is.
- `POST` [/v1/interactions/{interaction_id}/cancel](https://vestra.ai/developers/reference/api/interactions/post-v1-interactions-interaction-id-cancel.md): Withdraw it.

## [Files](https://vestra.ai/developers/reference/api/files.md)

Files Bash makes, and files you hand it.

- `POST` [/v1/files](https://vestra.ai/developers/reference/api/files/post-v1-files.md): Upload a file for Bash to use: multipart/form-data with one part named file.
- `GET` [/v1/files](https://vestra.ai/developers/reference/api/files/get-v1-files.md): Files, 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).
- `GET` [/v1/files/{file_id}](https://vestra.ai/developers/reference/api/files/get-v1-files-file-id.md): Details and a short-lived download link.
- `DELETE` [/v1/files/{file_id}](https://vestra.ai/developers/reference/api/files/delete-v1-files-file-id.md): Delete it.

## [Connected apps](https://vestra.ai/developers/reference/api/connected-apps.md)

The apps each user connects through a sign-in link, and the apps they may choose from.

- `GET` [/v1/apps](https://vestra.ai/developers/reference/api/connected-apps/get-v1-apps.md): The apps your users may connect, after your allowlist.
- `POST` [/v1/connections](https://vestra.ai/developers/reference/api/connected-apps/post-v1-connections.md): Get a connect link for one app, for one user (user_id) or the company's own Bash.
- `GET` [/v1/connections](https://vestra.ai/developers/reference/api/connected-apps/get-v1-connections.md): The connected apps of one user (user_id), or of the company's own Bash.
- `GET` [/v1/connections/{connection_id}](https://vestra.ai/developers/reference/api/connected-apps/get-v1-connections-connection-id.md): One connection's status.
- `DELETE` [/v1/connections/{connection_id}](https://vestra.ai/developers/reference/api/connected-apps/delete-v1-connections-connection-id.md): Disconnect.
- `GET` [/v1/connect/return](https://vestra.ai/developers/reference/api/connected-apps/get-v1-connect-return.md): Hosted by us.

## [MCP servers and secrets](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets.md)

Your MCP servers and the tools they offer, and the secrets Bash uses but never shows.

- `GET` [/v1/mcp-servers](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/get-v1-mcp-servers.md): Your registered MCP servers.
- `POST` [/v1/mcp-servers](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/post-v1-mcp-servers.md): Register 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.
- `GET` [/v1/mcp-servers/{server_id}](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/get-v1-mcp-servers-server-id.md): One server and its settings.
- `PATCH` [/v1/mcp-servers/{server_id}](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/patch-v1-mcp-servers-server-id.md): Change URL, auth or the tool policy floor, for every deployment in both modes.
- `DELETE` [/v1/mcp-servers/{server_id}](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/delete-v1-mcp-servers-server-id.md): Remove it from every user.
- `POST` [/v1/mcp-servers/{server_id}/check](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/post-v1-mcp-servers-server-id-check.md): Connect now and list its tools, to prove it works.
- `GET` [/v1/mcp-servers/{server_id}/tools](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/get-v1-mcp-servers-server-id-tools.md): The tools we found, each with its setting in the server's tool policy floor.
- `PUT` [/v1/secrets/{name}](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/put-v1-secrets-name.md): 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.
- `DELETE` [/v1/secrets/{name}](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/delete-v1-secrets-name.md): Remove one: the company's, or one user's (user_id).
- `GET` [/v1/secrets](https://vestra.ai/developers/reference/api/mcp-servers-and-secrets/get-v1-secrets.md): Secret names, never the values: the company's, or one user's (user_id).

## [Skills](https://vestra.ai/developers/reference/api/skills.md)

Skills your Bash may use: upload one, give it new versions, list them.

- `GET` [/v1/skills](https://vestra.ai/developers/reference/api/skills/get-v1-skills.md): Your company skills, plus the skills Bash already has.
- `POST` [/v1/skills](https://vestra.ai/developers/reference/api/skills/post-v1-skills.md): Upload a skill folder as a zip, or as JSON files.
- `GET` [/v1/skills/{skill_id}](https://vestra.ai/developers/reference/api/skills/get-v1-skills-skill-id.md): One skill and its files.
- `PUT` [/v1/skills/{skill_id}](https://vestra.ai/developers/reference/api/skills/put-v1-skills-skill-id.md): Upload a new version.
- `DELETE` [/v1/skills/{skill_id}](https://vestra.ai/developers/reference/api/skills/delete-v1-skills-skill-id.md): Remove it from every user.
- `GET` [/v1/skills/{skill_id}/versions](https://vestra.ai/developers/reference/api/skills/get-v1-skills-skill-id-versions.md): Every version, each with a content hash.

## [Notebooks](https://vestra.ai/developers/reference/api/notebooks.md)

Knowledge Bash reads before it answers: notebooks, and the documents in them.

- `POST` [/v1/notebooks](https://vestra.ai/developers/reference/api/notebooks/post-v1-notebooks.md): Create a notebook.
- `GET` [/v1/notebooks](https://vestra.ai/developers/reference/api/notebooks/get-v1-notebooks.md): Your notebooks.
- `GET` [/v1/notebooks/{notebook_id}](https://vestra.ai/developers/reference/api/notebooks/get-v1-notebooks-notebook-id.md): One notebook and who may read it.
- `PATCH` [/v1/notebooks/{notebook_id}](https://vestra.ai/developers/reference/api/notebooks/patch-v1-notebooks-notebook-id.md): Rename it, or set who may read it: every user, or named users only.
- `DELETE` [/v1/notebooks/{notebook_id}](https://vestra.ai/developers/reference/api/notebooks/delete-v1-notebooks-notebook-id.md): Delete it.
- `POST` [/v1/notebooks/{notebook_id}/documents](https://vestra.ai/developers/reference/api/notebooks/post-v1-notebooks-notebook-id-documents.md): Add a document, as a file or as text.
- `GET` [/v1/notebooks/{notebook_id}/documents](https://vestra.ai/developers/reference/api/notebooks/get-v1-notebooks-notebook-id-documents.md): Its documents.
- `DELETE` [/v1/notebooks/{notebook_id}/documents/{document_id}](https://vestra.ai/developers/reference/api/notebooks/delete-v1-notebooks-notebook-id-documents-document-id.md): Remove one.

## [Memory](https://vestra.ai/developers/reference/api/memory.md)

What Bash remembers about each user: read it, search it, add to it, forget it.

- `GET` [/v1/memory](https://vestra.ai/developers/reference/api/memory/get-v1-memory.md): What Bash remembers about one user (user_id), or the company's own Bash: the profile and the memories, newest first.
- `POST` [/v1/memory](https://vestra.ai/developers/reference/api/memory/post-v1-memory.md): Tell Bash a fact once, for example 'prefers window seats', for one user (user_id) or the company's own Bash.
- `DELETE` [/v1/memory](https://vestra.ai/developers/reference/api/memory/delete-v1-memory.md): Forget everything about one user (user_id), or the company's own Bash.
- `GET` [/v1/memory/search](https://vestra.ai/developers/reference/api/memory/get-v1-memory-search.md): Ask the memory a question (q), for one user (user_id) or the company's own Bash.
- `DELETE` [/v1/memory/{memory_id}](https://vestra.ai/developers/reference/api/memory/delete-v1-memory-memory-id.md): Forget one thing.

## [Deployments](https://vestra.ai/developers/reference/api/deployments.md)

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](https://vestra.ai/developers/reference/api/deployments/get-v1-deployments.md): Your deployments.
- `POST` [/v1/deployments](https://vestra.ai/developers/reference/api/deployments/post-v1-deployments.md): Create one on base 'bash'.
- `GET` [/v1/deployments/{deployment_id}](https://vestra.ai/developers/reference/api/deployments/get-v1-deployments-deployment-id.md): One deployment, by its id or its name: the live version and the draft.
- `PUT` [/v1/deployments/{deployment_id}](https://vestra.ai/developers/reference/api/deployments/put-v1-deployments-deployment-id.md): 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: []).
- `PATCH` [/v1/deployments/{deployment_id}](https://vestra.ai/developers/reference/api/deployments/patch-v1-deployments-deployment-id.md): Rename, describe or archive it.
- `POST` [/v1/deployments/{deployment_id}/versions](https://vestra.ai/developers/reference/api/deployments/post-v1-deployments-deployment-id-versions.md): Save 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.
- `GET` [/v1/deployments/{deployment_id}/versions](https://vestra.ai/developers/reference/api/deployments/get-v1-deployments-deployment-id-versions.md): Every version.
- `GET` [/v1/deployments/{deployment_id}/versions/{version}](https://vestra.ai/developers/reference/api/deployments/get-v1-deployments-deployment-id-versions-version.md): One version, in full.
- `GET` [/v1/deployments/{deployment_id}/diff](https://vestra.ai/developers/reference/api/deployments/get-v1-deployments-deployment-id-diff.md): What changed between two versions (?from=&to=).
- `POST` [/v1/deployments/{deployment_id}/versions/{version}/promote](https://vestra.ai/developers/reference/api/deployments/post-v1-deployments-deployment-id-versions-version-promote.md): Make it live.
- `POST` [/v1/deployments/{deployment_id}/rollback](https://vestra.ai/developers/reference/api/deployments/post-v1-deployments-deployment-id-rollback.md): Put an earlier version back live, instantly.
- `POST` [/v1/deployments/interview](https://vestra.ai/developers/reference/api/deployments/post-v1-deployments-interview.md): Build a deployment by talking to Bash: describe the job, answer its questions, receive a draft version.

## [Tests](https://vestra.ai/developers/reference/api/tests.md)

The scenarios a version must pass, drafted or written, and the runs that check it before your users see it.

- `GET` [/v1/deployments/{deployment_id}/scenarios](https://vestra.ai/developers/reference/api/tests/get-v1-deployments-deployment-id-scenarios.md): The deployment's test scenarios.
- `POST` [/v1/deployments/{deployment_id}/scenarios](https://vestra.ai/developers/reference/api/tests/post-v1-deployments-deployment-id-scenarios.md): Add one: a pretend user, their goal, what success looks like, what must never happen.
- `POST` [/v1/deployments/{deployment_id}/scenarios/generate](https://vestra.ai/developers/reference/api/tests/post-v1-deployments-deployment-id-scenarios-generate.md): Have Bash draft scenarios from the deployment's instructions.
- `PATCH` [/v1/deployments/{deployment_id}/scenarios/{scenario_id}](https://vestra.ai/developers/reference/api/tests/patch-v1-deployments-deployment-id-scenarios-scenario-id.md): Change one.
- `DELETE` [/v1/deployments/{deployment_id}/scenarios/{scenario_id}](https://vestra.ai/developers/reference/api/tests/delete-v1-deployments-deployment-id-scenarios-scenario-id.md): Remove one.
- `POST` [/v1/deployments/{deployment_id}/test-runs](https://vestra.ai/developers/reference/api/tests/post-v1-deployments-deployment-id-test-runs.md): Run every scenario against a version: version, or the latest when left out.
- `GET` [/v1/deployments/{deployment_id}/test-runs](https://vestra.ai/developers/reference/api/tests/get-v1-deployments-deployment-id-test-runs.md): Past test runs.
- `GET` [/v1/test-runs/{test_run_id}](https://vestra.ai/developers/reference/api/tests/get-v1-test-runs-test-run-id.md): Pass or fail per scenario, the conversation and the judge's reason.

## [Computer setup](https://vestra.ai/developers/reference/api/computer-setup.md)

Wake a user's computer before they need it.

- `POST` [/v1/users/{user_id}/warm](https://vestra.ai/developers/reference/api/computer-setup/post-v1-users-user-id-warm.md): Wake 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/fetch](https://vestra.ai/developers/reference/api/computer-setup/post-v1-users-user-id-browser-fetch.md): Open 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/cookies](https://vestra.ai/developers/reference/api/computer-setup/get-v1-users-user-id-browser-cookies.md): Which cookies of some names the user's browser holds for one site, and until when: names, sites and expiry only, never a value.
- `GET` [/v1/users/{user_id}/browser/watch](https://vestra.ai/developers/reference/api/computer-setup/get-v1-users-user-id-browser-watch.md): Watch the browser fetch's tabs live, as text/event-stream.

## [Routines](https://vestra.ai/developers/reference/api/routines.md)

Jobs Bash runs on a schedule in plain words, or whenever your system calls.

- `POST` [/v1/routines](https://vestra.ai/developers/reference/api/routines/post-v1-routines.md): Create 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).
- `GET` [/v1/routines](https://vestra.ai/developers/reference/api/routines/get-v1-routines.md): The routines of one user (user_id), or of the company's own Bash.
- `GET` [/v1/routines/{routine_id}](https://vestra.ai/developers/reference/api/routines/get-v1-routines-routine-id.md): One routine.
- `PATCH` [/v1/routines/{routine_id}](https://vestra.ai/developers/reference/api/routines/patch-v1-routines-routine-id.md): Change what it asks, when it runs (every, schedule or timezone), its filters, or pause and resume it.
- `DELETE` [/v1/routines/{routine_id}](https://vestra.ai/developers/reference/api/routines/delete-v1-routines-routine-id.md): Delete it.
- `POST` [/v1/routines/{routine_id}/run](https://vestra.ai/developers/reference/api/routines/post-v1-routines-routine-id-run.md): Run it now.
- `POST` [/v1/routines/{routine_id}/trigger](https://vestra.ai/developers/reference/api/routines/post-v1-routines-routine-id-trigger.md): Fire it with a payload from your system: a train delayed, a refund posted.
- `GET` [/v1/routines/{routine_id}/runs](https://vestra.ai/developers/reference/api/routines/get-v1-routines-routine-id-runs.md): Past runs and the tasks they started.

## [Batches](https://vestra.ai/developers/reference/api/batches.md)

Many users at once: one ask each, followed together.

- `POST` [/v1/batches](https://vestra.ai/developers/reference/api/batches/post-v1-batches.md): Start a batch: a deployment, a list of items (user_id optional, message, context, metadata) and a concurrency.
- `GET` [/v1/batches/{batch_id}](https://vestra.ai/developers/reference/api/batches/get-v1-batches-batch-id.md): Progress: counts by status, spend so far.
- `GET` [/v1/batches/{batch_id}/items](https://vestra.ai/developers/reference/api/batches/get-v1-batches-batch-id-items.md): Each item with its task id and result.
- `POST` [/v1/batches/{batch_id}/cancel](https://vestra.ai/developers/reference/api/batches/post-v1-batches-batch-id-cancel.md): Stop starting new items; running ones finish.

## [Webhooks and events](https://vestra.ai/developers/reference/api/webhooks-and-events.md)

Where events go, how each delivery went, and the record of every event.

- `POST` [/v1/webhooks](https://vestra.ai/developers/reference/api/webhooks-and-events/post-v1-webhooks.md): Register a URL and the events it wants.
- `GET` [/v1/webhooks](https://vestra.ai/developers/reference/api/webhooks-and-events/get-v1-webhooks.md): Your endpoints.
- `GET` [/v1/webhooks/{endpoint_id}](https://vestra.ai/developers/reference/api/webhooks-and-events/get-v1-webhooks-endpoint-id.md): One endpoint.
- `PATCH` [/v1/webhooks/{endpoint_id}](https://vestra.ai/developers/reference/api/webhooks-and-events/patch-v1-webhooks-endpoint-id.md): Change URL or events, switch it on or off.
- `DELETE` [/v1/webhooks/{endpoint_id}](https://vestra.ai/developers/reference/api/webhooks-and-events/delete-v1-webhooks-endpoint-id.md): Remove it.
- `POST` [/v1/webhooks/{endpoint_id}/roll-secret](https://vestra.ai/developers/reference/api/webhooks-and-events/post-v1-webhooks-endpoint-id-roll-secret.md): New signing secret; the old one is accepted for 24 hours.
- `POST` [/v1/webhooks/{endpoint_id}/test](https://vestra.ai/developers/reference/api/webhooks-and-events/post-v1-webhooks-endpoint-id-test.md): Send a sample event now.
- `GET` [/v1/webhooks/{endpoint_id}/deliveries](https://vestra.ai/developers/reference/api/webhooks-and-events/get-v1-webhooks-endpoint-id-deliveries.md): Every attempt with status code and timing.
- `POST` [/v1/webhooks/{endpoint_id}/deliveries/{delivery_id}/retry](https://vestra.ai/developers/reference/api/webhooks-and-events/post-v1-webhooks-endpoint-id-deliveries-delivery-id-retry.md): Send one again.
- `GET` [/v1/events](https://vestra.ai/developers/reference/api/webhooks-and-events/get-v1-events.md): The same events as a list you can pull, for anything you missed.
- `GET` [/v1/events/{event_id}](https://vestra.ai/developers/reference/api/webhooks-and-events/get-v1-events-event-id.md): One event.

## [Sessions](https://vestra.ai/developers/reference/api/sessions.md)

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

- `POST` [/v1/sessions](https://vestra.ai/developers/reference/api/sessions/post-v1-sessions.md): Open 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).
- `GET` [/v1/sessions/{session_id}](https://vestra.ai/developers/reference/api/sessions/get-v1-sessions-session-id.md): Whether a session is still open, and what it was opened with.
- `DELETE` [/v1/sessions/{session_id}](https://vestra.ai/developers/reference/api/sessions/delete-v1-sessions-session-id.md): End a session now: its token stops working, its streams close and its call hangs up.
- `GET` [/v1/sessions/{session_id}/frame-policy](https://vestra.ai/developers/reference/api/sessions/get-v1-sessions-session-id-frame-policy.md): Which sites may show a session's page.
- `GET` [/v1/sessions/{session_id}/screen](https://vestra.ai/developers/reference/api/sessions/get-v1-sessions-session-id-screen.md): With the session's token: the stream credentials of the user's Bash browser, good for 5 minutes.
- `POST` [/v1/sessions/{session_id}/screen](https://vestra.ai/developers/reference/api/sessions/post-v1-sessions-session-id-screen.md): With 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}/screenshot](https://vestra.ai/developers/reference/api/sessions/get-v1-users-user-id-screenshot.md): The latest frame of the user's browser, as a JPEG.
- `POST` [/v1/sessions/{session_id}/voice](https://vestra.ai/developers/reference/api/sessions/post-v1-sessions-session-id-voice.md): Called from the user's browser with the session's token and its WebRTC offer; answers the model's answer.

## [MCP server](https://vestra.ai/developers/reference/api/mcp-server.md)

Bash as an MCP server, for your editor or your own agents.

- `POST` [/v1/mcp](https://vestra.ai/developers/reference/api/mcp-server/post-v1-mcp.md): One MCP endpoint (streamable HTTP): the card's lines as tools, each with an optional user (with none, your company's own Bash).

## [A2A](https://vestra.ai/developers/reference/api/a2a.md)

Each deployment as an agent other agents can call, over the A2A protocol.

- `GET` [/v1/a2a/{deployment_id}/.well-known/agent-card.json](https://vestra.ai/developers/reference/api/a2a/get-v1-a2a-deployment-id-well-known-agent-card-json.md): What this deployment does and how to authenticate, for other agents to discover.
- `POST` [/v1/a2a/{deployment_id}](https://vestra.ai/developers/reference/api/a2a/post-v1-a2a-deployment-id.md): A2A JSON-RPC: send a message, stream, get, list or cancel.

## [Contract](https://vestra.ai/developers/reference/api/contract.md)

The contract itself, as OpenAPI.

- `GET` [/v1/openapi.json](https://vestra.ai/developers/reference/api/contract/get-v1-openapi-json.md): The whole contract, machine-readable.