API Reference

Soketify provides a Pusher-compatible REST API for triggering events, querying channel information, and listing presence users. All endpoints use HMAC-SHA256 signature authentication.

Base URL

https://api.soketify.com

All API endpoints are served over HTTPS. HTTP requests are not accepted.

Authentication

Every request to the REST API must include authentication parameters. Soketify uses the Pusher authentication scheme: a combination of your App Key, a timestamp, and an HMAC-SHA256 signature generated with your App Secret.

Required Query Parameters

Parameter	Type	Description
`auth_key`	string	Your App Key
`auth_timestamp`	integer	Unix timestamp in seconds. Must be within 600 seconds of server time.
`auth_version`	string	Always `"1.0"`
`auth_signature`	string	HMAC-SHA256 hex digest of the string to sign
`body_md5`	string	MD5 hex digest of the request body (for POST requests)

Signature Computation

The string to sign is constructed by joining the HTTP method, request path, and sorted query parameters:

Signature computation

javascript

1// String to sign format:
2// METHOD\nPATH\nQUERY_PARAMS
3
4// Example for POST /apps/12345/events:
5const stringToSign = [
6  "POST",
7  "/apps/12345/events",
8  "auth_key=YOUR_KEY&auth_timestamp=1700000000&auth_version=1.0&body_md5=BODY_MD5"
9].join("\n");
10
11// Generate HMAC-SHA256 signature
12const crypto = require("crypto");
13const signature = crypto
14  .createHmac("sha256", "YOUR_APP_SECRET")
15  .update(stringToSign)
16  .digest("hex");

Use the SDK

You do not need to compute signatures manually. The Pusher server libraries handle authentication automatically. Direct API calls with manual signatures are only necessary for languages without an official SDK.(pusher, pusher-http-php, etc.) handle authentication automatically. Direct API calls with manual signatures are only necessary for languages without an official SDK.

Trigger Event

POST/apps/{appId}/events

Trigger an event on one or more channels. This is the primary way to send real-time messages from your server to connected clients.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Event name (max 200 characters)
`data`	string	Yes	JSON-encoded event payload (max 10 KB)
`channel`	string	One of `channel` or `channels` required	Single channel name
`channels`	string[]	One of `channel` or `channels` required	Array of channel names (max 100)
`socket_id`	string	No	Exclude this socket from receiving the event

Example

Trigger event

javascript

1// Using the Pusher SDK (recommended)
2await pusher.trigger("my-channel", "my-event", {
3  message: "Hello!",
4});
5
6// Raw HTTP request
7// POST https://api.soketify.com/apps/YOUR_APP_ID/events
8// ?auth_key=...&auth_timestamp=...&auth_version=1.0
9// &body_md5=...&auth_signature=...
10
11// Request body:
12{
13  "name": "my-event",
14  "data": "{\"message\":\"Hello!\"}",
15  "channel": "my-channel"
16}

Response

Success response

json

// 200 OK
{}

Batch Trigger Events

POST/apps/{appId}/batch_events

Trigger multiple events in a single API call. Each event in the batch can target a different channel and use a different event name. This is more efficient than making multiple individual trigger requests.

Request Body

Field	Type	Description
`batch`	object[]	Array of event objects, each with `channel`, `name`, and `data` fields. Max 10 events per batch.

Example

Batch trigger

javascript

1// Using the Pusher SDK
2await pusher.triggerBatch([
3  {
4    channel: "user-1",
5    name: "notification",
6    data: { text: "You have a new message" },
7  },
8  {
9    channel: "user-2",
10    name: "notification",
11    data: { text: "Your order shipped" },
12  },
13  {
14    channel: "admin",
15    name: "log",
16    data: { action: "batch_notify", count: 2 },
17  },
18]);
19
20// Raw request body:
21{
22  "batch": [
23    {
24      "channel": "user-1",
25      "name": "notification",
26      "data": "{\"text\":\"You have a new message\"}"
27    },
28    {
29      "channel": "user-2",
30      "name": "notification",
31      "data": "{\"text\":\"Your order shipped\"}"
32    }
33  ]
34}

Response

Success response

json

// 200 OK
{}

List Channels

GET/apps/{appId}/channels

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

Query Parameters

Parameter	Type	Description
`filter_by_prefix`	string	Filter channels by prefix (e.g., `presence-`)
`info`	string	Comma-separated list of attributes: `user_count` (presence channels only)

Example

List channels

javascript

// Using the Pusher SDK
const result = await pusher.get({
  path: "/channels",
  params: {
    filter_by_prefix: "presence-",
    info: "user_count",
  },
});

console.log(result.channels);

Response

json

{
  "channels": {
    "presence-chat-room": {
      "user_count": 12
    },
    "presence-game-lobby": {
      "user_count": 4
    }
  }
}

Channel Info

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

Returns information about a specific channel, including whether it is currently occupied.

Query Parameters

Parameter	Type	Description
`info`	string	Comma-separated list: `user_count` (presence), `subscription_count`

Example

Channel info

javascript

const result = await pusher.get({
  path: "/channels/presence-chat-room",
  params: {
    info: "user_count,subscription_count",
  },
});

console.log(result);

Response

json

{
  "occupied": true,
  "user_count": 12,
  "subscription_count": 15
}

Info

subscription_count can be higher than user_count on presence channels because a single user can have multiple connections (e.g., multiple browser tabs).

Presence Users

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

Returns the list of unique users currently subscribed to a presence channel. This endpoint only works for channels with the presence- prefix.

Example

Presence users

javascript

const result = await pusher.get({
  path: "/channels/presence-chat-room/users",
});

console.log(result.users);
// [{ id: "user-1" }, { id: "user-2" }, { id: "user-3" }]

Response

json

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

Warning

This endpoint only returns user IDs, not the full user_info object. The full user info is only available on the client side through the presence channel subscription events.

Response Codes and Errors

All API responses use standard HTTP status codes. Error responses include a JSON body with details.

Status	Meaning	Common Causes
200	Success	Request processed successfully
400	Bad Request	Invalid JSON, missing required fields, payload too large
401	Unauthorized	Invalid auth_key, expired timestamp, invalid signature
403	Forbidden	App disabled, feature not enabled, plan limits exceeded
404	Not Found	Invalid app ID, channel does not exist
413	Payload Too Large	Event data exceeds 10 KB limit
429	Too Many Requests	Rate limit exceeded. Retry after the specified interval.

Error Response Format

Error response

json

{
  "error": "Invalid authentication signature",
  "code": 401
}

Rate Limits

API rate limits depend on your plan. When you exceed the rate limit, the API returns a 429 status code with a Retry-After header indicating when you can retry.

Plan	Requests per second	Messages per day
Free	10	200,000
Pro	100	10,000,000
Business	500	Unlimited

Info

Rate limits are applied per app, not per API key. If you need higher limits, contact us to discuss a custom plan.