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

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

users

Manage the people who use your app. Each one is a user, named by your own id, and Vestra creates them the first time you name them. Here you can give a user a name and time zone, cap what they spend, export everything Vestra holds about them, or erase them.

Create a user

Do it before their first ask to set their name and time zone. It is safe to repeat.

TypeScript
await vestra.users.create('traveller-42', { name: 'Priya Sharma', timezone: 'Asia/Kolkata' });

Read their spend

Their profile shows what they spent this month, and what is left under their cap.

TypeScript
const traveller = vestra.user('traveller-42');const profile = await traveller.get();console.log(profile.spend_month_usd, profile.caps_remaining.month_usd);

Set a monthly cap

Then wake their computer, and export everything Vestra holds about them.

TypeScript
await traveller.update({ monthly_cap_usd: 20 });await traveller.warm(); // wake their computer before they need itconsole.log(await traveller.export());

Erase a user

It runs as a job: deleted is false and status is deleting until user.deleted says it is done.

TypeScript
const erasing = await traveller.delete();console.log(erasing.deleted, erasing.status);

List your users

TypeScript
const page = await vestra.users.list();console.log(page.data.length);

Create a user

Do it before their first ask to set their name and time zone. It is safe to repeat.

Python
vestra.users.create("traveller-42", name="Priya Sharma", timezone="Asia/Kolkata")

Read their spend

Their profile shows what they spent this month, and what is left under their cap.

Python
traveller = vestra.user("traveller-42")profile = traveller.get()print(profile.spend_month_usd, profile.caps_remaining.month_usd)

Set a monthly cap

Then wake their computer, and export everything Vestra holds about them.

Python
traveller.update(monthly_cap_usd=20)traveller.warm()  # wake their computer before they need itprint(traveller.export())

Erase a user

It runs as a job: deleted is False and status is deleting until user.deleted says it is done.

Python
erasing = traveller.delete()print(erasing.deleted, erasing.status)

List your users

Python
print(len(vestra.users.list().data))

List your users

CLI
vestra users

Read their spend

You see what one user spent, and what is left this month.

CLI
vestra users traveller-42

Set a monthly cap

Then export everything Vestra holds about them, and wake their computer.

CLI
vestra users traveller-42 --cap 20vestra users export traveller-42vestra users warm traveller-42

Erase a user

It runs as a job, and user.deleted says when it is done.

CLI
vestra users delete traveller-42 --yes

Create a user

Do it before their first ask to set their name and time zone. It is safe to repeat with the same user_id.

HTTP
curl "$VESTRA_BASE_URL/v1/users" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "user_id": "traveller-42", "name": "Priya Sharma", "timezone": "Asia/Kolkata" }'

Read their spend

Their profile shows what they spent today and this month, against their caps.

HTTP
curl "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY"

Set a monthly cap

This one is 20 US dollars.

HTTP
curl -X PATCH "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "monthly_cap_usd": 20 }'

Wake their computer

Do it before they need it.

HTTP
curl -X POST "$VESTRA_BASE_URL/v1/users/traveller-42/warm" \  -H "Authorization: Bearer $VESTRA_API_KEY"

Open a page in their browser with no model

And keep the page's own data calls. The site must be in their deployment's browser.allowed_domains.

HTTP
curl -X POST "$VESTRA_BASE_URL/v1/users/traveller-42/browser/fetch" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "url": "https://www.ixigo.com/search/result/flight?from=DEL&to=GOI&date=06112026&adults=2&class=e", "capture": [{ "match": "/flights/v2/search/stream" }] }'

Erase a user

It runs as a job: the response is 202 with deleted false and status deleting, and then user.deleted says it is done.

HTTP
curl -X DELETE "$VESTRA_BASE_URL/v1/users/traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY"
MCP
{  "method": "tools/call",  "params": {    "name": "users_get",    "arguments": { "user": "traveller-42" }  }}

Good to know

User ids

Your id for a user is 1 to 128 characters and starts with a letter or digit. Reading a user never creates one. An unknown id on a read returns 404.

Erasing a user

DELETE /v1/users/{id} returns 202 with deleted: false and status: deleting. Vestra erases their computer, files and memory in the background, and the user.deleted event says when it is done.

Spending

A user's record shows what they spent today and this month, and how much they can still spend under their caps.

The key you need

Exporting or erasing a user needs a key with the admin scope, or all.

A page's own data, with no model

POST /v1/users/{id}/browser/fetch opens one page in a tab of the user's browser, with their sign-ins, and gives back the bodies of the page's own data calls that match capture. It can click, type, scroll and wait first (steps), and call the deployment's sites from inside the page (page_fetch). keep_open_ms keeps the tab, so the next fetch sends no url and runs there at once. It opens only sites in browser.allowed_domains, never a page in browser.blocked_paths such as a payment page (403 page_blocked), yields to a person with 409 browser_in_use, and answers a slow page with 504 timeout and what came in partial. POST /v1/users/{id}/warm with keep_ms keeps the computer awake for the next one.

The routes behind users9 routes, each with every field in the API reference
POST/v1/usersCreate one of your users, or return the existing one. Safe to repeat with the same user_id.Key scope: admin (or all)
GET/v1/usersList your users.Key scope: runtime (or all)
GET/v1/users/{user_id}One user: status, profile, memory mode, default deployment, and what they spent today and this month against their caps.Key scope: runtime (or all)
PATCH/v1/users/{user_id}Change name, language, time zone, metadata, day or month spend cap, default deployment, or status (active or disabled).Key scope: admin (or all)
DELETE/v1/users/{user_id}Erase the user and everything Bash holds for them: computer, files, memory. Runs as a job; a webhook says when it is done.Key scope: admin (or all)
POST/v1/users/{user_id}/exportPackage everything held for the user into one download, for data-rights requests.Key scope: admin (or all)
POST/v1/users/{user_id}/warmWake the user's computer now (for example when they open your app), so their next task starts without waiting. Answers 200 when it is already up and 202 while it wakes. At most 10 computers wake at once per company (429 warm_limit), and a second call for one user within a minute rides the first. keep_ms keeps it awake that long once it is up, up to two minutes; calling again extends it.Key scope: runtime (or all)
POST/v1/users/{user_id}/browser/fetchOpen one page in a background tab of the user's own browser, with no model, and get back the bodies of the page's own data calls that match capture. Only on sites the user's deployment lists in browser.allowed_domains (403 domain_not_allowed), and never on a page in its browser.blocked_paths, such as a payment page (403 page_blocked). Wakes the computer when it sleeps. Answers as soon as every required capture has its responses, with timings; 409 browser_in_use while a person drives the browser, 409 browser_busy past four at once; 504 timeout carries what came back in partial. frames returns small pictures of the tab at each milestone. A page_fetch step calls one of the deployment's sites from inside the page, as the page's own script would; keep_open_ms keeps the tab for the next fetch, which sends no url (409 no_open_tab when none is kept).Key scope: runtime (or all)
GET/v1/users/{user_id}/browser/cookiesWhich cookies of some names the user's browser holds for one site, and until when: names, sites and expiry only, never a value. Only a site on the deployment's browser.allowed_domains (403 domain_not_allowed). Opens no page and acts on nothing, so it never disturbs a person using the browser: read it every few seconds to see a person finish signing in on a page you handed them (front), as the site's session cookie appears or its expiry moves on. Wakes the computer when it sleeps.Key scope: runtime (or all)