Small API.
Stable contract.

API versioning

Management endpoints use /api/v1. Compatible fields may be added within v1, but existing fields and behavior will not be removed or changed incompatibly. A breaking contract change will use a new major path. Capture URLs remain /b/:binId/* so webhook destinations do not change when the management API evolves.

Install the CLI

curl -fsS https://freebin.org/freebin.mjs -o freebin.mjs
chmod +x freebin.mjs
FREEBIN_API_KEY=YOUR_API_KEY ./freebin.mjs bins

The CLI supports bins, create, send, requests, watch, export, replay, local-forward, assert, and delete-request. Watch and local-forward emit JSON lines and accept --include-existing. Local forwarding runs in the CLI, so it can reach localhost while still stripping authorization, cookies, credential-like, hop-by-hop, and source-address headers. Set FREEBIN_URL=http://127.0.0.1:8787 for local development.

./freebin.mjs assert BIN_ID --method POST --path '/webhooks/*' \
  --header x-event=invoice.created --body-json data.status=paid --timeout 30

Assertions combine method, path glob, repeated header, repeated body substring, and repeated JSON dot-path predicates with AND semantics. Exit code 0 indicates a match, 2 a timeout, and 1 a usage or operational error.

Connect an MCP client

{
  "mcpServers": {
    "freebin": {
      "url": "https://freebin.org/mcp"
    }
  }
}

The stateless Streamable HTTP server provides list_bins, list_requests, get_request, and replay_request. OAuth-capable clients discover Freebin automatically, use authorization code flow with S256 PKCE, and show an explicit consent screen for read and replay scopes. Account API keys remain a compatibility option through a custom bearer header. Both methods return owned bins only. Request bodies are bounded before entering model context, and replay uses the same destination allowlist, egress limits, retention, sensitive-header stripping, and mutation audit trail as the browser and API.

Create a bin

curl -X POST https://freebin.org/api/v1/bins \
  -H "authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Payments dev","termsAccepted":true}'

Send a request

curl -X POST https://freebin.org/b/YOUR_BIN_ID/events \
  -H "authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"status":"ok"}'

List captured requests

curl "https://freebin.org/api/v1/bins/YOUR_BIN_ID/interactions?limit=50" \
  -H "authorization: Bearer YOUR_API_KEY"

Inspector filtering

The browser inspector filters its loaded retained history by free text, HTTP method, capture time range, path, content type, header name and value, and dotted JSON body fields. Filter and paging state is encoded in the URL and restored by browser history, making a filtered inspector URL shareable with another authorized user. Named saved views are planned for a later phase.

Portable bin configuration

Export a versioned document containing the bin name, fallback response, forwarding configuration, and ordered conditional response rules. The document excludes captures, replay history, account ownership, Freebin API keys, public-share tokens, rule IDs and revisions, and internal enforcement metadata. User-authored response bodies, headers, destinations, and rule values may still be sensitive, so review a file before sharing it.

curl https://freebin.org/api/v1/bins/YOUR_BIN_ID/config \
  -H "authorization: Bearer YOUR_API_KEY" \
  -o freebin-config.json

curl -X PUT https://freebin.org/api/v1/bins/OTHER_BIN_ID/config \
  -H "authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  --data-binary @freebin-config.json

Imports replace the destination bin’s portable fields and all rules atomically while preserving its captured requests and replay attempts. Local rule IDs and revisions are regenerated. The import must satisfy the destination account’s limits, and enabled forwarding must target an origin permitted by that deployment. Validate files against bin-config.v1.json.

Authentication

Send an account API key as Authorization: Bearer YOUR_API_KEY. Keys are user-scoped, shown only once, individually revocable, and limited to five active keys per account. Every capture method requires a key belonging to the destination bin’s owner.

Complete endpoint reference

All currently implemented API and capture endpoints are listed below. Public share URLs are read-only web pages rather than JSON API endpoints.

Documented service limits

Retention is byte-based across captures and replay history. Old replay attempts are evicted before captured requests when the account reaches its allowance. There is no date-based cleanup. Rate-limited requests return 429; oversized requests return 413.

Automatic forwarding is best-effort: one destination per bin, a 10-second timeout, no redirects, and no retries. Each captured request has separate pending, delivered, or failed attempt history with destination, response code, error, latency, and timestamps; the request-level fields summarize the latest result. The original path and query are appended to the configured base URL. Credential-like headers are stripped by default and may be retained with a per-bin allowlist. Authorization is always removed because it contains the Freebin API key; hop-by-hop and source-address headers are also never forwarded.

Conditional responses evaluate up to five enabled rules in order and stop at the first match. Each rule supports up to five AND conditions over method, path, query, selected headers, and JSON or form body fields using equals, exists, contains, or glob. Rules cannot inspect authorization or cookie headers. Static responses may delay for up to five seconds.

Replay attempts preserve the original capture and store the effective edited request plus its result separately. Replay history shares the account retention budget; oldest replay attempts are evicted before captured requests. Replay uses a 10-second timeout, does not follow redirects, and strips authorization, cookies, credential-like, hop-by-hop, and source-address headers.

Error model

JSON API errors use {"error":"Human-readable message"}. Clients should branch on HTTP status codes and treat the message as diagnostic text, not a stable machine identifier.