API Documentation

Complete API reference for application developers

🔐 Authentication (two key types):

App API Key: X-APP-API-KEY (or legacy X-API-Key) – can only access its own application.
Admin API Key: X-ADMIN-API-KEY – can act on any application.

🔒 Multi-Tenant Isolation: When using X-APP-API-KEY, all operations are automatically scoped to your own app_id.

📝 Note: For admin keys, pass the target app_id in the path, body, or query as documented per endpoint.

Authentication

All API endpoints require authentication using either an App API Key or an Admin API Key:

# App owner
X-APP-API-KEY: your-app-api-key-here

# Legacy (still supported)
X-API-Key: your-app-api-key-here

Alternatively, you can pass it as a query parameter:

?api_key=your-api-key-here

Token API

POST /api/token

Generate a JWT token for client authentication. The token automatically includes app_id in the payload for security. This endpoint does NOT require API key authentication.

Request Body

Parameter	Type	Required
app_id	string	Required
app_secret	string	Required
payload	object	Optional

Example Request:

POST /api/token
Content-Type: application/json

{
  "app_id": "my-app-123",
  "app_secret": "your-app-secret",
  "payload": {
    "user_id": "user-123",
    "name": "John Doe"
  }
}

Example Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "expires_at": "2024-01-02T12:00:00.000Z"
}

// Token payload includes:
// {
//   "app_id": "my-app-123",  // Automatically included
//   "user_id": "user-123",   // From payload
//   "name": "John Doe",      // From payload
// }

Broadcast API

POST /api/broadcast Requires API Key

Broadcast an event to all subscribers in a room. Rate limited by API Key (1000 requests/minute per application).

Request Body

Parameter	Type	Required
app_id	string	Optional*
room	string	Required
event	string	Required
data	object	Optional

* app_id is automatically extracted from API Key. Only include if you want to verify it matches.

Example Request (app_id optional):

POST /api/broadcast
X-API-Key: your-api-key
Content-Type: application/json

{
  "room": "chat-room-1",
  "event": "new-message",
  "data": {
    "user_id": "user-123",
    "message": "Hello everyone!",
    "timestamp": 1704110400000
  }
}

Example Response:

{
  "success": true,
  "room": "app-my-app-123-chat-room-1",
  "event": "new-message",
  "subscriber_count": 5,
  "timestamp": 1704110400000
}

Applications API

GET /api/applications Requires API Key

Get your application details.

GET /api/applications
X-API-Key: your-api-key

PUT /api/applications/:app_id Requires API Key

Update your application settings.

PUT /api/applications/my-app-123
X-API-Key: your-api-key
Content-Type: application/json

{
  "allowed_domain": "example.com",
  "rate_limit": 60,
  "status": true
}

POST /api/applications/:app_id/regenerate-api-key Requires API Key

Regenerate your API key.

POST /api/applications/my-app-123/regenerate-api-key
X-API-Key: your-api-key

Analytics API

GET /api/analytics Requires API Key

Get analytics and metrics for your application. The app_id is automatically extracted from your API key.

GET /api/analytics?period=24h
X-API-Key: your-api-key

Example Response:

{
  "success": true,
  "app_id": "my-app-123",
  "period": "24h",
  "metrics": {
    "connections": {
      "total": 150,
      "current": 25
    },
    "events": {
      "total": 5000,
      "broadcasts": 3000
    },
    "users": {
      "online": 25,
      "total": 25
    }
  },
  "timestamp": 1234567890
}

Webhooks API

POST /api/webhooks Requires API Key

POST /api/webhooks
X-API-Key: your-api-key
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "secret": "your-webhook-secret",
  "events": ["new-message", "user-joined", "*"]
}

Example Response:

{
  "success": true,
  "webhook": {
    "id": "webhook_1234567890_abc123",
    "url": "https://your-app.com/webhook",
    "events": ["new-message", "user-joined", "*"],
    "enabled": true
  }
}

GET /api/webhooks Requires API Key

List all webhooks for your application.

GET /api/webhooks
X-API-Key: your-api-key

DELETE /api/webhooks/:id Requires API Key

Delete a webhook.

DELETE /api/webhooks/webhook_1234567890_abc123
X-API-Key: your-api-key

Error Responses

All endpoints return errors in the following format:

{
  "success": false,
  "error": "Error message here"
}

Common HTTP Status Codes

400 - Bad Request (missing or invalid parameters)
401 - Unauthorized (missing or invalid API key)
403 - Forbidden (access denied, multi-tenant isolation)
404 - Not Found (resource doesn't exist)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

Rate Limiting:

HTTP APIs: 1000 requests/minute per API Key (not per IP)
Token API: 100 requests/minute per IP
Rate limit responses include retry_after header