Interactions

What Bash waits on (approvals, questions, apps to connect, hand-offs, calls to your tools) and the answers.

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

RoutesOpen one for every field it takes and answers.

GET/v1/interactionsEverything Bash waits on, across your users: approvals, questions, app connections, hand-offs, and calls to your client tools (type tool_call).

Filter by user_id, conversation_id, task_id, type or status (pending by default).

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

Request8 fields

Query

limitintegerHow many items per page, 1 to 100. Default 20.

Type: integer

cursorstringWhere to go on from: the next_cursor of the page before, unchanged. Absent: the first page.

Type: string

user_idstringOnly this user's, by your id for them.

Type: string

conversation_idstringOnly this conversation's (conv_...).

Type: string

task_idstringOnly this task's (task_...).

Type: string

type"approval" | "question" | "connect" | "handoff" | "tool_call"Only this type. Absent: every type, calls to your tools included. tool_call: those calls alone.

Type: "approval" | "question" | "connect" | "handoff" | "tool_call"

Type: "ask_question" | "composio_auth" | "tool_permission" | "credit_approval" | "exit_plan" | "custom" | "hands_approval" | "plan_limit"

status"pending" | "resolved" | "cancelled" | "expired"Only this status. Default: pending, what Bash waits on now.

Type: "pending" | "resolved" | "cancelled" | "expired"

Answers 2002 fields

dataobject[]The items on this page.

object"interaction"Always interaction.

Type: "interaction"

idstringThe interaction, to answer by its id (int_...; call_... for a call to your tool).

Example: int_3j9

user_idstring | nullYour id for the user it is for; null on your company's own Bash.

Type: string | null

task_idstring | nullThe task that asked (task_...); null for a call to your tool that Bash's reply made.

Type: string | null

conversation_idstring | nullIts conversation (conv_...); null when its task has none.

Type: string | null

kind"ask_question" | "composio_auth" | "tool_permission" | "credit_approval" | "exit_plan" | "custom" | "hands_approval" | "plan_limit"What exactly Bash waits on. ask_question: a question, or a hand-off. composio_auth: connecting an app. tool_permission: a step with a tool. credit_approval: spending on a paid tool. exit_plan: a plan before it starts. hands_approval: an action on a computer, approved in person. plan_limit: a plan's limit ran out (read only). custom: anything else, named by details.renderer.

Type: "ask_question" | "composio_auth" | "tool_permission" | "credit_approval" | "exit_plan" | "custom" | "hands_approval" | "plan_limit"

type"approval" | "question" | "connect" | "handoff" | "tool_call"What kind of answer it takes. approval: yes or no. question: an answer to each question. connect: your user connects an app. handoff: a person does one thing, then says so. tool_call: your tool returns an output or an error.

Type: "approval" | "question" | "connect" | "handoff" | "tool_call"

status"pending" | "resolved" | "cancelled" | "expired"pending: Bash waits on it. resolved: it was answered. cancelled: it was withdrawn before an answer. expired: nobody answered in time.

Type: "pending" | "resolved" | "cancelled" | "expired"

summarystringWhat Bash wants, in a phrase to show your user.

Example: pay, amount $500.00

moves_moneyboolean | nullWhether saying yes spends money, such as a payment. null on the card for one of your own tools (a function of yours, or a tool of your MCP servers): your app knows what your tools cost, and Vestra cannot.

Type: boolean | null

requires_present_userbooleanWhether a yes needs present_user: true, meaning the person who saw it said yes: true for a payment, and for an action approved in person.

Type: boolean

noncestringmay be absentFor an action approved in person (hands_approval) only: send it back with your yes.

Type: string

questionsobject[]may be absentFor a question or a hand-off: what Bash asks, one or more questions.

questionstringThe question, as Bash asks it.

Example: Which flight should I book?

headerstringA short label for it, for a heading or a chip; empty when Bash gave none.

Type: string

optionsobject[]Answers Bash suggests; your user may still answer in their own words. Empty when it suggests none.

Type: object[]

multi_selectbooleanWhether more than one option may be picked.

Type: boolean

frame_urlstringmay be absentFor a hand-off, on a single read only (never in lists): the page Bash was on when it asked, as a JPEG data URI.

Type: string

browserobjectmay be absentFor a hand-off in the browser: open a session with a screen (POST /v1/sessions) so a person can do it.

suggested_mode"control"Open the screen with control, so the person can take the wheel.

Type: "control"

urlstring | nullThe page Bash's browser is on; null when it did not say.

Type: string | null

detailsmap of anyA few named facts for its kind, safe to show: such as tool_name and rows for a tool step (with server for a tool of an MCP server, and its arguments as rows), or app for a connection. Never the raw request.

Type: map of any

outcomeobject | nullHow it ended; null while it is pending.

decision"approved" | "denied" | "answered" | "cancelled" | "expired"How it ended.

Type: "approved" | "denied" | "answered" | "cancelled" | "expired"

answersstring[]may be absentFor an answered question: the answer to each question, in order.

Type: string[]

reasonstringmay be absentFor a denial: why, when one was recorded.

Type: string

messagestringmay be absentFor a denial: the note that was sent with the no, when there was one.

Type: string

created_atstringWhen Bash asked, as an ISO 8601 time.

Type: string

expires_atstring | nullWhen it expires unanswered, as an ISO 8601 time; null when it never does.

Type: string | null

resolved_atstring | nullWhen it was answered, withdrawn or expired, as an ISO 8601 time; null while pending.

Type: string | null

next_cursorstring | nullSend it as cursor for the next page; null on the last page.

Type: string | null

TypeScript

const waiting = await vestra.answer.list();

Python

waiting = vestra.answer.list()

CLI

vestra answer

HTTP

# List what Bash is waiting on. For one user, this lists approvals, questions, hand-offs, apps to connect and# calls to your tools.curl "$VESTRA_BASE_URL/v1/interactions?user_id=traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Approve or deny. A payment or hands-on approval needs present_user: true, and a hands-on approval also needs# its nonce. To say no, send approve: false.curl "$VESTRA_BASE_URL/v1/interactions/int_3j9/answer" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "approve": true, "present_user": true }' # Answer a question. Send one answer per question.curl "$VESTRA_BASE_URL/v1/interactions/int_7qp/answer" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "answers": ["The 09:15 flight"] }' # Return your tool's result. Answer a call to one of your tools with its output, or an error.curl "$VESTRA_BASE_URL/v1/interactions/call_4mz/answer" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "output": { "status": "confirmed", "pnr": "100042" } }'

MCP

{  "method": "tools/call",  "params": {    "name": "answer",    "arguments": { "interaction": "int_3j9", "approve": true, "present_user": true }  }}

GET/v1/interactions/{interaction_id}One item, by its int_ or call_ id: its type (approval, question, connect, handoff, tool_call), what Bash wants to do, the options, when it expires.

A handoff carries a snapshot of the page.

Your API key, or a session's token, scope runtime or all. On the card: answer. Every call here is a checked sample.

Every field it takes and answers, and its code

POST/v1/interactions/{interaction_id}/answerAnswer it, whatever it is.

An approval takes approve (true or false), a question answers or approve: false, a hand-off done, could_not or not_now (or answers, when it asks for a value such as a code), a client tool call output or error. A money or account approval, and the yes to a company action (a tool of your MCP servers, or a function of yours that is not read-only or run without asking), must carry present_user: true. A body that fits another kind is 400 answer_mismatch.

Your API key, or a session's token, scope runtime or all. On the card: answer. Every call here is a checked sample.

Every field it takes and answers, and its code

POST/v1/interactions/{interaction_id}/cancelWithdraw it.

The task carries on without that action.

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

Every field it takes and answers, and its code

NextFiles