API Reference

Full reference for the Verne Relay HTTP API. All endpoints are served from https://api.vernesoft.com.

Examples are shown as raw curl requests and as calls through the official SDKs — see Installation to set one up. SDK snippets assume an initialized verne client.

1. Authentication

Every request must include a Bearer token in the Authorization header. Relay tokens follow the format:

vrn_relay_<environment>_<secret>

Prefix	Environment
`vrn_relay_test_`	Sandbox — events are accepted but not delivered.
`vrn_relay_live_`	Production — full delivery pipeline.

Example header:

Authorization: Bearer vrn_relay_live_sk_9f8a7...

Tokens are scoped to a single tenant and can be rotated from the Dashboard → Keys page.

2. Send Event

POST /v1/relay/messages

Publishes a new event to all endpoints subscribed to the given event_type.

Request Body

Field	Type	Required	Description
`event_type`	`string`	Yes	Dot-notated event name (e.g. `user.created`).
`payload`	`object`	Yes	Arbitrary JSON payload delivered to subscribers.
`idempotency_key`	`string`	No	Prevents duplicate delivery within a 24 h window.
`channels`	`string[]`	No	Restrict delivery to endpoints listening on these channels.

Example Request

curl -X POST https://api.vernesoft.com/v1/relay/messages \
  -H 'Authorization: Bearer vrn_relay_test_123' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "user.created",
    "payload": { "id": "123" },
    "idempotency_key": "evt_abc",
    "channels": ["team-a"]
  }'

Response

{
  "id": "msg_2hV9kLmNpQ",
  "event_type": "user.created",
  "status": "accepted",
  "timestamp": "2026-03-17T12:00:00Z"
}

Retries are safe. A second send with an idempotency_key that was already accepted does not create a second event and does not fail — it returns 202 with the originally accepted message, same id and same timestamp. A client that retries a request whose response it never saw ends up in the right state without having to tell a duplicate apart from a success. The window is 24 hours.

Status Code	Meaning
`202 Accepted`	Event queued for delivery — or already was, if you sent this `idempotency_key` before.
`400 Bad Request`	Invalid payload or missing required fields.
`401 Unauthorized`	Missing or invalid Bearer token.
`402 Payment Required`	The account is suspended for billing, or a renewal is unpaid. Retrying does not help — settle the balance.
`429 Too Many Requests`	Rate limit reached, or the monthly allowance is spent — retry after the `Retry-After` header.

3. List Events

GET /v1/relay/messages

Returns a paginated list of previously sent events for the current tenant.

Query Parameters

Parameter	Type	Default	Description
`limit`	`integer`	`20`	Items per page. Values above `100` are clamped to `100` rather than rejected.
`cursor`	`string`	—	Pagination cursor from a previous response.
`event_type`	`string`	—	Filter by event type.

Example Request

curl 'https://api.vernesoft.com/v1/relay/messages?limit=5&event_type=user.created' \
  -H 'Authorization: Bearer vrn_relay_test_123'

Response

{
  "data": [
    {
      "id": "msg_2hV9kLmNpQ",
      "event_type": "user.created",
      "status": "accepted",
      "timestamp": "2026-03-17T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

status is always accepted — it records that Relay took the event, not what each subscriber endpoint did with it afterwards. Per-endpoint delivery state lives in the Console under Dashboard → Relay.

next_cursor is null on the last page, so paginate until has_more is false rather than until the list comes back empty.

Error Format

All errors follow a consistent structure. The SDKs surface these fields as a typed error:

{
  "error": {
    "code": "invalid_payload",
    "message": "Field 'event_type' is required.",
    "request_id": "req_abc123"
  }
}

Include the request_id when contacting support for faster resolution.