REST API · v1

Automate all of RelayFox

Create and configure webhook endpoints, inspect captured requests, replay deliveries, manage sharing and collaborators, and stream new events from any AI agent, script, or integration.

Create an API key OpenAPI 3.1 JSON

Base URL: https://relayfox.dev/api/v1JSON requests and responses300 requests/minute/key

Authentication

Create a scoped key under Dashboard → API keys. Send it as a bearer token on every protected request. The plaintext key is shown once; RelayFox stores only its SHA-256 hash.

export RELAYFOX_API_KEY="rfx_..."

curl https://relayfox.dev/api/v1/account \
  -H "Authorization: Bearer $RELAYFOX_API_KEY"

Give each AI agent or integration its own key. Use an AI agent — full API key for automation, or a CLI — stream only key for localhost forwarding.

Start with capability discovery

A key's scopes and the account plan jointly determine what it can do. Call this endpoint first. Each returned operation includes its method, path, required scope, and current availability.

curl https://relayfox.dev/api/v1/capabilities \
  -H "Authorization: Bearer $RELAYFOX_API_KEY"

Create a webhook endpoint

Configure the response RelayFox should return to the webhook provider. The response includes both the public capture_url and private viewer_url.

curl -X POST https://relayfox.dev/api/v1/endpoints \
  -H "Authorization: Bearer $RELAYFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe development",
    "response_status": 200,
    "response_body": "received",
    "response_content_type": "text/plain"
  }'

Send a webhook

Webhook providers send requests directly to the returned capture URL. Capture URLs do not use API-key authentication; treat each URL as a bearer secret and rotate it after accidental disclosure.

curl -X POST https://relayfox.dev/h/{endpoint_id}/stripe/events?source=docs \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: test_signature" \
  -d '{"type":"checkout.session.completed"}'

Inspect captured requests

Request history is newest-first. Use before_seq to page backward or after_seq to fetch newer deliveries. Page sizes range from 1 to 100.

curl "https://relayfox.dev/api/v1/endpoints/{endpoint_id}/requests?limit=50" \
  -H "Authorization: Bearer $RELAYFOX_API_KEY"

Replay a request

Replay preserves the captured method, safe headers, query, path, and body. Targets must resolve to public HTTP(S) addresses. Pro endpoint owners may provide an edited body_text.

curl -X POST https://relayfox.dev/api/v1/requests/{request_id}/replay \
  -H "Authorization: Bearer $RELAYFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.com/webhooks/stripe"}'

Create a read-only share link

Share links expose request history without allowing changes. The operation is idempotent: enabling an existing link returns the same URL.

curl -X PUT https://relayfox.dev/api/v1/endpoints/{endpoint_id}/share \
  -H "Authorization: Bearer $RELAYFOX_API_KEY"

Stream new requests

The live Server-Sent Events endpoint uses the stream:read scope. Reconnect with Last-Event-ID or the after query parameter to resume from a sequence.

curl -N "https://relayfox.dev/api/stream/{endpoint_id}" \
  -H "Authorization: Bearer $RELAYFOX_API_KEY" \
  -H "Accept: text/event-stream"

AI-agent discovery

API-capable agents such as Claude, Codex, and Kimi should read the live capability response and OpenAPI contract before acting. Ask before destructive, sharing, collaborator, billing, or key management changes.

OpenAPI: https://relayfox.dev/api/openapi.json
Capabilities: https://relayfox.dev/api/v1/capabilities
Agent manifest: https://relayfox.dev/.well-known/relayfox.json

Recommended AI-agent instruction:
"Use my RelayFox API at https://relayfox.dev/api/v1. Keep the key secret.
Read /capabilities and the linked OpenAPI contract before acting.
Use only operations marked available, and confirm destructive changes."

Endpoint reference

This is the human-readable route index. The live OpenAPI document remains the source of truth for request and response schemas.

Discovery and account

Method	Path	Scope	Purpose
GET	/capabilities	Any valid key	Discover allowed operations
GET	/account	account:read	Read account plan and limits

Webhook endpoints

Method	Path	Scope	Purpose
GET	/endpoints	endpoints:read	List owned endpoints
POST	/endpoints	endpoints:write	Create an endpoint
GET	/endpoints/{endpoint_id}	endpoints:read	Read endpoint configuration
PATCH	/endpoints/{endpoint_id}	endpoints:write	Update endpoint configuration
DELETE	/endpoints/{endpoint_id}	endpoints:write	Delete endpoint and history
POST	/endpoints/{endpoint_id}/claim	endpoints:write	Claim an anonymous endpoint

Captured requests

Method	Path	Scope	Purpose
GET	/endpoints/{endpoint_id}/requests	requests:read	List captured requests
GET	/requests/{request_id}	requests:read	Read one captured request
POST	/requests/{request_id}/replay	requests:replay	Replay to a public HTTP(S) URL
DELETE	/requests/{request_id}	requests:write	Delete one captured request

Live streaming

Method	Path	Scope	Purpose
GET	/api/stream/{endpoint_id}	stream:read	Stream newly captured requests over SSE

Sharing and collaborators

Method	Path	Scope	Purpose
GET · PUT · DELETE	/endpoints/{endpoint_id}/share	sharing:read/write	Inspect, enable, or disable a share link
GET · POST	/endpoints/{endpoint_id}/members	members:read/write	List or invite Pro collaborators
DELETE	/endpoints/{endpoint_id}/members/{user_id}	members:write	Remove a Pro collaborator

API keys and billing

Method	Path	Scope	Purpose
GET · POST	/keys	keys:read/write	List or create API keys
DELETE	/keys/{key_id}	keys:write	Revoke an API key
POST	/billing/checkout	billing:write	Create a hosted Pro checkout
POST	/billing/portal	billing:write	Create a Pro billing portal session

Ready to automate RelayFox?

Create a scoped key, discover its available capabilities, and keep the OpenAPI document as your machine-readable source of truth.

Create an API key View OpenAPI JSON