API docsspec sample · fictional client, real writing
An API reference that answers before you ask
- Client
- Relay (spec)
- Year
- 2026
- Niche
- API docs
[ The brief ]
Reference docs live or die on completeness and honesty about edge cases. The spec brief: document Relay’s replay endpoint so an integrator never has to email support, or guess.
[ Craft decisions ]
- →Each parameter answers three questions: what, what happens if omitted, what goes wrong.
- →Guarantees stated as contracts (idempotency, ordering): the things engineers actually grep for.
- →Rate limits and pagination documented at the endpoint, not exiled to a general page.
[ The sample ]
POST /v1/deliveries/{id}/replay
Re-sends a previously attempted delivery to its endpoint. Replays use the original event payload and a fresh signature with the current timestamp, so receivers validating timestamp windows will accept them. Replaying is idempotent per delivery: concurrent replay requests for the same id coalesce into one attempt.
curl -X POST https://api.relay.dev/v1/deliveries/dl_8Kd2/replay \ -H "Authorization: Bearer $RELAY_KEY" \ -d reason="endpoint bug fixed"
Parameters
- ✱reason (string, optional, ≤140 chars): recorded in the delivery log and visible to your team. Omitting it is fine; your future self during the next incident disagrees.
- ✱override_url (string, optional): replay to a different HTTPS URL without re-registering the endpoint. The signature still uses the original endpoint’s secret.
Errors
- ✱409 replay_in_flight: a replay for this delivery is already executing. Safe to retry after it settles; you will not cause a double-send.
- ✱410 event_expired: event payloads are retained 30 days. Past that, replay returns 410 and the payload is genuinely gone (export retention rules on the Plans page).
[ Read it like an editor ]
“Your future self during the next incident disagrees.” Reference docs can be complete and human at once. The idempotency contract up top is what a senior engineer scans for first.