Rest API

REST APIs let your backend talk to PieSocket over plain HTTP, publish messages, check who's connected, pull logs, without opening a WebSocket connection yourself.

There are two separate APIs, on two separate domains:

The following are the Cluster API endpoints, reachable at your cluster's own domain, they talk directly to the cluster running your connections rather than your account as a whole. key and secret go in the JSON request body here instead of headers, alongside the rest of the parameters.

Publish a message

POST https://CLUSTER_ID.piesocket.com/api/v4/publish

{
  "key": "YOUR_API_KEY",
  "secret": "YOUR_API_SECRET",
  "channel": "room-1",
  "message": { "event": "new-message", "data": "Hello" }
}

POST https://CLUSTER_ID.piesocket.com/api/publish

{
  "key": "YOUR_API_KEY",
  "secret": "YOUR_API_SECRET",
  "channel": "room-1",
  "message": { "event": "new-message", "data": "Hello" }
}

message can be any string or JSON value, whatever you'd publish is delivered to every connection subscribed to channel as-is. See publish examples with curl and wget.

Which path you call depends on which protocol version the connections you're targeting use, not a setting on the request itself, a V3 connection won't receive anything published to the V4 path and vice versa.

List channel members

POST https://CLUSTER_ID.piesocket.com/api/v4/members

{ "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET", "channel": "room-1" }

POST https://CLUSTER_ID.piesocket.com/api/members

{ "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET", "channel": "room-1" }

channel is required on the V4 path, and the response adds a count field and deduplicates members by identity, see Presence channels in the V4 reference. On the V3 path, channel is optional, omit it to get every channel for this key grouped by name.

Pagination (V4 only)

By default, members on the V4 path is capped to the 200 most recently active members, count always reports the true total regardless of the cap. Pass paginate: 1 to page through the full list instead:

POST https://CLUSTER_ID.piesocket.com/api/v4/members

{
  "key": "YOUR_API_KEY",
  "secret": "YOUR_API_SECRET",
  "channel": "room-1",
  "paginate": 1,
  "page": 1,
  "limit": 50
}

{
  "success": true,
  "members": ["user-1", "user-2"],
  "count": 134,
  "page": 1,
  "limit": 50,
  "totalPages": 3
}

Kick your connections

Force-disconnects connections on your API key. Authenticated the same way as publish and presence, with your own API key and secret.

Without a uuid/user, it kicks every connection on the key, for example right after rotating a leaked key, works the same on both paths below regardless of which protocol version the connections used:

POST https://CLUSTER_ID.piesocket.com/api/v4/kick

{ "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET", "reason": "key rotated" }

POST https://CLUSTER_ID.piesocket.com/api/kick

{ "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET", "reason": "key rotated" }

reason is optional, sent to the kicked client as the disconnect message, defaults to "Connection closed by administrator" if omitted.

Kick by uuid/user (V4 only)

Pass uuid and/or user to target specific connections instead of the whole key, the same two values you already set when connecting (uuid identifies one device/session, user is the identity you authenticated as):

• uuid only — kicks that one device/session, regardless of which user it's signed in as.
• user only — kicks that user everywhere, across every device/session (every uuid).
• Both — kicks only the connection matching that exact uuid and user pair.

Add channel to scope any of the above to one channel, omit it to match across every channel under the key.

POST https://CLUSTER_ID.piesocket.com/api/v4/kick

{ "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET", "user": "alice", "channel": "room-1" }

Health check

GET https://CLUSTER_ID.piesocket.com/api/health

{ "status": "ok" }

No authentication required. If you want proper uptime monitoring on top of this, alerts, status pages, historical checks, rather than polling it yourself, use PieMonitor.

The following are the Account API endpoints, reachable at www.piesocket.com. Every request needs your API key and secret as the key and secret HTTP headers.

List allowed domains

Returns the list of domains allowed to connect with this API key.

GET https://www.piesocket.com/api/domains

["example.com", "app.example.com"]

List active connections by channel

Returns active connection counts, broken down by channel, for this API key.

GET https://www.piesocket.com/api/connections

[
  { "channel_id": "room-1", "room_id": "room-1", "connection_count": 12 },
  { "channel_id": "room-2", "room_id": "room-2", "connection_count": 3 }
]

Pass page and/or limit to paginate instead of getting the full list back, limit is capped at 100:

GET https://www.piesocket.com/api/connections?page=1&limit=50

{
  "data": [
    { "channel_id": "room-1", "room_id": "room-1", "connection_count": 12 }
  ],
  "total": 134,
  "page": 1,
  "limit": 50,
  "totalPages": 3
}

Total active connections

Returns the total connection count across every channel for this API key.

GET https://www.piesocket.com/api/connections/sum

{ "connection_count": 15 }

Fetch recent logs

Returns the 500 most recent messages logged across every channel for this API key.

GET https://www.piesocket.com/api/logs