> ## Documentation Index
> Fetch the complete documentation index at: https://relay-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://relay-demo.mintlify.site/authentication.md).

## 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](https://relay-demo.mintlify.site/idempotency.md).

```json 202 theme={null}
{
  "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": "..."}}`.

![Decision diagram for a failed request: retry with the same Idempotency-Key on 5xx api\_error, a timeout or a network error; wait, then retry with the same key on 429 rate\_limited (wait Retry-After seconds) and 409 request\_in\_progress (wait a second); fix first on 409 idempotency\_conflict, 400 invalid\_request, 401 authentication\_failed, 403 permission\_denied and 404 not\_found.](https://mintcdn.com/relay-demo/EZNTzLZZIWlaFK8l/images/error-retry.png?fit=max\&auto=format\&n=EZNTzLZZIWlaFK8l\&q=85\&s=338807e94102b787fe3ae4ef0646565f)

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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.