API Reference

The TrustRelay API is organized around REST. All requests must be authenticated with your API key via the Authorization header.

Base URL: https://api.trustrelay.io/v1

Authentication

Include your API key as a Bearer token on every request:

Authorization: Bearer your_api_key_here

Requests without a valid key will return 401 Unauthorized.

Relay Events

Create a relay event

POST /relay

Sends a payload through the relay and returns an event record.

Request body

Field	Type	Required	Description
`source`	`string`	Yes	Identifier for the originating service
`payload`	`object`	Yes	Arbitrary JSON payload to relay
`metadata`	`object`	No	Optional key-value metadata
`ttl`	`number`	No	Time-to-live in seconds (default: 300)

Example request

{
  "source": "auth-service",
  "payload": {
    "userId": "u_1234",
    "action": "login"
  },
  "metadata": {
    "region": "us-east-1"
  }
}

Example response

{
  "id": "re_9kXmT3fAbc",
  "status": "delivered",
  "source": "auth-service",
  "createdAt": "2026-03-13T10:00:00Z",
  "expiresAt": "2026-03-13T10:05:00Z"
}

Get a relay event

GET /relay/{id}

Returns a relay event by its ID.

Path parameters

Parameter	Type	Description
`id`	`string`	Relay event ID

List relay events

GET /relay

Returns a paginated list of relay events for your account.

Query parameters

Parameter	Type	Default	Description
`limit`	`number`	`20`	Number of results (max: 100)
`cursor`	`string`	—	Pagination cursor from last page
`source`	`string`	—	Filter by source identifier

Error Codes

Code	Meaning
`400`	Bad request — check your request body
`401`	Unauthorized — invalid or missing API key
`404`	Not found — the relay event does not exist
`429`	Rate limited — slow down your request rate
`500`	Internal server error — contact support

Rate Limits

The API enforces rate limits per API key:

100 requests / 10 seconds on POST /relay
1,000 requests / 10 seconds on read endpoints

Exceeding these limits returns a 429 response with a Retry-After header indicating when you may resume.