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. Every route of Deployments.

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.

Request2 fields

Path

deployment_idstringrequiredThe deployment's id (dep_...). The /v1/deployments routes also take its name.

Type: string

versionstringrequiredThe version number: 1 is the first, and each save adds one.

Type: string

Answers 20013 fields

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.

serverstringThe MCP server, by its mcp_ id, one mcp_servers lists.

Type: string

denystring[]Tools of the server this version never calls, on top of the server's own floor.

Default: []
Limits: At most 200 items.

require_approvalstring[]Tools of the server that wait for the person's yes in this version, on top of the server's own floor.

Default: []
Limits: At most 200 items.

run_without_askingstring[]may be absentTools of the server this version runs without waiting for the person's yes. Every other tool of the server waits for it, unless the server marks the tool read-only (readOnlyHint).

Limits: At most 200 items.

appsobjectWhich apps its users may connect.

Default: {"allow":"all"}

allow"all" | string[]The apps its users may connect: all (the default), or a list such as ["gmail"].

Default: all

approvalsobjectWhat Bash asks the person before doing.

Default: {"always":["payment","booking","cancellation"]}

always("payment" | "booking" | "cancellation" | "send_email" | "publish" | "delete")[]What Bash asks the person before doing: any of payment, booking, cancellation, send_email, publish and delete. Default the first three. A system approval enforces what approvals lists for your own functions and your MCP servers' tools that wait for a yes; in a browser or a connected app, Bash is instructed to ask.

Default: ["payment","booking","cancellation"]

modelstringdefault (the default), or a model id from GET /v1/models.

Default: default

memoryobjectWhat Bash remembers about each user here.

Default: {}

mode"vestra" | "customer" | "none"may be absentvestra, customer or none. Absent: the company's memory_mode.

Type: "vestra" | "customer" | "none"

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

namestringThe tool's name: lowercase letters, digits and underscores, starting with a letter, up to 64.

Example: get_booking

descriptionstringWhat the tool does, so Bash knows when to call it, up to 1024 characters.

Limits: 1 to 1024 characters.
Example: A booking by its PNR

input_schemamap of anyIts arguments, as JSON Schema with type: object. Bash's call fills them in.

Example: {"type":"object","properties":{"pnr":{"type":"string"}},"required":["pnr"]}

timeout_sintegerSeconds Bash waits for your answer, 5 to 600. Default 120; after it, the call expires.

Default: 120
Limits: 5 to 600.

read_onlybooleanmay be absenttrue: the tool changes nothing (a lookup), so Bash calls it without waiting for the person's yes. Absent: false.

Type: boolean

run_without_askingbooleanmay be absenttrue: the tool changes something that needs no yes, so Bash calls it without waiting for the person's yes. Absent: false.

Type: boolean

environmentobjectmay be absentBash's computer, ready before the first task: a setup script, environment variables, repositories and files. Absent: a plain computer.

setup_scriptstringmay be absentA shell script run once on each computer before its first task, and again when the environment changes, up to 20,000 characters. Absent: none.

Limits: At most 20000 characters.

envmap of stringEnvironment variables on the computer, by name. A credential is ${secret:NAME}, filled in from your secrets, never a raw value.

Default: {}
Example: {"REGION":"ap-south-1"}

reposobject[]Repositories cloned onto the computer.

Default: []

filesobject[]Files placed on the computer.

Default: []

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.

allowed_domainsstring[]may be absentThe sites a browser fetch may open, as bare host names such as ixigo.com, which also allows www.ixigo.com. Up to 20. Absent: a browser fetch opens nothing.

Limits: 1 to 20 items.
Example: ["ixigo.com"]

blocked_pathsstring[]may be absentPages the browser never opens or acts on, as a site and the start of a path, such as ixigo.com/payments/. Enforced in code for a browser fetch (403 page_blocked) and Bash's own browser tools. Up to 20.

Limits: 1 to 20 items.
Example: ["ixigo.com/payments/"]

routinesobject[]Not used: a version holds no routines. Write them in vestra.yaml, or make them with POST /v1/routines.

Default: []

namestringThe routine's name.

Type: string

schedulestringWhen it runs.

Type: string

messagestringWhat it asks.

Type: string

limitsobjectWhat one piece of work may spend. There is no time limit.

Default: {"spend_per_task_usd":2}

spend_per_task_usdnumberThe most one piece of work may spend, in US dollars, above 0 and at most 100. Default 2.

Default: 2
Limits: Above 0, at most 100.

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.

namestringThe tool's name.

Type: string

descriptionstringWhat it does.

Type: string

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[]

HTTP

# Describe the job. The interview runs as a conversation, so its questions arrive like any other reply.curl "$VESTRA_BASE_URL/v1/deployments/interview" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "Trip rescue", "slug": "trip-rescue", "job": "Help Tripnest travellers fix broken trips: cancellations, delays, missed connections. Look bookings up with get_booking." }' # Answer its questions. Follow the conversation the response names, and reply in it.curl -N "$VESTRA_BASE_URL/v1/conversations/conv_iv7/events" \  -H "Authorization: Bearer $VESTRA_API_KEY" curl "$VESTRA_BASE_URL/v1/conversations/conv_iv7/messages" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "message": "Ask first before paying a fare difference." }' # Save the draft to your repo. When the interview ends, download the draft as vestra.yaml, starter tests# included.curl "$VESTRA_BASE_URL/v1/deployments/trip-rescue?format=yaml" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -o vestra.yaml # Read the closing words. The draft version (the deployment's draft_version) has them in its interview field:# what it set up, the tools your code must answer, the spending cap per task, the tests, and the next steps.curl "$VESTRA_BASE_URL/v1/deployments/trip-rescue/versions/2" \  -H "Authorization: Bearer $VESTRA_API_KEY"

HTTP

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

# Describe the job. The interview runs as a conversation, so its questions arrive like any other reply.curl "$VESTRA_BASE_URL/v1/deployments/interview" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "Trip rescue", "slug": "trip-rescue", "job": "Help Tripnest travellers fix broken trips: cancellations, delays, missed connections. Look bookings up with get_booking." }' # Answer its questions. Follow the conversation the response names, and reply in it.curl -N "$VESTRA_BASE_URL/v1/conversations/conv_iv7/events" \  -H "Authorization: Bearer $VESTRA_API_KEY" curl "$VESTRA_BASE_URL/v1/conversations/conv_iv7/messages" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "message": "Ask first before paying a fare difference." }' # Save the draft to your repo. When the interview ends, download the draft as vestra.yaml, starter tests# included.curl "$VESTRA_BASE_URL/v1/deployments/trip-rescue?format=yaml" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -o vestra.yaml # Read the closing words. The draft version (the deployment's draft_version) has them in its interview field:# what it set up, the tools your code must answer, the spending cap per task, the tests, and the next steps.curl "$VESTRA_BASE_URL/v1/deployments/trip-rescue/versions/2" \  -H "Authorization: Bearer $VESTRA_API_KEY"