HTTP API Reference

All endpoints prefixed with /apps/{appId}.

Authentication

All API requests require a signature for authentication. The signature is generated using your app secret with HMAC-SHA256. The signature is computed over a string composed of the HTTP method, request path, and query parameters.

Server SDKs (Laravel Broadcasting, Pusher PHP, pusher-js, etc.) handle signature generation automatically. You only need to provide your app ID, key, and secret.

Publishing

POST /apps/{appId}/events

Publish a single event to one or more channels.

Request Body

Example Request

POST /apps/my-app/events
Content-Type: application/json

{
  "name": "user.updated",
  "channel": "private-users",
  "data": "{\"id\":1,\"name\":\"Jayden\"}"
}

POST /apps/{appId}/events/batch

Publish multiple events in a single request. Each event in the batch follows the same format as the single event endpoint.

Example Request

POST /apps/my-app/events/batch
Content-Type: application/json

{
  "batch": [
    {
      "name": "user.updated",
      "channel": "private-users",
      "data": "{\"id\":1,\"name\":\"Jayden\"}"
    },
    {
      "name": "order.created",
      "channel": "private-orders",
      "data": "{\"order_id\":42,\"total\":19.99}"
    }
  ]
}

Channels

GET /apps/{appId}/channels

Returns a list of active channels.

Query Parameters

Example Response

{
  "channels": {
    "private-users": { "subscription_count": 12 },
    "presence-chat": { "user_count": 5 }
  }
}

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

Returns information about a specific channel, including whether it is occupied and its subscription count.

Example Response

{
  "occupied": true,
  "subscription_count": 8
}

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

Returns a list of users subscribed to a presence channel. Only works with presence- channels.

Example Response

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

Authentication Endpoint

POST /apps/{appId}/auth

Authenticates a user for a private or presence channel. Your backend calls this endpoint (or the server SDK handles it) to authorize a client subscription.

Request Body

Other Endpoints

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

Returns event history for a channel. Only available when event history is enabled (RELAY_HISTORY_ENABLED=true).

GET /apps/{appId}/events/log

Returns the server event log. Useful for debugging and monitoring event flow.

GET /stats

Returns server-wide statistics including the total number of active connections and channels.

Example Response

{
  "connections": 142,
  "channels": 37
}

GET /health

Returns 200 OK if the server is healthy. Use this endpoint for load balancer health checks and uptime monitoring.

WebSocket Protocol

Connection URL

Connect to the WebSocket server at:

ws://localhost:6001/app/{appKey}

Replace {appKey} with your app key. For TLS connections, use wss:// instead.

Server → Client Events

Client → Server Events