Help: For agent builders
Handling responses
This page is for people who build agents. It lists everything funwatcher can answer and what a well-behaved agent does next. The rule behind all of it: act only on an answer that says proceed, and treat everything else as "do not act".
Every status
The status field of an answer holds one of these values, written as shown in the first column.
| Status | What the agent should do | What can follow |
|---|---|---|
pending |
No answer yet. Do not act. Wait on the request, or tell the user and ask whether to keep waiting. | approved, denied, cancelled, expired |
held |
No answer yet. Do not act. The action is released when the hold ends unless a person cancels it. Wait on the request. | cancelled, released |
approved |
Proceed. If edited_payload is present, act with exactly that payload. Then report the result. | executed, failed |
denied |
Do not act. Tell the user and stop. | Nothing. Final. |
cancelled |
Do not act. Tell the user and stop. | Nothing. Final. |
expired |
Do not act. Nobody decided in time. Tell the user. To ask again, submit a new request with a new idempotency key. | Nothing. Final. |
released |
Proceed. Then report the result. | executed, failed |
executed |
Nothing. This is the result you reported. | Nothing. Final. |
failed |
Nothing. This is the result you reported. | Nothing. Final. |
auto_allowed |
Proceed. Then report the result. | executed, failed |
prohibited |
Do not act. The account's rules forbid this action. Tell the user and stop. Asking again gives the same answer. | Nothing. Final. |
A submission is answered at once with pending, held, auto_allowed or prohibited. The other statuses appear when you read or wait on the request later.
timed_out
The wait route adds timed_out to its answer.
false: the status in the answer is current and, unless it ispendingorheld, it is the answer.true: the wait ended with no change. The status is stillpendingorheld. Do not act. Call the wait route again.
One wait call lasts at most 30 seconds, so waiting for a person means calling it in a loop. Stop looping when the status is anything other than pending or held.
edited_payload
- The field appears on an approved request when the reviewer changed the payload before approving.
- When it is present, carry out the action with exactly the edited payload. Do not merge it with the original and do not fall back to the original.
- When it is absent, or null in the MCP tool's answer, carry out the action with the payload you submitted.
- If you cannot carry out the edited payload, do not act. Report
failedwith the reason indetail.
Reporting the result
- After an attempt on an
approved,releasedorauto_allowedrequest, call the report route once. - Send
outcomeasexecutedif the action was carried out, orfailedif it was attempted and did not succeed. - Add
external_ref(a transaction id, message id or address) anddetailif you have them.
A report on a request in any other status is refused with HTTP 409. A second report on the same request is refused the same way. The report is recorded as the agent's statement. funwatcher cannot confirm it.
Maintenance (HTTP 503)
While maintenance mode is on, every route under /api/v1 answers HTTP 503 with a Retry-After header of 120 seconds and the body {"error": "…", "maintenance": true}, where the error is a sentence for the user.
- Nothing was recorded. Do not act on a request you could not submit.
- Wait for the time in
Retry-Afterand try again. - For a request that was already approved before maintenance began, the approval stands. Report the result when the API answers again.
Other answers
| Code | Meaning | What the agent should do |
|---|---|---|
| 401 | The key is missing, wrong or revoked. | Stop and tell the user. Retrying with the same key does not help. |
| 404 | No such request in this key's account, or the agent id on the webhook route is not this key's agent. | Check the id. Do not act. |
| 409 | The request's status does not allow the call, for example cancelling a decided request or reporting on a pending one. | Read the request's status and follow the table above. |
| 413 | The payload is larger than 65536 bytes. | Send a smaller payload. Do not act until a submission succeeds. |
| 422 | The body is not valid. The answer lists each problem under details. | Fix the body and submit again. |
429 with Retry-After | More than 120 calls in 60 seconds with one key. | Wait for the time in the header. |
429 without Retry-After | The agent already has 25 requests that are pending or held. | Wait for decisions, or cancel requests that are no longer needed. |
Withdrawing a request
If the action is no longer needed while its status is pending or held, call the cancel route. The status becomes cancelled. A request in any other status cannot be cancelled.
For the routes and limits, see API overview. For the same answers through MCP, see MCP tools.
Previous: MCP tools
Next: Troubleshooting
All help pages
Inbox
- Read a request
- Approve, deny or edit a request
- Held actions
- Expired requests and history
- Request statuses
Rules
- How rules work
- The default rules
- Write a rule in plain English
- Build a rule with the form
- Reorder, enable and disable rules
- Suggested rules
- Set a default policy for an agent
- Export your rules
Teams
Ledger
- What the ledger is
- Browse and filter the ledger
- Export and verify the ledger
- Payload retention
- Monthly statements
Billing
Account and security
- Change your password
- Two-factor authentication and recovery codes
- Rotate or revoke an agent key
- How your data is protected
- Closing an account