API Reference

Complete reference for all LatteStream APIs and protocols

This section provides comprehensive documentation for all LatteStream APIs, protocols, and interfaces. Whether you're building with our SDKs or integrating directly with our APIs, you'll find everything you need here.

API Overview

LatteStream provides multiple API surfaces for different use cases:

• WebSocket API - Real-time bidirectional communication
• REST API - Server-side event triggering and management
• Webhooks - Server-side event notifications
• Authentication - Channel authorization and security

WebSocket API

The WebSocket API enables real-time communication between clients and the LatteStream service.

Connection Endpoint

wss://ws-{cluster}.lattestream.com/app/{app-key}

Basic Connection Flow

1. Connect to WebSocket endpoint with app key
2. Subscribe to channels for receiving events
3. Bind event handlers to process incoming messages
4. Authenticate for private/presence channel access

View WebSocket API Documentation →

REST API

The REST API allows server-side applications to trigger events, manage channels, and retrieve information.

Base URL

https://api-{cluster}.lattestream.com

Authentication

All REST API requests require authentication using your Master Key:

Authorization: Bearer {master-key}
Content-Type: application/json

Core Endpoints

• POST /apps/{app-id}/events - Trigger events
• GET /apps/{app-id}/channels - List channels
• GET /apps/{app-id}/channels/{channel} - Get channel info
• GET /apps/{app-id}/channels/{channel}/users - Get presence users

View REST API Documentation →

Webhooks

Webhooks provide server-side notifications for connection events, channel lifecycle, and user presence changes.

Supported Events

• Connection Events - connection_established, connection_disconnected
• Channel Events - channel_occupied, channel_vacated
• Presence Events - member_added, member_removed
• Client Events - client_event (for presence channels)

Webhook Security

All webhooks are signed with HMAC-SHA256 for authenticity verification.

View Webhooks Documentation →

Authentication

LatteStream uses a multi-layered authentication system to secure your applications.

Authentication Layers

1. App Keys - Public keys for client connection
2. Master Keys - Private keys for server operations
3. Channel Auth - Authorization for private/presence channels
4. User Auth - Optional user identification and data

Channel Types & Security

• Public Channels - No authentication required
• Private Channels - Require server-side authorization
• Presence Channels - Require authorization + user identification

View Authentication Documentation →

Rate Limits

LatteStream implements rate limiting to ensure fair usage and system stability.

Connection Limits

Plan	Concurrent Connections	Channels per Connection
Free	100	10
Pro	1,000	50
Business	10,000	100
Enterprise	Custom	Custom

API Rate Limits

Endpoint Category	Rate Limit	Burst Limit
Event Triggering	1,000/min	100/sec
Channel Info	500/min	50/sec
Authentication	2,000/min	200/sec

Message Size Limits

• Event Data: 32KB per message
• Channel Name: 164 characters
• Event Name: 200 characters
• Batch Events: 100 events per batch

Regional Clusters

LatteStream operates in multiple regions for optimal performance:

Available Clusters

• us-east-1 - US East (Virginia) - Default
• us-west-2 - US West (Oregon)
• eu-west-1 - Europe (Ireland)
• ap-southeast-1 - Asia Pacific (Singapore)
• ap-northeast-1 - Asia Pacific (Tokyo)

Cluster Selection

Choose the cluster closest to your users for best performance:

// Client SDK
const lattestream = new LatteStream('your-app-key', {
  cluster: 'eu-west-1',
});

// Server SDK
const lattestream = new LatteStreamServer('app-key', 'master-key', {
  cluster: 'eu-west-1',
});

SDKs & Client Libraries

Official SDKs are available for multiple languages and frameworks:

Client-Side SDKs

• JavaScript/TypeScript - npm: @lattestream/client
• Python - Coming Soon
• Go - Coming Soon
• Rust - Coming Soon

Server-Side SDKs

• Node.js - npm: @lattestream/server
• Python - Coming Soon
• PHP - Coming Soon
• Ruby - Coming Soon
• Go - Coming Soon

Error Codes

WebSocket Error Codes

Code	Name	Description
4001	Application does not exist	Invalid app key
4004	Application over quota	Connection limit exceeded
4005	Path not found	Invalid WebSocket path
4006	Invalid version string	Unsupported protocol version
4007	Unsupported protocol version	Use supported version
4008	No protocol version supplied	Missing version in connection

HTTP Status Codes

Code	Description	Common Causes
400	Bad Request	Invalid JSON, missing parameters
401	Unauthorized	Invalid or missing Master Key
403	Forbidden	Insufficient permissions
404	Not Found	Invalid app ID or channel
413	Payload Too Large	Message exceeds size limit
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Service issue

Protocol Specifications

Message Format

All WebSocket messages follow a standardized JSON format:

{
  "event": "event_name",
  "channel": "channel_name",
  "data": "json_string"
}

Connection States

WebSocket connections progress through these states:

1. connecting - Establishing connection
2. connected - Successfully connected
3. disconnected - Connection lost
4. reconnecting - Attempting to reconnect
5. failed - Connection failed permanently

Event Types

• Channel Events - User-defined events on specific channels
• Connection Events - System events for connection lifecycle
• Presence Events - User join/leave events for presence channels
• Client Events - Events triggered by other clients

Quick Reference

Common Patterns

Subscribe to Channel

const channel = lattestream.subscribe('my-channel');
channel.bind('my-event', (data) => console.log(data));

Trigger Event from Server

await lattestream.trigger('my-channel', 'my-event', { message: 'Hello' });

Authenticate Private Channel

app.post('/lattestream/auth', (req, res) => {
  const auth = lattestream.authenticate(
    req.body.socket_id,
    req.body.channel_name
  );
  res.json(auth);
});

Environment Variables

# Required
LATTESTREAM_APP_KEY=app_1234567890abcdef
LATTESTREAM_MASTER_KEY=master_1234567890abcdef

# Optional
LATTESTREAM_CLUSTER=us-east-1
LATTESTREAM_WEBHOOK_SECRET=webhook_secret_key
LATTESTREAM_ENABLE_LOGGING=true

Related Documentation

• Getting Started - Quick setup guide
• JavaScript SDK - Client SDK documentation
• Server SDK - Server SDK documentation
• Examples - Implementation examples

Support

• Discord Community - Join our Discord
• GitHub Issues - Report API issues
• Email Support - api-support@lattestream.com
• Status Page - status.lattestream.com

---

Need help? Start with our Getting Started guide or explore specific API documentation above.