Relay API · v1

Send an event to every destination that needs it.

Relay is a fictional event-delivery API. This example shows how a Staleless site can combine a working quickstart, concepts, reference-shaped details, and recovery paths.

01 · QUICKSTART

Make your first delivery

Create a test key in your workspace, then send one event. Test events are retained for 24 hours and never reach production destinations.

Before you beginYou need a test API key with the deliveries:write scope.

02 · REQUEST

Create a delivery

Send an idempotency key for every request you may retry. Relay returns the existing delivery instead of creating a duplicate.

event: Required · The event name consumers subscribe to.
payload: Required · A JSON object smaller than 256 KB.

curl https://api.relay.example/v1/deliveries \
  -H "Authorization: Bearer $RELAY_KEY" \
  -H "Idempotency-Key: order_1847" \
  -d '{
    "event": "order.created",
    "payload": { "order_id": "1847" }
  }'

03 · CORE CONCEPTS

A delivery has a visible lifecycle

QueuedRelay accepted and validated the event.

DeliveringAt least one destination is still being attempted.

CompleteEvery destination succeeded or exhausted its retries.

04 · RECOVERY

Errors should lead to a safe next action

409 duplicate_delivery

The idempotency key was already used with different content. Retrieve the original delivery or send this event with a new key; do not retry unchanged.

05 · NEXT

Continue with a real destination

Add a signed webhook, inspect one test delivery, and promote the destination only after signature verification succeeds.

Build docs like this Use the API template