Endpoints - Socketo Docs

Base URLs

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

Authentication

All endpoints require HMAC-SHA256 authentication parameters passed in the query string:

Parameter	Type	Required	Description
`auth_key`	`string`	Yes	Application key (`app.id`).
`auth_timestamp`	`number`	Yes	Current epoch seconds (valid within ±600s of server clock).
`auth_version`	`string`	Yes	Must be `"1.0"`.
`body_md5`	`string`	Conditional	Hex MD5 digest of body. Required on `POST`, `PUT`, `PATCH`.
`auth_signature`	`string`	Yes	Canonical query HMAC signature.

1. Trigger Event

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

http

POST /apps/:id/events

Request Body

json

{
  "name": "order-created",
  "channels": ["orders", "warehouse"],
  "data": "{\"order_id\":\"ord_987\"}",
  "socket_id": "1234.5678",
  "info": "user_count"
}

Field	Type	Required	Description
`name`	`string`	Yes	Event identifier.
`data`	`string`	Yes	Serialized JSON data payload (max 10 KiB).
`channels`	`string[]`	Conditional	Array of target channels (1–100). Provide either `channels` or `channel`.
`channel`	`string`	Conditional	Single target channel. Provide either `channel` or `channels`.
`socket_id`	`string`	No	Exclude an originating socket connection from receiving the broadcast.
`info`	`string`	No	Comma-separated attributes: `user_count` (presence channels) or `subscription_count`.

Response (`200 OK`)

json

{}

When info attribute is queried:

json

{
  "channels": {
    "presence-lobby": {
      "user_count": 4
    }
  }
}

2. Batch Trigger Events

Publish up to 10 distinct events in a single network round-trip.

http

POST /apps/:id/batch_events

Request Body

json

{
  "batch": [
    {
      "channel": "orders",
      "name": "created",
      "data": "{\"id\":\"ord_1\"}"
    },
    {
      "channel": "presence-chat",
      "name": "message",
      "data": "{\"text\":\"Hello\"}",
      "info": "user_count"
    }
  ]
}

Response (`200 OK`)

json

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

3. Active Sockets Count

Retrieve the total number of open WebSocket connections for the application.

http

GET /apps/:id/sockets

Response (`200 OK`)

json

{
  "sockets": 142
}

4. List Occupied Channels

Retrieve a directory of channels currently holding active subscribers.

http

GET /apps/:id/channels

Query Parameters

Parameter	Type	Required	Description
`filter_by_prefix`	`string`	No	Filter channels matching prefix (e.g. `presence-`).
`info`	`string`	No	Metadata to append (`user_count`). Requires `filter_by_prefix=presence-`.

Response (`200 OK`)

json

{
  "channels": {
    "presence-room-1": { "user_count": 3 },
    "orders": {}
  }
}

5. Channel Info

Retrieve subscriber state and metadata for an individual channel.

http

GET /apps/:id/channels/:channel_name

Query Parameters

Parameter	Type	Required	Description
`info`	`string`	No	Attributes: `user_count` (presence) or `subscription_count`.

Response (`200 OK`)

json

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

If the channel is empty:

json

{
  "occupied": false
}

6. Presence Channel Users

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

http

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

Valid exclusively for channels with presence- prefix.

Response (`200 OK`)

json

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

7. Terminate User Connections

Forcefully disconnect all active WebSocket sessions for an authenticated user_id.

http

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

Response (`200 OK`)

json

{}

Sockets are disconnected with WebSocket close code 4200.

8. Send Event to User

Transmit an event directly to an authenticated user's socket connections (#server-to-user-<user_id>).

http

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

Request Body

json

{
  "name": "order-update",
  "data": "{\"status\":\"shipped\"}"
}

Response (`200 OK`)

json

{}

HTTP Status Codes

Code	Meaning
`200 OK`	Request processed successfully.
`400 Bad Request`	Missing required parameters, invalid JSON, or malformed channel name.
`401 Unauthorized`	Invalid HMAC signature or expired timestamp (> 600s).
`403 Forbidden`	Application is suspended or disabled.
`404 Not Found`	Application ID does not exist.
`429 Too Many Requests`	Edge rate limits exceeded.

Base URLs#

Authentication#

1. Trigger Event#

Request Body#

Response (200 OK)#

2. Batch Trigger Events#

Request Body#

Response (200 OK)#

3. Active Sockets Count#

Response (200 OK)#

4. List Occupied Channels#

Query Parameters#

Response (200 OK)#

5. Channel Info#

Query Parameters#

Response (200 OK)#

6. Presence Channel Users#

Response (200 OK)#

7. Terminate User Connections#

Response (200 OK)#

8. Send Event to User#

Request Body#

Response (200 OK)#

HTTP Status Codes#

Base URLs

Authentication

1. Trigger Event

Request Body

Response (`200 OK`)

2. Batch Trigger Events

Request Body

Response (`200 OK`)

3. Active Sockets Count

Response (`200 OK`)

4. List Occupied Channels

Query Parameters

Response (`200 OK`)

5. Channel Info

Query Parameters

Response (`200 OK`)

6. Presence Channel Users

Response (`200 OK`)

7. Terminate User Connections

Response (`200 OK`)

8. Send Event to User

Request Body

Response (`200 OK`)

HTTP Status Codes