Requests

What an agent sends, what comes back, and the one field it may act on.

A request is one question from an agent: may I do this? It is answered once, and the answer never changes.

What the agent sends

agent
The agent's name, the same every time, 1 to 200 characters.
action
A short machine-friendly name such as email.send. Rules match on it.
summary
One plain sentence for the person deciding, up to 2,000 characters.
details
Optional. A JSON object with supporting facts: the message text, the code change, the items. See How details are shown.
amount
Optional. The money the action would move, as a number or a string such as "129.00", with at most 4 decimals. Rules with a limit go by it. Needs currency.
currency
Optional. The three-letter code of the amount, such as EUR.
wait_seconds
Optional. Wait up to this many seconds (0 to 30) for a decision, and answer as soon as it is made.
ttl_seconds
Optional. How long to wait, 10 seconds to 7 days. Default 15 minutes.

What comes back

id
The request's id, to read the answer with later.
status
pending, approved, denied, expired or withdrawn.
allowed
The only field an agent should act on. True only after an approval, and never while the workspace or the agent's key is paused.
amount, currency
The amount the request stated, when it stated one.
approved_summary, approved_amount
Once approved, what the agent may do: the wording to act on, and the most money it may move, in currency. Act on these, never on summary and amount.
changed
True when the person approved a narrower version than the agent asked: new wording, a lower amount, or both.
paused, pause
paused is true while a person has paused the workspace or this agent's key; pause then says which, workspace or agent.
key_name
The name of the key the request was made with, as an owner wrote it.
decided_by
Email of the person who decided, or who wrote the rule that did.
by_rule
True when a standing rule made the decision.
approvals_needed, approvals
How many different people must approve, and who has so far. One denial is enough to stop it.
decision_note
The reason, if the person gave one.
expires_at
When the request stops accepting a decision.
outcome, outcome_note
How the approved action went, once the agent reported it: succeeded or failed.

The one rule

Only allowed: true means go. Everything else means stop.

  • A decision is final. Nobody can turn an approval into a denial.
  • A request nobody answers in time expires and can no longer be approved.
  • An agent key can ask, and read, withdraw or report on its own requests. It cannot see another key’s requests, list the inbox, decide, or change any setting.
  • An agent in one workspace can never see a request from another.

Approved with changes

The person deciding can change what is approved before approving it: reword the summary, or lower the amount. The agent may then do only the changed version. The answer has changed: true, and approved_summary and approved_amount hold what was approved, while summary and amount keep what was asked, for the record.

  • A change only ever narrows. The amount can go down or stay the same, in the same currency. It can never go up, and a request that stated no amount cannot be given one.
  • Only an approval can carry changes, not a denial.
  • Changes apply to that one request, so they cannot be remembered as a rule.
  • When a request needs several people, everyone approves the same changes. An approval with different changes, or none after the first made some, is refused and not counted: approve the same version, or deny it.
  • A budget counts what was approved, so a lowered amount uses up only the lower amount.

An agent that can only do what it asked must not act on a changed approval. The TypeScript guard does nothing in that case unless told it can, variantgate run does not run its command, and the hooks deny the tool call.

Waiting for the answer

Pass wait_seconds when asking or reading, and the call stays open until a person decides or the time is up, for at most 30 seconds. One call usually brings the answer, and none of the waiting counts against the rate limit.

curl 'https://api.variantgate.com/v1/requests/REQUEST_ID?wait_seconds=30' \
  -H 'authorization: Bearer gl_YOUR_KEY'

Taking a request back

If the plan changes before anyone decides, the agent withdraws the request. It leaves the inbox, nobody can approve it any more, and the record shows it was withdrawn.

curl -X POST https://api.variantgate.com/v1/requests/REQUEST_ID/withdraw \
  -H 'authorization: Bearer gl_YOUR_KEY'

Saying how it went

An approval says an action may happen. After acting, the agent reports whether it did, once, with a short note such as a message id or an error. The record then shows both: who allowed it, and what came of it.

curl -X POST https://api.variantgate.com/v1/requests/REQUEST_ID/outcome \
  -H 'authorization: Bearer gl_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{ "outcome": "succeeded", "note": "Sent as message 4411" }'

Only the key that asked can withdraw a request or report its outcome.

Two names

An agent picks its own name, so agent can say anything. The key it asked with has a name too, written by an owner, and the agent cannot change that one. When the two differ, the inbox and the record show both, and rules always go by the key.

Finding a request

Above the inbox, one row narrows the list: by agent key, by action (email.send, or email.* for a family), and by an amount it must be above, in whatever currency each request states. The record has the same row, with a search box. Both keep what you chose in the address, so a filtered view can be bookmarked or shared.

Keyboard shortcuts

The inbox can be worked without a mouse. Press ? to see every shortcut. None of them fire while you type in a field, or with Ctrl, Cmd or Alt held.

j and k
Move to the next or the previous request.
Enter
Open the selected request on its own.
a
Approve, exactly as the Approve button does.
d
Deny.
e
Edit the request, then approve the changed version.
/
Go to the search box, or the filters in the inbox.
g, then a letter
Go to a section: i for the inbox, n insights, r the record, u rules, a agents, p people, s settings.

A shortcut presses the same button a click would. A request that needs two people still waits for the second, and a request a rule sends to someone else still cannot be decided by anyone but them and the owners.

Writing a good summary

The person deciding reads the summary first, often on a phone. Say exactly what will happen, with the amount, the recipient or the number of things affected.

Weak
Send email
Strong
Send the March invoice (€1,240.00) to billing@acme.example
Weak
Clean up files
Strong
Delete 214 files in /exports/2024, 1.8 GB in total

How details are shown

The inbox shows details as the agent sent them, so the person deciding reads exactly what they approve. Everything is shown as text: HTML and markdown in a value are never interpreted.

  • Text keeps its line breaks and spacing. Text longer than about eight lines starts collapsed, with a button to show all of it.
  • A field whose name says it holds code, such as sql, query, command, script, json or yaml, also with words around it as in raw_sql, is set in a fixed-width font.
  • Text in unified diff format, as git diff writes it, is shown as a diff: added lines green with their +, removed lines red with their -.
  • http and https addresses become links that read as the whole address. Nothing else is linked.
  • An object is shown indented under its name. A list of plain values is a list; a list of objects with the same few keys (up to five) is a table, and other lists are numbered.
  • Past four levels the rest is shown as JSON. A list longer than 50 shows the first 50, says how many more there are, and shows them on a click.

Tips for agents

  • Put the text of a message in a field such as body, whole, not a description of it.
  • Put a code change in diff as a unified diff, SQL in sql, and a shell command in command.
  • Send items, such as order lines or files, as a list of objects with the same keys.
  • Details share the request’s 64 KB limit. For something larger, send the first part and say how much is left out.
{
  "details": {
    "body": "Hi Ana,\n\nSorry the lamp arrived broken. We have refunded €129.00 to your card; it shows within 5 days.\n\nYour order: https://shop.example/orders/4471\n\nBest,\nNorthwind support",
    "lines": [
      {
        "item": "Desk lamp",
        "price": "109.00",
        "qty": 1
      },
      {
        "item": "Bulb, warm",
        "price": "10.00",
        "qty": 2
      }
    ],
    "order": "4471",
    "to": "ana@customer.example"
  }
}

support-agent

refund.create · asked just now

14 min

Refund Ana €129.00 for order 4471 and email her

€129.00as stated by the agent

body

Hi Ana, Sorry the lamp arrived broken. We have refunded €129.00 to your card; it shows within 5 days. Your order: https://shop.example/orders/4471 (opens in a new tab) Best, Northwind support

lines
itempriceqty
Desk lamp109.001
Bulb, warm10.002
order

4471

to

ana@customer.example

How this request looks in the inbox, with example values.