Routines

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

Send Authorization: Bearer vk_test_... on every call. Every route of Routines.

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.

Request8 fields

Path

routine_idstringrequiredThe routine's id (rtn_...).

Type: string

Body

namestringA new name, up to 200 characters.

Limits: 1 to 200 characters.

askstringWhat Bash is asked on every run from now on, up to 8,000 characters.

Limits: 1 to 8000 characters.

everystringA new schedule. When 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.

Limits: 1 to 100 characters.

timezonestringA new zone, an IANA name, for the schedule it already has or for new plain words.

Limits: 1 to 64 characters.

scheduleobjectA new schedule 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

filtersmap of anyNew filters, for a routine that runs on a call.

Type: map of any

enabledbooleanfalse pauses it; true resumes it.

Type: boolean

Answers 20017 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

await vestra.routines.pause('rtn_5kd');

Python

vestra.routines.pause("rtn_5kd")

CLI

vestra routines pause rtn_5kd

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"    }  }}