---
title: API overview
description: OrbitRail Events API — endpoints, base URL, and how to use the interactive reference.
url: https://pr-1-3b5c652a9824.thally.app/api/introduction
---

# API overview

OrbitRail Events API — endpoints, base URL, and how to use the interactive reference.

This reference documents the OrbitRail Events API (v1.14.0), which provides three endpoints for publishing events, replaying retained events, and inspecting delivery status.

Every endpoint page includes request and response schemas generated from the OpenAPI specification.

## Base URL

All requests use the same base URL:

```text
https://events.orbitrail.example
```

## Endpoints

| Method | Path | Operation | Description |
|---|---|---|---|
| `POST` | `/v1/events` | Publish an event | Ingest a JSON event for delivery to registered destinations |
| `POST` | `/v1/events/{eventId}/replay` | Replay an event | Queue a new delivery attempt for a retained event |
| `GET` | `/v1/events/{eventId}` | Get delivery status | Return the lifecycle state and attempt history for an event |

## Authentication

Every request requires an `X-OrbitRail-Key` header containing your API key. See [Authentication](/api/authentication) for details.

## Common response patterns

- **`202`** — request accepted (publish and replay endpoints)
- **`200`** — status returned (delivery status endpoint)
- **`404`** — event not found or no longer retained (events are retained for 30 days)
- **`413`** — payload exceeds the 256 KiB limit (publish endpoint only)
- **`415`** — content type is not `application/json` (publish endpoint only)
- **`429`** — replay cooldown not elapsed (replay endpoint only; minimum 30-second interval)

## Request constraints

| Constraint | Value |
|---|---|
| Content type | `application/json` (required) |
| Maximum payload size | 256 KiB (262,144 bytes) |
| Idempotency key | Required on publish; 24-hour deduplication window |
| Delivery timeout | 8 seconds per attempt |
| Retry policy | Up to 12 attempts over 72 hours, exponential backoff with jitter |
| Event retention | 30 days |
| Replay cooldown | 30 seconds between replay requests for the same event |