Help: For agent builders
API overview
This page is for people who connect an agent to funwatcher over HTTP. The agent submits a proposed action before carrying it out, waits for the answer, acts only on that answer and reports what happened. If your agent speaks MCP, there is nothing to write: see Connect an agent and MCP tools.
The machine-readable description of every route is the OpenAPI document at /api/v1/openapi.json.
Authentication
- Register the agent under Agents and copy its key. The key is shown once.
- Send the key on every call in the header
Authorization: Bearerfollowed by the key.
- A key belongs to one agent in one account. Every call sees only that account's requests. A request id from another account answers "Request not found."
- A missing header answers HTTP 401 with "Missing or malformed Authorization header; expected Bearer <agent key>." A wrong or revoked key answers HTTP 401 with "Invalid or revoked agent key."
- Errors are JSON of the form
{"error": "message"}.
The routes
All routes are under /api/v1, take and return JSON, and need the key unless marked public.
| Method | Path | What it does | Possible status codes |
|---|---|---|---|
| POST | /api/v1/requests |
Submit a proposed action | 200, 201, 401, 413, 422, 429 |
| GET | /api/v1/requests/{id} |
Read a request's status | 200, 401, 404, 429 |
| GET | /api/v1/requests/{id}/wait |
Long-poll for a decision | 200, 401, 404, 429 |
| POST | /api/v1/requests/{id}/report |
Report the execution outcome | 200, 401, 404, 409, 422, 429 |
| POST | /api/v1/requests/{id}/cancel |
Withdraw a request | 200, 401, 404, 409, 429 |
| GET | /api/v1/policy/check |
Dry-run the policy | 200, 401, 413, 422, 429 |
| GET | /api/v1/openapi.json |
This document (public, no key needed) | 200 |
| POST | /api/v1/hooks/{agent_id} |
Submit a proposed action from a webhook (n8n, Zapier) | 200, 201, 401, 404, 413, 422, 429 |
Submitting a request
The body of a submission is a JSON object with these fields. Unknown fields are refused.
| Field | Required | Meaning |
|---|---|---|
idempotency_key | yes | Your own unique text for this action. See the rules below. |
action_type | yes | One of: payment, message, delete, post, sign, account_change, other. |
summary | yes | One sentence a person reads to decide. It must not be blank. |
payload | yes | A JSON object with the exact parameters the agent will act with. At most 65536 bytes. |
reversible | yes | true if the action can be undone afterwards, otherwise false. |
counterparty | no | Who or what the action is directed at. |
amount_minor, currency | no | The amount in the currency's minor units (cents, pence) as a whole number, and a three-letter currency code. Send both or neither. |
ttl_seconds | no | How long a pending request waits for a decision before it expires. Default 3600, at most 86400. A larger value is reduced to the maximum. |
The answer carries the request's id, its status, the policy_outcome, an explanation and a poll_url. See Handling responses for what to do with each status.
Idempotency key rules
- Every submission must carry an
idempotency_keyof 1 to 200 characters. - Use a new key for each distinct action, and the same key when you retry the same action.
- A second submission with a key the same agent already used creates nothing. It answers with the same document as the first, with a success code that says "found" in place of "created".
- The body of a retry is not compared with the original. The original request is returned as it is.
- Keys are per agent. Two agents may use the same key for different requests.
Waiting for a decision
- The wait route holds the call open until the request has an answer or the
timeoutyou pass, in seconds, runs out. One call waits at most 30 seconds. A larger value is reduced to that. - The answer includes
timed_out. When it istruethere is no decision yet: call again. - You can poll the status route instead. Waiting is kinder to the rate limit.
The webhook route
The hooks route is for automation platforms such as n8n and Zapier that send a flat body. The agent id in the path must be the agent the key belongs to.
- It accepts
idempotency_key,action_type,summary,counterparty,amount(in minor units),currencyandreversible. - Every other field becomes the payload.
reversibledefaults tofalsewhen it is left out.- Everything else, including the answer and the limits, is the same as a normal submission.
The policy check
The policy check route takes the same body as a submission, sent as JSON on a GET, with idempotency_key optional. It answers with the outcome your rules would give and records nothing: no request, no ledger event and no notification.
Limits
| Limit | Value | When you pass it |
|---|---|---|
| Calls per key | 120 in 60 seconds | HTTP 429 with a Retry-After header saying how many seconds to wait. |
| Requests of one agent that are pending or held at the same time | 25 | HTTP 429. Wait for decisions or cancel some. |
| Payload size | 65536 bytes | HTTP 413. |
What the API does not do
- It never carries out the action and never calls any address found in a payload.
- It cannot check that the agent's summary, amount or payload are true, or that a report of "executed" is true.
- It cannot stop an agent that acts without submitting a request first.
Previous: Connect an agent
Next: MCP tools
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