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

  1. Register the agent under Agents and copy its key. The key is shown once.
  2. Send the key on every call in the header Authorization: Bearer followed by the key.

The routes

All routes are under /api/v1, take and return JSON, and need the key unless marked public.

MethodPathWhat it doesPossible 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.

FieldRequiredMeaning
idempotency_keyyesYour own unique text for this action. See the rules below.
action_typeyesOne of: payment, message, delete, post, sign, account_change, other.
summaryyesOne sentence a person reads to decide. It must not be blank.
payloadyesA JSON object with the exact parameters the agent will act with. At most 65536 bytes.
reversibleyestrue if the action can be undone afterwards, otherwise false.
counterpartynoWho or what the action is directed at.
amount_minor, currencynoThe amount in the currency's minor units (cents, pence) as a whole number, and a three-letter currency code. Send both or neither.
ttl_secondsnoHow 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

Waiting for a decision

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.

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

LimitValueWhen you pass it
Calls per key120 in 60 secondsHTTP 429 with a Retry-After header saying how many seconds to wait.
Requests of one agent that are pending or held at the same time25HTTP 429. Wait for decisions or cancel some.
Payload size65536 bytesHTTP 413.

What the API does not do

Previous:
Next:

All help pages

Inbox

Rules

Teams

Ledger

Billing

Account and security

For agent builders

Troubleshooting