Docs & API

Everything is a plain HTTP call. No SDK, no signup.

1. Create a bin

POST https://catchr.perch-app.workers.dev/api/bins
# optional JSON body: {"name":"my test"}
→ 200 {"id":"a1b2c3d4","url":"https://catchr.perch-app.workers.dev/h/a1b2c3d4",
       "inspect_url":"https://catchr.perch-app.workers.dev/i/a1b2c3d4?t=TOKEN","token":"TOKEN"}

Keep token — it's how you read requests back and delete the bin. Anyone with the url can send to it; only the token can read.

2. Send anything to the bin

curl -X POST https://catchr.perch-app.workers.dev/h/a1b2c3d4/any/path -d '{"event":"ping"}' \
     -H 'content-type: application/json'

Any method (GET/POST/PUT/PATCH/DELETE/…), any sub-path, any headers/body. Catchr stores it and replies 200 {"ok":true}.

3. Read captured requests (JSON)

GET https://catchr.perch-app.workers.dev/api/bins/a1b2c3d4/requests?token=TOKEN&limit=50
→ {"bin":"a1b2c3d4","count":1,"requests":[
     {"method":"POST","path":"/any/path","query":"",
      "headers":{...},"body":"{\"event\":\"ping\"}","size":16,"ts":1699999999999}]}

Newest first. Great for CI/agents: create a bin, trigger your webhook, and assert on the payload.

3b. Wait for a request (long-poll — no polling loop)

GET https://catchr.perch-app.workers.dev/api/bins/a1b2c3d4/requests?token=TOKEN&wait=15
# blocks up to 15s (max 25) and returns the instant a request arrives.
# Add &since=<ts> to only wake for requests newer than a timestamp
# you already saw — perfect for create → trigger → await-assert in CI.

This is the wedge for automated tests & agents: no sleep/retry loop — one blocking call returns as soon as the webhook lands, or empty on timeout.

3c. Custom response (mock any status/body)

POST https://catchr.perch-app.workers.dev/api/bins/a1b2c3d4/response?token=TOKEN
# JSON body: {"status":500,"content_type":"application/json",
#             "body":"{\"error\":\"boom\"}"}
# now the bin returns THAT to whatever hits its /h URL —
# test how your sender handles a 500, a specific JSON reply, etc.
DELETE https://catchr.perch-app.workers.dev/api/bins/a1b2c3d4/response?token=TOKEN   # back to default 200

Turns a bin into a configurable mock endpoint — verify your webhook's retry/error handling without standing up a fake server. Status 100–599, body up to 16 KB. Still inbound-only: Catchr only shapes its own reply, never fires a request on your behalf.

4. Manage

DELETE https://catchr.perch-app.workers.dev/api/bins/a1b2c3d4/requests?token=TOKEN   # clear
DELETE https://catchr.perch-app.workers.dev/api/bins/a1b2c3d4?token=TOKEN            # delete bin

🔌 MCP server (for AI agents)

Catchr is also a remote Model Context Protocol server, so an AI coding agent can test the very webhooks and tool-callbacks it builds. Add it to any MCP client (Claude Desktop, Cursor, etc.) as a Streamable HTTP server:

{
  "mcpServers": {
    "catchr": { "url": "https://catchr.perch-app.workers.dev/mcp" }
  }
}

No auth to connect — each bin carries its own token. Tools exposed:

create_bin   → returns a live capture URL + token
get_requests → read captured requests; set wait to block
               until one arrives (create → trigger → assert)
set_response → make the bin return a chosen status/body
               (mock a 500, a specific JSON reply, …)
clear_bin    → wipe a bin's captured requests

JSON-RPC 2.0 over a single POST to https://catchr.perch-app.workers.dev/mcp.

Limits

Bodies stored up to 64 KB · last 100 requests kept per bin · bins pruned after 14 days of inactivity · free.

Machine-readable specs: /openapi.json · /llms.txt · MCP: /mcp