REST API Endpoints#

Socketo provides a Pusher-compatible HTTP REST API for triggering server-to-client events, querying channel occupancy, and managing connected users.

Base URLs#

• Socketo Cloud: https://api.socketo.dev
• Socketo Local CLI: http://localhost:8787
• Self-Hosted: https://<your-worker-domain>

Authentication#

All REST endpoints under /apps/:id/* require Pusher Channels HMAC-SHA256 authentication passed as URL query parameters.

Required Query Parameters#

Official Pusher server SDKs handle signature generation automatically. See Auth & Signatures to sign requests manually.

1. Trigger Event#

Publish an event to one or more channels (up to 100 channels).

POST /apps/:id/events

Request Body#

{
  "name": "new-message",
  "channels": ["chat-room-1", "chat-room-2"],
  "data": "{\"text\":\"Hello world!\",\"author\":\"Alice\"}",
  "socket_id": "1234.5678",
  "info": "user_count"
}

Response (200 OK)#

{}

When info attribute is included in the request body:

{
  "channels": {
    "presence-room-1": {
      "user_count": 4
    }
  }
}

2. Batch Trigger Events#

Publish up to 10 distinct events in a single network request.

POST /apps/:id/batch_events

Request Body#

{
  "batch": [
    {
      "channel": "orders",
      "name": "order-created",
      "data": "{\"order_id\":\"ord_101\"}"
    },
    {
      "channel": "presence-lobby",
      "name": "announcement",
      "data": "{\"msg\":\"Server restart in 5m\"}",
      "info": "user_count"
    }
  ]
}

Response (200 OK)#

{
  "batch": [
    {},
    { "user_count": 12 }
  ]
}

3. Get Active Sockets Count#

Retrieve the total count of active WebSocket connections for your application.

GET /apps/:id/sockets

Response (200 OK)#

{
  "sockets": 142
}

4. List Occupied Channels#

Retrieve a list of currently active channels that have at least one subscriber.

GET /apps/:id/channels

Query Parameters#

Response (200 OK)#

{
  "channels": {
    "presence-room-1": { "user_count": 3 },
    "presence-room-2": { "user_count": 1 },
    "public-feed": {}
  }
}

5. Get Channel Info#

Retrieve occupancy and subscriber metadata for a single channel.

GET /apps/:id/channels/:channel_name

Query Parameters#

Response (200 OK)#

{
  "occupied": true,
  "user_count": 5
}

If the channel currently has no active subscribers:

{
  "occupied": false
}

6. Get Presence Channel Users#

Retrieve a list of all user IDs currently online in a specific presence channel.

GET /apps/:id/channels/:channel_name/users

Note: Only valid for channels prefixed with presence-.

Response (200 OK)#

{
  "users": [
    { "id": "user_101" },
    { "id": "user_102" },
    { "id": "user_103" }
  ]
}

7. Terminate User Connections#

Forcefully disconnect and terminate all active WebSocket connections belonging to a specific user_id.

POST /apps/:id/users/:user_id/terminate_connections

Response (200 OK)#

{}

Terminated connections receive a WebSocket close frame with code 4200.

8. Send Event to User#

Send an event directly to all active WebSocket connections belonging to an authenticated user_id.

Socketo delivers the event with wire channel #server-to-user-<user_id>, which automatically triggers callbacks registered via pusher.user.bind(eventName, callback) in the official pusher-js SDK.

You can also trigger user events using the official Pusher backend SDK method pusher.sendToUser(userId, name, data).

POST /apps/:id/users/:user_id/events

Request Body#

{
  "name": "notification",
  "data": {
    "title": "New Alert",
    "message": "You have a new update."
  }
}

Response (200 OK)#

{}

Error Status Codes#