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}/versionsEvery version.
Request3 fields
Path
deployment_idstringrequiredThe deployment's id (dep_...). The /v1/deployments routes also take its name.
- Type
string
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.
object"deployment_version"Always deployment_version.
- Type
"deployment_version"
deployment_idstringThe deployment's id.
- Example
dep_8f2k
versionintegerA version number: 1 is the first, and each save adds one.
- Type
integer
manifestobjectThe version's settings, every default filled in.
base"bash"What the deployment is built on: always bash.
- Default
bash
instructionsstringWhat Bash does here, and how, in plain words, up to 8,000 characters. Empty by default.
- Default
- Empty.
- Limits
- At most 8000 characters.
languagestringThe language Bash speaks: a tag such as en, hi or pt-BR, or auto (the default) to follow each user.
- Default
auto
mcp_serversstring[]The MCP servers Bash may call, by their mcp_ ids (POST /v1/mcp-servers).
- Default
[]
mcp_tool_policyobject[]may be absentThis version's own tool policy for its MCP servers, on top of each server's floor. Absent (every version saved before it): each server's own policy alone.
- Limits
- At most 50 items.
appsobjectWhich apps its users may connect.
- Default
{"allow":"all"}
approvalsobjectWhat Bash asks the person before doing.
- Default
{"always":["payment","booking","cancellation"]}
modelstringdefault (the default), or a model id from GET /v1/models.
- Default
default
memoryobjectWhat Bash remembers about each user here.
- Default
{}
notebooksstring[]What Bash reads before it answers: notebooks, by their nb_ ids.
- Default
[]
skillsstring[]Skills Bash may use: company skills by their skl_ ids, or skills Bash already has, by name.
- Default
[]
toolsobject[]Tools your own code answers: Bash's call reaches you as an interaction of type tool_call, after the person's yes unless the tool is marked read_only or run_without_asking.
- Default
[]
environmentobjectmay be absentBash's computer, ready before the first task: a setup script, environment variables, repositories and files. Absent: a plain computer.
- Type
object
browserobjectmay be absentThe sites a browser fetch may open, and the pages the browser never opens or acts on. Absent: a fetch opens nothing, and no page is closed.
- Type
object
routinesobject[]Not used: a version holds no routines. Write them in vestra.yaml, or make them with POST /v1/routines.
- Default
[]
limitsobjectWhat one piece of work may spend. There is no time limit.
- Default
{"spend_per_task_usd":2}
manifest_sha256stringA hash of the settings: two versions with the same hash run the same.
- Type
string
skill_pinsobject[]The company skills this version runs, each at the version of the skill current when it was saved.
skillstringThe company skill, by its skl_ id.
- Type
string
slugstringThe skill's name.
- Type
string
pressing_sha256string | nullThe content hash of the skill's version when this version was saved: the one it runs. Null when none was recorded.
- Type
string | null
notestring | nullThe note it was saved with; null when none.
- Type
string | null
created_bystringWho saved it: a key's id (key_...), console (a person in the console), client (a session token from your app) or interview (the draft the interview wrote).
- Type
string
created_atstringWhen it was saved, as an ISO 8601 date and time in UTC.
- Type
string
is_draftbooleanTrue when test keys run this version.
- Type
boolean
is_livebooleanTrue when live keys run it.
- Type
boolean
test_verdict"passed" | "failed" | "none"may be absentIts latest test run's verdict: passed, failed, or none (never tested). Only when you read one version (GET .../versions/{version}); absent in the list.
- Type
"passed" | "failed" | "none"
interviewobjectmay be absentThe interview's closing words, on the version the interview saved; absent on every other version.
summarystringWhat the draft sets Bash up to do, in the interview's words.
- Type
string
toolsobject[]The tools the file declares that your own code answers.
- Type
object[]
per_task_usdnumberThe spending cap per piece of work, in US dollars.
- Type
number
per_task_usd_is_defaultbooleanTrue when that cap is the default, 2, because the file left it.
- Type
boolean
testsintegerHow many starter tests the file holds.
- Type
integer
next_stepsstring[]What to do next, one plain line each, in order.
- Type
string[]
next_cursorstring | nullSend it as cursor for the next page; null on the last page.
- Type
string | null
# Publish a change. Send the whole file as JSON, by its name. The first call creates the deployment, and a# file that changes nothing makes no new version. Its tests run, and when they pass the version goes live in# your key's mode: test traffic with a test key, real users with a live key. A test plays your own tools with# tool_results. The first deployment you promote becomes the default, and every ask that names no deployment# goes to it. became_default is true when this call made it the default. If the call waits for tests, that# happens when they pass.curl -X PUT "$VESTRA_BASE_URL/v1/deployments/trip-rescue?promote=after_tests" \ -H "Authorization: Bearer $VESTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "trip-rescue", "instructions": "You help Tripnest travellers fix broken trips. Always offer two options.", "apps": ["gmail", "google-calendar"], "tools": [{ "function": "get_booking", "description": "A booking by its PNR", "input": { "pnr": "string" }, "read_only": true }], "approvals": ["payment", "booking", "cancellation"], "tests": [{ "name": "Bag allowance", "ask": "How many kilos can I take on booking TN-48213?", "expect": "Says 7 kg of cabin baggage.", "tool_results": { "get_booking": { "cabin_kg": 7 } } }] }' # Read the file and its versions. The file comes back as YAML.curl "$VESTRA_BASE_URL/v1/deployments/trip-rescue?format=yaml" \ -H "Authorization: Bearer $VESTRA_API_KEY" curl "$VESTRA_BASE_URL/v1/deployments/dep_4kq/versions" \ -H "Authorization: Bearer $VESTRA_API_KEY" # Roll back to the previous version. The version that was live before comes back at once. This needs a live key.curl -X POST "$VESTRA_BASE_URL/v1/deployments/dep_4kq/rollback" \ -H "Authorization: Bearer $VESTRA_LIVE_KEY"No sample in your language for this route, so here it is over HTTP.
# Publish a change. Send the whole file as JSON, by its name. The first call creates the deployment, and a# file that changes nothing makes no new version. Its tests run, and when they pass the version goes live in# your key's mode: test traffic with a test key, real users with a live key. A test plays your own tools with# tool_results. The first deployment you promote becomes the default, and every ask that names no deployment# goes to it. became_default is true when this call made it the default. If the call waits for tests, that# happens when they pass.curl -X PUT "$VESTRA_BASE_URL/v1/deployments/trip-rescue?promote=after_tests" \ -H "Authorization: Bearer $VESTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "trip-rescue", "instructions": "You help Tripnest travellers fix broken trips. Always offer two options.", "apps": ["gmail", "google-calendar"], "tools": [{ "function": "get_booking", "description": "A booking by its PNR", "input": { "pnr": "string" }, "read_only": true }], "approvals": ["payment", "booking", "cancellation"], "tests": [{ "name": "Bag allowance", "ask": "How many kilos can I take on booking TN-48213?", "expect": "Says 7 kg of cabin baggage.", "tool_results": { "get_booking": { "cabin_kg": 7 } } }] }' # Read the file and its versions. The file comes back as YAML.curl "$VESTRA_BASE_URL/v1/deployments/trip-rescue?format=yaml" \ -H "Authorization: Bearer $VESTRA_API_KEY" curl "$VESTRA_BASE_URL/v1/deployments/dep_4kq/versions" \ -H "Authorization: Bearer $VESTRA_API_KEY" # Roll back to the previous version. The version that was live before comes back at once. This needs a live key.curl -X POST "$VESTRA_BASE_URL/v1/deployments/dep_4kq/rollback" \ -H "Authorization: Bearer $VESTRA_LIVE_KEY"