Documentation

Early access

Approvals

Tools that cancel an order or send an email run only after the end user says yes, once for each call.

Early access: Hosted tools is turned on per organization. Contact support to have it enabled for yours.

Each hosted tool is marked as one that only reads data or one that changes something. A tool that reads runs as soon as the model asks for it. A tool that changes something (it cancels an order, sends an email, books a slot) runs only after the end user approves that call. There is no setting to skip the question: every call asks.

How a call is approved

  1. The model asks for a tool that changes something. ModelRiver checks the arguments against the tool's schema, as for any call.
  2. The round's other calls, the ones that read, run as usual. Then the request pauses.
  3. Your app receives the call's approval prompt and the arguments you chose to show, over the request's WebSocket channel (and in a webhook, if you have one).
  4. The end user selects Approve or Decline. Your app sends the choice to your backend, which forwards it to ModelRiver with your API key.
  5. When every call of the round is decided, or the wait runs out, the request carries on. Approved calls are sent to your endpoint, once each. The model gets every result of the round in the order it asked for them, and continues.

A declined call, or one nobody answered in time, is not run. The model is told, and carries on; the request does not fail because of it.

The browser never approves anything itself. Approving needs your API key and the end user's id, so it goes through your backend, which already knows who is signed in.


Set up a tool that changes something

On the workflow's Tools tab, open the tool and select Changes something under What does calling it do? Two more fields appear under Approval:

FieldWhat it is
Approval promptThe question the end user sees, as written: Cancel this order? This can't be undone. Up to 300 characters. Required to switch the tool on. It is plain text: no placeholders, and argument values are never put into it
Show to the userThe tool's arguments, one checkbox each. The ones ticked are shown next to the prompt. All of them start ticked, and the console warns you about any you untick, because the user would approve without seeing that value. Up to 16

Only top-level arguments can be shown. An argument the model didn't send is left out rather than shown empty.

Under Limits per request, select Edit. Approval wait (minutes) sets how long a call waits for an answer: 10 minutes by default, from 1 to 60. It appears once the workflow has a tool that changes something. Waiting doesn't count toward the request's Total time.

The tool row shows Changes data · Asks first.

Over the API, the same settings are approval_prompt and approval_fields on each tool, and tool_approval_timeout_ms on the workflow (60000 to 3600000). A tool saved without approval_fields shows all its top-level arguments (the first 16 by name when it has more); only an explicit [] shows none.


Show the approval in your app

Client SDK 1.10.0 and later keep the calls waiting for an answer in pendingApprovals:

TSX
1import { Fragment } from 'react';
2import { useModelRiver } from '@modelriver/client/react';
3 
4function Approvals() {
5 // getToken lets the client rejoin after a reload: a wait can outlast the 5-minute resume token
6 const { pendingApprovals } = useModelRiver({ getToken });
7 
8 // Your route; it knows who is signed in, so the browser sends no user id
9 const decide = (id: string, decision: 'approve' | 'reject') =>
10 fetch(`/api/tool-calls/${encodeURIComponent(id)}/${decision}`, { method: 'POST' });
11 
12 return pendingApprovals.map((approval) => (
13 <div key={approval.id}>
14 {/* Plain text: React escapes it. Never render these as HTML, Markdown or links. */}
15 <p>{approval.prompt}</p>
16 <dl>
17 {Object.entries(approval.arguments).map(([name, value]) => (
18 <Fragment key={name}>
19 <dt>{name}</dt>
20 {/* Show the whole value: a cut-off value can hide what is being approved */}
21 <dd style={{ whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }}>
22 {typeof value === 'string' ? value : JSON.stringify(value)}
23 </dd>
24 </Fragment>
25 ))}
26 </dl>
27 <button onClick={() => decide(approval.id, 'approve')}>Approve</button>
28 <button onClick={() => decide(approval.id, 'reject')}>Decline</button>
29 </div>
30 ));
31}

Each entry of pendingApprovals:

FieldDescription
idThe call's id (tc_…). Send it to your backend
nameThe tool's name
labelThe tool's progress label, or null
roundThe model round the call belongs to
promptThe tool's approval prompt
argumentsOnly the arguments ticked under Show to the user, by name
expires_atWhen the wait ends (ISO 8601)

The values in arguments were written by the model. Show the prompt and every value as plain text, in full and wrapped, never cut off; show values that aren't text as JSON.

The same list is pendingApprovals in the Vue composable and the Svelte store, pendingApprovals$ in the Angular service, and getState().pendingApprovals with the tool_approvals event on ModelRiverClient. An entry leaves the list when the call is decided or expires. The list is kept across a reconnect, and rebuilt from tool_state when the client rejoins, so a reload shows the question again.

The raw WebSocket events are tool_approval_required and tool_approval_resolved; see Progress events.


Send the decision from your backend

Your route checks who is signed in, then calls ModelRiver. The end_user.id must be the one you sent with the request:

JAVASCRIPT
1// Express. requireSignedIn is your own session check.
2app.post('/api/tool-calls/:id/:decision', requireSignedIn, async (req, res) => {
3 const { id, decision } = req.params;
4 if (decision !== 'approve' && decision !== 'reject') return res.sendStatus(404);
5 
6 const response = await fetch(
7 `https://api.modelriver.com/v1/ai/tool-calls/${encodeURIComponent(id)}/${decision}`,
8 {
9 method: 'POST',
10 headers: {
11 Authorization: `Bearer ${process.env.MODELRIVER_API_KEY}`,
12 'Content-Type': 'application/json',
13 },
14 // From your session, never from the browser
15 body: JSON.stringify({ end_user: { id: req.user.id } }),
16 }
17 );
18 res.status(response.status).type(response.headers.get('content-type') ?? 'text/plain').send(await response.text());
19});

POST /v1/ai/tool-calls/:call_id/approve and /reject

Bash
curl -X POST https://api.modelriver.com/v1/ai/tool-calls/tc_3f2a9c1d5b7e4a6f8c0d1e2b/approve \
-H "Authorization: Bearer $MODELRIVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"end_user": {"id": "user_812"}}'
JSON
1{
2 "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",
3 "status": "approved",
4 "decided_at": "2026-11-14T10:12:31Z",
5 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b"
6}

Sending the same decision again returns the same 200, so a double click or a retry is harmless. Errors use the native error format:

StatuserrorWhen
400end_user_requiredNo end_user.id, or it isn't text
400end_user_invalidend_user isn't an object, has fields other than id and claims, has an id over 256 characters, or has claims that break the end_user rules
404tool_call_not_foundThe API key's project has no call with this id that needed approval. The same answer for another project's call, a Playground call, and a call that needed no approval
409end_user_mismatchThe call belongs to a different end_user.id
409tool_call_already_decidedThe call was already decided the other way, or the request was stopped while it waited. details.status is the decision that stands
410tool_approval_expiredThe wait is over; the call was not run
429Rate limit exceededYour API rate limit, per project or per IP address (limit_type). Retry after the Retry-After header. This body has retry_after, window and limit_type instead of details; see Rate limiting

These calls don't count as requests on your plan.

GET /v1/ai/tool-calls/:call_id

For a backend that shows the question itself. Same API key and the same 404 rule:

JSON
1{
2 "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",
3 "status": "pending",
4 "tool": "cancel_order",
5 "prompt": "Cancel this order? This can't be undone.",
6 "arguments": { "order_id": "1041" },
7 "expires_at": "2026-11-14T10:20:00Z",
8 "decided_at": null,
9 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b"
10}

status is pending, approved, rejected or expired. arguments holds only the arguments ticked under Show to the user.


Without the Client SDK: webhook and GET

Older SDK versions ignore the approval events, so the request just seems to take longer. They also keep a stored request for only 5 minutes (60 with getToken), so a reload during a longer wait can't rejoin. To ask the user with them, or from another channel such as email or chat, use the webhook or the GET above from your backend, or upgrade the SDK.

Each enabled webhook of the project receives tool.approval_required for every call that waits, signed like every other delivery:

JSON
1{
2 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b",
3 "timestamp": 1794590623,
4 "data": {
5 "type": "tool.approval_required",
6 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b",
7 "call_id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",
8 "workflow": "support_desk",
9 "tool": "cancel_order",
10 "prompt": "Cancel this order? This can't be undone.",
11 "arguments": { "order_id": "1041" },
12 "end_user_id": "user_812",
13 "expires_at": "2026-11-14T10:20:00Z"
14 }
15}
  • Tell it apart from a response by data.type. It has no callback_url: the call is decided through the endpoints above, never through a callback.
  • A delivery can arrive more than once. Use data.call_id to ignore repeats.
  • It carries only the prompt and the shown arguments, never the other arguments or a secret.
  • A Playground run sends no webhook.

Verify the signature as for any webhook.


What the model is told

In place of a result, the model reads ModelRiver's own fixed text:

Outcomeerror.codeWhat the model reads
Declinedtool_call_rejectedThe user declined this action. Do not try it again unless the user asks.
No answer in timetool_approval_expiredThe user did not respond in time, so this action was not taken.
Outcome unknowntool_outcome_unknownThe tool may or may not have finished. Do not say it succeeded; ask the user to check.
Ran, but the result can't be readNone: not an errorThe action was carried out, but its result could not be read. Do not run it again, and do not say it failed.

How an approved call runs

An approved call is sent at most once. Calls that change something are never retried, and a call is never sent again after it may have reached your endpoint.

Your endpointThe call's statusThe model is told
2xx with JSONokThe result
2xx with anything else, or a result that takes the request over its 256 KB of resultsokThe action was carried out, but its result could not be read. The call's log keeps tool_result_invalid or tool_result_too_large
A body over 32 KBunknowntool_outcome_unknown: the answer is cut off at the limit, so nothing says what your endpoint did
3xx or 4xxerrorThe tool refused (tool_endpoint_error). Redirects are never followed
5xxunknowntool_outcome_unknown: it may have done part of it
No answer within the timeout, or the connection failsunknowntool_outcome_unknown

A call that was never sent is an error with 0 attempts, never unknown. In the log, its approval.status stays approved. Its code says why:

  • tool_timeout: no time was left in the request once it was decided. The model doesn't read this: the request ends with tool_loop_timeout.
  • cancelled: the request was stopped first.
  • tool_resume_failed: the request couldn't carry on after the wait, and ended with tool_resume_failed.
  • tool_unavailable, before anything is sent: hosted tools were turned off, or the workflow was deleted or its tools switched off, during the wait. The request ends with tool_unavailable (see below). The same code marks the call when none of the workflow's models can call tools any more; the request then ends with tool_model_unsupported.
  • tool_unavailable, when the call is made: the project has no signing secret, or the endpoint's address is blocked. The model is told, and the request carries on.

Only the last case sends tool_call_started and tool_call_completed (with status: "error"); the others get neither event. Make your endpoint safe to repeat anyway, and use the call's id (x-modelriver-tool-call-id) to recognise one you already handled. See the endpoint contract.

In your app, unknown means: tell the user it may or may not have happened, and to check before trying again.


Waiting, stopping and limits

  • The wait. Each call waits until its expires_at. Undecided calls then expire and the request carries on. The time spent waiting doesn't count toward the request's total time; the clock starts again where it stopped.
  • Rejoining. The request stays reachable for the whole wait: the channel can be joined again, and POST /v1/ai/reconnect gives a new token, from any server and after a restart.
  • Stopping. A stop (the SDK's cancel()) while calls wait ends the request straight away with error.type: "cancelled". The waiting calls are declined and never run later. A stop that arrives after every call is decided works as for a running request: an approved call not yet sent is not sent, and one already sent is left to finish.
  • Requests waiting at once. A project can have at most 50 requests waiting for approval. While it has 50, a new request to a workflow with a tool that changes something is refused with 429 tool_approvals_limited and Retry-After: 30. A waiting request doesn't count toward the project's running hosted-tools requests.
  • Tool-call limit. A call that changes something counts toward the workflow's tool-call limit when the model asks for it, whatever the end user decides, so a model that keeps asking is stopped.
  • Configuration. The request carries on with the same published revision (or Playground draft) it started with, even if you publish a new one while it waits.

When a waiting request can't carry on

The final response has status: "error", and error.message is "This request could not be completed." for each of these:

error.typeWhat happened
tool_pause_failedThe request couldn't be saved to wait for approval
tool_unavailableHosted tools were turned off, or the workflow was deleted (or couldn't be loaded) or its tools switched off, while it waited. Nothing approved was sent
tool_resume_failedThe request could not carry on after the wait
tool_model_unsupportedNone of the workflow's models can call tools any more (see Which models can run tools). Nothing approved was sent, and no model was called

If your plan's request limit or the project's quota was reached while the request waited, it ends with request_limit_exceeded, as a running request does, and nothing approved is sent.

A request that ends while it waits (it was stopped, or ended with one of the errors above) sends its final response once. If a ModelRiver server fails at that moment, the response may not arrive; the request's log still shows how it ended. So don't let your app wait without limit after the last expires_at.


What counts

  • Each model round counts as one request on your plan, as always. The round that paused is counted when it pauses, so a request that waits and then expires has paid for the rounds it ran, and no more.
  • meta.tool_loop.tool_calls and the Usage API's tool_calls count calls sent to your endpoints. Declined and expired calls are not counted.
  • Approving, declining and the GET are not requests.

In Request Logs

While a request waits, the round that paused is shown on its own in Request Logs, with each waiting call marked Waiting for approval, until its expiry time. Once the request ends, it moves under the request's own log as usual.

The Timeline shows each call's decision and when: Approved by the end user, Declined by the end user, No answer in time, so it was not run, Not run: the request was stopped, or the Playground's own decisions. In the log detail API, each call has an approval object:

JSON
1"approval": {
2 "status": "approved",
3 "decided_at": "2026-11-14T10:12:31Z",
4 "expires_at": "2026-11-14T10:20:00Z",
5 "decided_by": "end_user"
6}

status is pending, approved, rejected or expired; decided_by is end_user, playground, cancel or null. A call that needed no approval has "approval": null. A call's own status can also be awaiting_approval, approved, rejected, expired or unknown.


In the Playground

Calls to a tool that changes something wait in the Playground too. The prompt and the shown arguments appear under the run with Approve and Decline buttons; an approved call gets a mock result, or, when the run sends its tool calls to your CLI, is sent once to your local endpoint. See Testing.


Workflows saved before approvals

  • A tool that changes something can be switched on only once it has an approval prompt, on every save and publish. One without a prompt is never offered to the model.
  • Importing a workflow whose switched-on tool changes something but has no prompt imports that tool switched off, and the import response lists it in warnings with the code write_tool_switched_off. Restoring an old revision as a draft does the same. Add a prompt, then switch the tool on.
  • Send test call doesn't ask for approval: it really calls your endpoint, once, and never retries.

Next steps