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

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

Routines

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

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

RoutesOpen one for every field it takes and answers.

POST/v1/routinesCreate 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).

For a user, or with no user_id for the company's own Bash. Each run is a message in the routine's conversation.

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

Request12 fields

Headers

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

Body

user_idstringWhose Bash runs it: your id for the user. Absent: your company's own Bash.
Example
traveller-42
askstringrequiredWhat Bash is asked on every run, as a person would ask it, up to 8,000 characters.
Limits
1 to 8000 characters.
Example
Check today's trips for delays and tell me what changed.
namestringIts name, up to 200 characters. Absent: the start of ask.
Limits
1 to 200 characters.
everystringWhen it runs, in plain words: weekday at 08:00, mon, wed, fri at 18:30, 30 minutes, month on the 1st at 09:00. At most once every 15 minutes. Give one of every, schedule or on.
Limits
1 to 100 characters.
Example
weekday at 08:00
timezonestringThe zone every is read in, an IANA name such as Asia/Kolkata. Absent: the user's own, then UTC.
Limits
1 to 64 characters.
Example
Asia/Kolkata
scheduleobjectWhen it runs, as cron, instead of every.
cronstringrequiredA cron expression of five fields: 0 7 * * * runs at 7:00 every day.
Limits
1 to 120 characters.
Example
0 7 * * 1-5
timezonestringThe zone the cron is read in, an IANA name such as Asia/Kolkata. Absent: the user's own, then UTC.
Limits
1 to 64 characters.
Example
Asia/Kolkata
on"call"call: it runs whenever your system posts to its trigger_url, instead of on a schedule.
Type
"call"
filtersmap of anyWith on: call, the fields and values a payload must carry for the routine to run; any other payload is filtered.
Example
{"event":"flight.delayed"}
conversation_idstringAn existing conversation of this user that each run posts into. Absent: the routine gets its own.
Limits
At least 1 character.
deploymentstringFor the routine's own conversation, a deployment by its dep_ id or name. Absent: the user's default, then the company's.
Limits
At least 1 character.
enabledbooleanfalse makes it paused: it keeps its schedule but does not run. Default true.
Default
true
Answers 20117 fields
idstringThe routine's id.
Example
rtn_8f2k
object"routine"Always routine.
Type
"routine"
user_idstring | nullYour id for the user whose Bash runs it; null for your company's own Bash.
Type
string | null
conversation_idstring | nullThe conversation each run posts into, named or made when the routine was; null for a routine not made through the API.
Type
string | null
namestringIts name.
Type
string
askstringWhat Bash is asked on every run.
Type
string
kind"schedule" | "trigger" | "app_event"schedule: it runs on its schedule. trigger: it runs when your system posts to trigger_url. app_event: an event in a connected app runs it.
Type
"schedule" | "trigger" | "app_event"
scheduleobject | nullWhen it runs; null for one that runs on a call.
everystring | nullThe plain words it was given; null for a cron.
Type
string | null
cronstringThe schedule as cron, worked out from every when it was given in words.
Type
string
timezonestringThe zone it runs in, an IANA name.
Type
string
triggerobject | nullFor one that runs on a call, what it listens for; null for one on a schedule.
filtersmap of any | nullWhat a payload must carry for it to run; null: any payload.
Type
map of any | null
trigger_urlstring | nullFor one that runs on a call: POST here, with your key and any JSON object, to run it. Null otherwise.
Type
string | null
enabledbooleanfalse while it is paused.
Type
boolean
status"active" | "completed" | "failed"active: it runs as it should. completed: it has finished and will not run again. failed: it stopped on an error.
Type
"active" | "completed" | "failed"
last_run_atstring | nullWhen it last ran; null when it never has.
Type
string | null
next_run_atstring | nullWhen it runs next; null when paused, finished, or run on a call.
Type
string | null
run_countintegerHow many times it has run.
Type
integer
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
TypeScript
const routine = await vestra.user('traveller-42').routines.create({ ask: 'Check my trips for today.', every: 'weekday at 08:00' });
Python
routine = vestra.user("traveller-42").routines.create("Check my trips for today.", every="weekday at 08:00")
CLI
vestra routines add "Check my trips for today." --every "weekday at 08:00" --user traveller-42
HTTP
# Run on a schedule. Write it in plain words, read in the user's own time zone. The response gives the cron# expression and the next run.curl "$VESTRA_BASE_URL/v1/routines" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "user_id": "traveller-42",    "ask": "Check my trips for today and tell me about any delay.",    "every": "weekday at 08:00"  }' # Run when your system calls. Post a payload to the routine's trigger_url.curl "$VESTRA_BASE_URL/v1/routines" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "user_id": "traveller-42", "ask": "A train of mine is late. Find me another way.", "on": "call" }' curl "$VESTRA_BASE_URL/v1/routines/rtn_7qp/trigger" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "train": "12127", "delay_minutes": 45 }' # Manage a routine. Pause it (enabled: true resumes it), run it once now, and list the user's routines.curl -X PATCH "$VESTRA_BASE_URL/v1/routines/rtn_5kd" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "enabled": false }' curl -X POST "$VESTRA_BASE_URL/v1/routines/rtn_5kd/run" \  -H "Authorization: Bearer $VESTRA_API_KEY" curl "$VESTRA_BASE_URL/v1/routines?user_id=traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY"
MCP
{  "method": "tools/call",  "params": {    "name": "routines_add",    "arguments": {      "user": "traveller-42",      "ask": "Check my trips for today and tell me about any delay.",      "every": "weekday at 08:00",      "timezone": "Asia/Kolkata"    }  }}
GET/v1/routinesThe routines of one user (user_id), or of the company's own Bash.

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

GET/v1/routines/{routine_id}One routine.

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

PATCH/v1/routines/{routine_id}Change what it asks, when it runs (every, schedule or timezone), its filters, or pause and resume it.

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

DELETE/v1/routines/{routine_id}Delete it.

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

POST/v1/routines/{routine_id}/runRun it now.

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

POST/v1/routines/{routine_id}/triggerFire it with a payload from your system: a train delayed, a refund posted.

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

GET/v1/routines/{routine_id}/runsPast runs and the tasks they started.

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