REST API Reference

Base URL: https://your-relay-host.com/api/v1

All endpoints require authentication via X-Relay-Key + X-Relay-Secret headers, Authorization: Bearer <token>, or Pusher HMAC signature.

Trigger Event

POST /apps/{appId}/events

Send an event to one or more channels.

Request Body

Field Type Required Description
name string Yes Event name (max 200 chars, cannot start with pusher:)
channels string[] Yes Target channels (max 100)
data string Yes JSON-encoded payload (max 10KB)
socket_id string No Exclude this connection from receiving the event

Example

curl -X POST /api/v1/apps/APP_ID/events \
  -H "X-Relay-Key: KEY" -H "X-Relay-Secret: SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"new-order","channels":["orders"],"data":"{\"id\":42}"}'

Response

{}

Batch Trigger

POST /apps/{appId}/batch_events

Send up to 10 events in a single request.

Request Body

Field Type Required
batch array Yes
batch[].name string Yes
batch[].channel string Yes
batch[].data string Yes
batch[].socket_id string No

List Channels

GET /apps/{appId}/channels

Query Parameters

Param Description
filter_by_prefix Only return channels starting with this prefix
info Comma-separated: subscription_count, user_count

Response

{
  "channels": {
    "my-channel": {"subscription_count": 3},
    "presence-room": {"subscription_count": 5, "user_count": 5}
  }
}

Channel Info

GET /apps/{appId}/channels/{channelName}

Returns subscription count, user count (presence), and occupied status.

Presence Users

GET /apps/{appId}/channels/{channelName}/users

Only works for presence- channels.

{"users": [{"id": "1"}, {"id": "2"}]}

Client Auth

POST /apps/{appId}/auth

Used by client libraries to authenticate private/presence channel subscriptions.

Request Body

Field Type Required
socket_id string Yes
channel_name string Yes
channel_data string Presence only

Response

{"auth": "key:signature", "channel_data": "..."}

Rate Limits

  • API trigger: 300 requests/minute per IP
  • Daily message limit: depends on your plan (Free: 200K, Starter: 1M, Pro+: unlimited)
  • Returns 429 with X-RateLimit-* headers when exceeded