HTTP API Reference

All endpoints prefixed with /apps/{appId}. Authenticated endpoints require Bearer token.

Most endpoints require authentication via the Authorization header:

Authorization: Bearer {appSecret}

The auth endpoint (/apps/{appId}/auth) does not require Bearer authentication.

Publishing

POST /apps/{appId}/events Requires auth

Publish an event to a single channel. The data field must be a JSON-encoded string.

Request Body

Field	Type	Required	Description
`channel`	string	Yes	Target channel name
`event`	string	Yes	Event name
`data`	string	Yes	JSON-encoded event payload
`socket_id`	string	No	Exclude this socket from receiving the event

Response

json

{ "ok": true }

Example

bash

curl -X POST http://localhost:6001/apps/my-app/events \
  -H "Authorization: Bearer my-secret" \
  -H "Content-Type: application/json" \
  -d '{"channel":"chat","event":"message","data":"{\"text\":\"Hello\"}"}'

POST /apps/{appId}/events/batch Requires auth

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

Request Body

json

{
  "batch": [
    { "channel": "chat", "event": "message", "data": "{\"text\":\"Hello\"}" },
    { "channel": "alerts", "event": "notify", "data": "{\"level\":\"info\"}" }
  ]
}

Response

json

{ "ok": true, "count": 2 }

Example

bash

curl -X POST http://localhost:6001/apps/my-app/events/batch \
  -H "Authorization: Bearer my-secret" \
  -H "Content-Type: application/json" \
  -d '{"batch":[{"channel":"chat","event":"msg","data":"{}"},{"channel":"alerts","event":"ping","data":"{}"}]}'

Channels

GET /apps/{appId}/channels Requires auth

List all active channels for the application.

Response

json

{
  "channels": [
    {
      "name": "chat",
      "type": "public",
      "subscriber_count": 5,
      "occupied": true,
      "app_id": "my-app"
    }
  ]
}

Example

bash

curl http://localhost:6001/apps/my-app/channels \
  -H "Authorization: Bearer my-secret"

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

Get detailed information for a single channel.

Response

json

{
  "name": "chat",
  "type": "public",
  "subscriber_count": 5,
  "occupied": true,
  "app_id": "my-app"
}

Example

bash

curl http://localhost:6001/apps/my-app/channels/chat \
  -H "Authorization: Bearer my-secret"

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

Get the list of members in a presence channel. Only works for channels prefixed with presence-.

Response

json

{
  "users": [
    { "id": 1, "user_info": { "name": "Alice" } },
    { "id": 2, "user_info": { "name": "Bob" } }
  ]
}

Example

bash

curl http://localhost:6001/apps/my-app/channels/presence-room/users \
  -H "Authorization: Bearer my-secret"

Authentication

POST /apps/{appId}/auth

Generate an auth token for a private or presence channel subscription. This endpoint does not require Bearer authentication -- it is called by the client-side SDK and validated using the app secret internally.

Request Body

Field	Type	Required	Description
`socket_id`	string	Yes	The connecting client's socket ID
`channel_name`	string	Yes	Channel to authorize
`channel_data`	string	No	JSON user data (required for presence channels)

Response

json

{
  "auth": "my-key:a1b2c3d4e5f6...",
  "channel_data": "{\"user_id\":1,\"user_info\":{\"name\":\"Alice\"}}"
}

Example

bash

curl -X POST http://localhost:6001/apps/my-app/auth \
  -H "Content-Type: application/json" \
  -d '{"socket_id":"123.456","channel_name":"private-user.1"}'

Other Endpoints

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

Get event history for a channel. Supports ?limit=50 query parameter (default 50).

Example

bash

curl http://localhost:6001/apps/my-app/channels/chat/events?limit=20 \
  -H "Authorization: Bearer my-secret"

GET /apps/{appId}/events/log Requires auth

Get the 20 most recent events for the app. Useful for debugging during development.

Example

bash

curl http://localhost:6001/apps/my-app/events/log \
  -H "Authorization: Bearer my-secret"

GET /stats

Server-level stats including total connections, channels, and per-app counts. No authentication required.

Example

bash

curl http://localhost:6001/stats

GET /health

Health check endpoint. Returns 200 OK if the server is running. No authentication required.

Example

bash

curl http://localhost:6001/health

WebSocket Protocol

Clients connect via WebSocket. All messages are JSON-encoded.

Connection URL

url

ws://{host}:{port}/app/{appKey}

Server → Client Events

Event	Description
`relay:connection_established`	Sent on connect. Contains `socket_id` and server activity timeout.
`relay:subscription_succeeded`	Channel subscription confirmed. Presence channels include the initial member list.
`relay:member_added`	A new member joined a presence channel. Payload includes member `id` and `info`.
`relay:member_removed`	A member left a presence channel. Payload includes member `id` and `info`.
`relay:pong`	Response to a `relay:ping` keep-alive message.
`relay:error`	Error message with `code` and `message` fields.

Client → Server Events

Event	Description
`relay:subscribe`	Subscribe to a channel. Include `auth` token for private/presence channels.
`relay:unsubscribe`	Unsubscribe from a channel.
`relay:ping`	Keep-alive ping. Server responds with `relay:pong`.
`client-*`	Client events (private/presence channels only). Event name must start with `client-`.