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
- The model asks for a tool that changes something. ModelRiver checks the arguments against the tool's schema, as for any call.
- The round's other calls, the ones that read, run as usual. Then the request pauses.
- 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).
- The end user selects Approve or Decline. Your app sends the choice to your backend, which forwards it to ModelRiver with your API key.
- 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:
| Field | What it is |
|---|---|
| Approval prompt | The 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 user | The 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:
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 token6 const { pendingApprovals } = useModelRiver({ getToken });7 8 // Your route; it knows who is signed in, so the browser sends no user id9 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:
| Field | Description |
|---|---|
id | The call's id (tc_…). Send it to your backend |
name | The tool's name |
label | The tool's progress label, or null |
round | The model round the call belongs to |
prompt | The tool's approval prompt |
arguments | Only the arguments ticked under Show to the user, by name |
expires_at | When 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:
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 browser15 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
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"}}'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:
| Status | error | When |
|---|---|---|
| 400 | end_user_required | No end_user.id, or it isn't text |
| 400 | end_user_invalid | end_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 |
| 404 | tool_call_not_found | The 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 |
| 409 | end_user_mismatch | The call belongs to a different end_user.id |
| 409 | tool_call_already_decided | The call was already decided the other way, or the request was stopped while it waited. details.status is the decision that stands |
| 410 | tool_approval_expired | The wait is over; the call was not run |
| 429 | Rate limit exceeded | Your 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:
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:
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 nocallback_url: the call is decided through the endpoints above, never through a callback. - A delivery can arrive more than once. Use
data.call_idto 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:
| Outcome | error.code | What the model reads |
|---|---|---|
| Declined | tool_call_rejected | The user declined this action. Do not try it again unless the user asks. |
| No answer in time | tool_approval_expired | The user did not respond in time, so this action was not taken. |
| Outcome unknown | tool_outcome_unknown | The tool may or may not have finished. Do not say it succeeded; ask the user to check. |
| Ran, but the result can't be read | None: not an error | The 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 endpoint | The call's status | The model is told |
|---|---|---|
2xx with JSON | ok | The result |
2xx with anything else, or a result that takes the request over its 256 KB of results | ok | The 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 KB | unknown | tool_outcome_unknown: the answer is cut off at the limit, so nothing says what your endpoint did |
3xx or 4xx | error | The tool refused (tool_endpoint_error). Redirects are never followed |
5xx | unknown | tool_outcome_unknown: it may have done part of it |
| No answer within the timeout, or the connection fails | unknown | tool_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 withtool_loop_timeout.cancelled: the request was stopped first.tool_resume_failed: the request couldn't carry on after the wait, and ended withtool_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 withtool_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 withtool_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/reconnectgives 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 witherror.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_limitedandRetry-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.type | What happened |
|---|---|
tool_pause_failed | The request couldn't be saved to wait for approval |
tool_unavailable | Hosted 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_failed | The request could not carry on after the wait |
tool_model_unsupported | None 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_callsand the Usage API'stool_callscount calls sent to your endpoints. Declined and expired calls are not counted.- Approving, declining and the
GETare 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:
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
warningswith the codewrite_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
- Endpoint contract: what your endpoint receives, and how calls that change something are sent
- Security: what to trust, and what the browser sees
- Progress events: every event and status
- Testing: approve and decline in the Playground