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

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

Batches

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

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

RoutesOpen one for every field it takes and answers.

POST/v1/batchesStart a batch: a deployment, a list of items (user_id optional, message, context, metadata) and a concurrency.

Each item is one conversation message with hand_off: always.

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

Request5 fields

Headers

Idempotency-KeystringSend the same key to retry this call safely for 24 hours.
Type
string

Body

deploymentstringWhich deployment answers every item: its id or name, never a pinned version. Absent: your company's default deployment.
Limits
At least 1 character.
itemsobject[]requiredThe jobs: 1 to 5,000, each one conversation.
Limits
1 to 5000 items.
user_idstringYour id for the user this item is for. Absent: your company's own Bash.
Example
traveller-42
messagestringrequiredWhat Bash is asked, in at most 32,000 characters. It goes straight to work.
Limits
1 to 32000 characters.
Example
Is your flight hit by the storm?
contextmap of anyFacts for this item only, as JSON: Bash reads them as data, never as instructions.
Type
map of any
metadatamap of stringYour own labels, given back as you sent them: at most 32 keys of 1 to 64 characters, each value a string of at most 512. Bash never reads them.
Example
{"order_id":"ORD-1042","channel":"app"}
concurrencyintegerHow many items run at once, 1 to 100. Default: 10. Items with no user share your company's own Bash, 5 at a time at most.
Default
10
Limits
1 to 100.
metadatamap of stringYour own labels, given back as you sent them: at most 32 keys of 1 to 64 characters, each value a string of at most 512. Bash never reads them.
Example
{"order_id":"ORD-1042","channel":"app"}
Answers 20111 fields
idstringThe batch (bat_...).
Example
bat_7xk
object"batch"Always batch.
Type
"batch"
status"running" | "cancelled" | "completed"running: items are still starting or running. cancelled: you cancelled it, so no new item starts. completed: every item has finished.
Type
"running" | "cancelled" | "completed"
deployment_idstring | nullThe deployment that answers its items (dep_...); null when none applies.
Type
string | null
concurrencyintegerHow many items run at once.
Type
integer
item_countintegerHow many items it has.
Type
integer
countsobjectIts items, by status.
queuedintegerItems not started yet.
Type
integer
runningintegerItems running now.
Type
integer
succeededintegerItems that finished well.
Type
integer
failedintegerItems that failed.
Type
integer
cancelledintegerItems a cancel kept from starting.
Type
integer
spend_usdnumberWhat it has cost so far, in billed US dollars: every item's conversation and all its work.
Example
0.061
metadatamap of stringYour labels, as you sent them; empty when you sent none.
Type
map of string
created_atstringWhen it was made, as an ISO 8601 time.
Type
string
completed_atstring | nullWhen it stopped running, completed or cancelled, as an ISO 8601 time; null while running.
Type
string | null
TypeScript
const batch = vestra.ask([{ user: 'traveller-42', message: 'Is your flight hit by the storm?' }]);await batch.created;
Python
batch = vestra.ask([{"user": "traveller-42", "message": "Is your flight hit by the storm?"}])created = batch.created
CLI
vestra ask "Is your flight hit by the storm?" --users travellers.csv
HTTP
# Ask for one of your users. Their Bash is created the first time you name them. With stream: true, the# response streams this turn's events as they happen, and ends when the turn is over.curl -N "$VESTRA_BASE_URL/v1/conversations" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "user_id": "traveller-42",    "message": "My 6am flight got cancelled. What should I do?",    "stream": true  }' # Ask a follow-up. It goes to the same conversation.curl -N "$VESTRA_BASE_URL/v1/conversations/conv_8f2k/messages" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "message": "Can I get a refund for it?", "stream": true }' # Stop a reply and its work. This stops the reply and every task the conversation started.curl -X POST "$VESTRA_BASE_URL/v1/conversations/conv_8f2k/stop" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Ask for your company. Leave user_id out, and the job goes to your company's own Bash.curl "$VESTRA_BASE_URL/v1/conversations" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "message": "Write a two-line notice for our travellers about storm delays at Mumbai airport today." }' # Ask for many users at once. Each user gets their own conversation. If Bash asks one of them a question,# that item waits for the answer.curl "$VESTRA_BASE_URL/v1/batches" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "items": [      { "user_id": "traveller-42", "message": "A storm may delay flights from Mumbai today. What should I do before I leave for the airport? Two lines, in general: no need to look up my booking." },      { "user_id": "traveller-77", "message": "A storm may delay flights from Pune today. What should I do before I leave for the airport? Two lines, in general: no need to look up my booking." }    ]  }'
MCP
{  "method": "tools/call",  "params": {    "name": "ask",    "arguments": {      "user": "traveller-42",      "message": "My 6am flight got cancelled. Get me on the next one."    }  }}
GET/v1/batches/{batch_id}Progress: counts by status, spend so far.

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

GET/v1/batches/{batch_id}/itemsEach item with its task id and result.

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

POST/v1/batches/{batch_id}/cancelStop starting new items; running ones finish.

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