Every sample on every page follows this. Change it any time.

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

Deployments

How your Bash is set up, in versions: apply a whole vestra.yaml, promote, roll back, and the interview that drafts the file.

Send Authorization: Bearer vk_test_... on every call.

RoutesOpen one for every field it takes and answers.

GET/v1/deploymentsYour deployments.

Your API key, scope setup or all. On the card: deploy. Over HTTP it is made from the contract: fill in every value.

Request2 fields

Query

limitintegerHow many items per page, 1 to 100. Default 20.
Type
integer
cursorstringWhere to go on from: the next_cursor of the page before, unchanged. Absent: the first page.
Type
string
Answers 2002 fields
dataobject[]The items on this page.
idstringThe deployment's id.
Example
dep_8f2k
object"deployment"Always deployment.
Type
"deployment"
namestringIts name, as people read it.
Type
string
slugstringIts name in URLs and refs: send it where a route takes {deployment_id}.
Example
trip-rescue
descriptionstringWhat it is for; empty when none was given.
Type
string
base"bash"What it is built on: always bash.
Type
"bash"
status"active" | "archived"active, or archived (put away: no new conversation or version reaches it).
Type
"active" | "archived"
draft_versionintegerThe version test keys run. A new save moves it there; a promote with a test key moves it to the version named, older ones included.
Type
integer
live_versioninteger | nullThe version live keys run; null until one is promoted.
Type
integer | null
created_atstringWhen it was made, as an ISO 8601 date and time in UTC.
Type
string
updated_atstringWhen it last changed, as an ISO 8601 date and time in UTC.
Type
string
next_cursorstring | nullSend it as cursor for the next page; null on the last page.
Type
string | null
HTTP

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

curl "$VESTRA_BASE_URL/v1/deployments" \  -H "Authorization: Bearer $VESTRA_API_KEY"
POST/v1/deploymentsCreate one on base 'bash'.

It starts with a draft version.

Your API key, scope setup or all. On the card: deploy. Over HTTP it is made from the contract: fill in every value.

GET/v1/deployments/{deployment_id}One deployment, by its id or its name: the live version and the draft.

With format=yaml, its latest version as vestra.yaml.

Your API key, scope setup or all. On the card: deploy. Every call here is a checked sample.

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: []).

MCP servers are registered by URL, and the tool policy the file gives each one is this version's own, on top of the server's floor, from the moment the version runs. Tests become scenarios, and the routines and webhooks the file declares are its own. ?promote=after_tests (the default), now or no promotes in the key's mode. 400 secret_missing names the secrets to store first; 409 mcp_server_shared names the other deployments that run an MCP server whose headers the file would change.

Your API key, scope setup or all. On the card: deploy. Every call here is a checked sample.

PATCH/v1/deployments/{deployment_id}Rename, describe or archive it.

Your API key, scope setup or all. On the card: deploy. Over HTTP it is made from the contract: fill in each {…} and every value.

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.

Your API key, scope setup or all. On the card: deploy. Over HTTP it is made from the contract: fill in each {…} and every value.

GET/v1/deployments/{deployment_id}/versionsEvery version.

Your API key, scope setup or all. On the card: deploy. Every call here is a checked sample.

GET/v1/deployments/{deployment_id}/versions/{version}One version, in full.

Your API key, scope setup or all. On the card: deploy. Every call here is a checked sample.

GET/v1/deployments/{deployment_id}/diffWhat changed between two versions (?from=&to=).

Your API key, scope setup or all. On the card: deploy. Over HTTP it is made from the contract: fill in each {…} and every value.

POST/v1/deployments/{deployment_id}/versions/{version}/promoteMake it live.

Refused unless its latest test run passed.

Your API key, scope setup or all. On the card: deploy. Over HTTP it is made from the contract: fill in each {…} and every value.

POST/v1/deployments/{deployment_id}/rollbackPut an earlier version back live, instantly.

Your API key, scope setup or all. On the card: deploy. Every call here is a checked sample.

POST/v1/deployments/interviewBuild a deployment by talking to Bash: describe the job, answer its questions, receive a draft version.

Your API key, scope setup or all. On the card: init. Every call here is a checked sample.