API reference

The Relay REST API: base URL, endpoints and errors.

The base URL is https://api.relay.example/v1. Requests and responses are JSON. Authenticate with a bearer token; see Authentication.

Endpoints

Method and path	Does
POST /events	Sends an event. Answers 202 with the event.
POST /events/batch	Sends up to 100 events.
GET /events/{id}	Gets an event and its deliveries.
GET /endpoints	Lists endpoints.
POST /endpoints	Creates an endpoint. The response holds its signing secret, shown once.
PATCH /endpoints/{id}	Changes an endpoint’s URL, subscriptions or concurrency.
DELETE /endpoints/{id}	Deletes an endpoint.
GET /deliveries	Lists deliveries.
POST /deliveries/{id}/replay	Sends a delivery again.

Send an event

type · string · required

The event type, such as invoice.paid. Lowercase letters, digits, dots and underscores.

data · object · required

The payload, up to 256 KB. Relay delivers it unchanged.

Idempotency-Key · string

Up to 255 characters. See Idempotency.

202

{
  "id": "evt_2Lk9xQ",
  "type": "invoice.paid",
  "created": 1729600000,
  "deliveries": 2
}

Errors

Errors answer with a status code and a body like {"error": {"type": "rate_limited", "message": "..."}}.

Retry server errors and rate limits with the same idempotency key; fix the request, the key or the scope for everything else.

Status	error.type
400	invalid_request
401	authentication_failed
403	permission_denied (the key or token lacks the scope)
404	not_found
409	idempotency_conflict, request_in_progress
429	rate_limited
5xx	api_error. Safe to retry with the same idempotency key.