Developer platform

Small API.
Stable contract.

Build local webhook workflows with the versioned API, a dependency-free CLI, reusable SDK examples, and an OpenAPI 3.1 contract. Creating a bin confirms acceptance of the Terms and Conditions.

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, export, and delete-request. Set FREEBIN_URL=http://127.0.0.1:8787 for local development.

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"

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.

Stable management API

Bearer-authenticated endpoints intended for integrations. Replace path parameters with IDs returned by the API.

GET /api/v1/bins

List every bin owned by the API-key user, newest first. Returns names, IDs, creation times, and retained-request counts.

Bearer key
POST /api/v1/bins

Create a private registered bin. Send name and termsAccepted: true. Accounts are limited to five bins.

Bearer key
GET /api/v1/bins/:binId

Read a bin’s name, response configuration, creation time, and current public-share token.

Bearer key or session
PATCH /api/v1/bins/:binId

Customize capture status, body, content type, and response headers. Text fields and serialized headers are limited to 500 UTF-8 bytes.

Bearer key or session
DELETE /api/v1/bins/:binId

Permanently delete the bin and all of its retained requests.

Bearer key or session
GET /api/v1/bins/:binId/interactions?limit=50

List the newest retained requests. limit accepts 1–100 and defaults to 50.

Bearer key or session
GET /api/v1/bins/:binId/stream?lastId=:requestId

Open a server-sent event stream. Emits request events and keepalives for about 25 seconds; reconnect to continue.

Session or token query
GET /api/v1/bins/:binId/export

Download bin metadata and every currently retained request as JSON.

Bearer key or session
POST /api/v1/bins/:binId/share

Enable or disable a read-only public bin URL with {"public":true|false}. Enabling again rotates the URL.

Bearer key or session
DELETE /api/v1/bins/:binId/interactions/:requestId

Permanently delete one retained request.

Bearer key or session
GET /api/v1/bins/:binId/interactions/:requestId/export

Download one retained request as JSON.

Bearer key or session
POST /api/v1/bins/:binId/interactions/:requestId/share

Enable or disable a read-only public request URL with {"public":true|false}.

Bearer key or session
POST /api/v1/bins/:binId/interactions/:requestId/replay

Replay the retained request to the public HTTPS URL supplied as {"url":"https://…"}. Private and local targets are rejected.

Bearer key or session

Request capture

Capture URLs are deliberately outside the management API version. They remain stable destinations for webhook senders.

GET /b/:binId/*

Capture a GET request and return the bin’s configured response.

Bearer key required
POST /b/:binId/*

Capture a POST request and return the bin’s configured response.

Bearer key required
PUT /b/:binId/*

Capture a PUT request and return the configured response.

Bearer key required
PATCH /b/:binId/*

Capture a PATCH request and return the configured response.

Bearer key required
DELETE /b/:binId/*

Capture a DELETE request and return the configured response.

Bearer key required
OPTIONS /b/:binId/*

Capture an OPTIONS request and return the configured response.

Bearer key required

Browser account and session API

These endpoints support the first-party web application. Session endpoints use the secure HttpOnly cookie set during registration or login.

GET /api/config

Return public browser configuration: signup availability and optional RUM endpoint and client key.

Public
POST /api/auth/register

Create an account and session. Requires email, a 10–128 character password, termsAccepted: true, and enabled signups.

Public
POST /api/auth/login

Validate email and password and create a 30-day session cookie.

Public
POST /api/auth/logout

Delete the current server session and clear its cookie.

Session optional
GET /api/me

Return the signed-in account, byte usage and limit, and owned bins. Returns user: null when signed out.

Session
DELETE /api/me

Permanently delete the signed-in account and clear its session.

Session required
GET /api/account/token

List API-key metadata. Full key values are never returned after creation.

Session required
POST /api/account/token

Create a named user API key. The full token is returned once; accounts may have five active keys.

Session required
DELETE /api/account/token

Revoke the key whose ID is supplied as {"id":"…"}.

Session required

Documented service limits

LimitRegisteredAnonymous demo
Capture rate20 requests/second per userCapture unavailable
Request body1 MBCapture unavailable
Retention1 GB per account by defaultPublic demo history only
Bins5 per accountSubject to creation abuse controls
API keys5 active per accountNot applicable
List page1–100 requests; default 50
Custom response fields500 UTF-8 bytes per text field and serialized headers field

Retention is byte-based and evicts the oldest requests first. There is no date-based cleanup. Rate-limited requests return 429; oversized requests return 413.

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.