REST API Reference

Complete REST API reference for managing NoLag programmatically. API keys are project-scoped, so no organization or project IDs are needed in the URLs.

Base URL

https://api.nolag.app/v1

Authentication

All API requests require a project-scoped API key in the Authorization header:

Authorization: Bearer nlg_live_xxx.secret

API keys are created in the NoLag dashboard and are scoped to a specific project. The API key determines which project's resources you can access.

Apps

Apps are containers for rooms and topics within your project.

List Apps

GET /apps

# Query parameters (optional)
?page=1&limit=20&orderBy=name:ASC&name=chat&blueprintId=xxx&status=active

Returns a paginated list of apps in your project. Query parameters: page, limit, orderBy, name, blueprintId, status.

Create App

POST /apps

{
  "name": "My Chat App",
  "description": "A real-time chat application",
  "blueprintId": "optional-blueprint-id",
  "slug": "my-chat-app",
  "accessMode": "restricted",
  "topics": ["messages", "typing"],
  "topicConfigs": {
    "messages": { "logging": true }
  }
}

Required fields: name. Optional fields: description, blueprintId, slug (auto-generated from name if omitted), accessMode ("open" | "restricted", defaults to "restricted"), topics (array of topic names), topicConfigs (per-topic logging settings).

Get App

GET /apps/{appId}

Update App

PATCH /apps/{appId}

{
  "name": "Updated Name",
  "description": "Updated description",
  "status": "active"
}

Updatable fields: name, description, status ("active" | "disabled"), config, files, topics, topicConfigs, pinnedBlueprintVersion, hydrationWebhook, triggerWebhook.

Delete App

DELETE /apps/{appId}

Returns 200 OK with { "success": true }.

Reset App to Blueprint

POST /apps/{appId}/reset-to-blueprint

Resets the app's configuration to match its source blueprint. The app must have been created from a blueprint. Returns the updated app.

Rooms

Rooms organize topics within an app. Each room has a unique slug used in topic patterns.

List Rooms

GET /apps/{appId}/rooms

# Query parameters (optional)
?name=general&slug=general&status=active&isStatic=true

Returns a plain array of rooms (not paginated). Query parameters: name, slug, status, isStatic.

Create Room

POST /apps/{appId}/rooms

{
  "name": "General Chat",
  "slug": "general",
  "description": "General discussion room",
  "topics": ["messages", "typing", "presence"],
  "metadata": {
    "maxUsers": 100
  }
}

Required fields: name. Optional fields: slug (auto-generated from name if omitted), description, topics, metadata (arbitrary JSON object).

Get Room

GET /apps/{appId}/rooms/{roomId}

Update Room

PATCH /apps/{appId}/rooms/{roomId}

{
  "name": "Updated Room Name",
  "description": "Updated description",
  "status": "active"
}

Updatable fields: name, description, status ("active" | "disabled"), topics, metadata. Note: slug cannot be changed after creation.

Delete Room

DELETE /apps/{appId}/rooms/{roomId}

Returns 204 No Content with an empty response body.

Note: Only dynamic rooms can be deleted. Static rooms defined in blueprints cannot be deleted.

Actors

Actors represent clients that connect to NoLag (devices, users, services, or sessions). Each actor has an access token used for WebSocket connections.

List Actors

GET /actors

# Query parameters (optional)
?name=web&actorType=device&status=active

Returns a plain array of actors (not paginated). Query parameters: name, actorType, status.

Create Actor

POST /actors

{
  "name": "Web Client",
  "actorType": "device",
  "metadata": {
    "platform": "web"
  }
}

Required fields: name, actorType. Optional fields: expiresAt (ISO 8601), metadata.

Actor types:

• device - Browser, mobile app, IoT device
• user - Authenticated user connection
• service - Backend service, microservice
• session - Browser session, temporary connection

Get Actor

GET /actors/{actorId}

Update Actor

PATCH /actors/{actorId}

{
  "name": "Updated Name",
  "status": "active",
  "metadata": {
    "platform": "mobile"
  }
}

Updatable fields: name, status ("active" | "disabled"), expiresAt, metadata.

Delete Actor

DELETE /actors/{actorId}

Returns 204 No Content with an empty response body.

Topic Patterns

Topics follow the pattern app-slug/room-slug/topic-name:

# Example topic patterns
my-chat-app/general/messages
my-chat-app/general/typing
my-chat-app/private-room/notifications

Response Format

Successful responses return the resource directly. The Apps list endpoint is paginated, wrapping results in a data array with a pagination object. Rooms and Actors list endpoints return plain arrays.

// Single resource (e.g. GET /apps/{appId})
{
  "appId": "01939f83-8b57-7c3e-a456-426614174000",
  "name": "My App",
  "description": "...",
  "accessMode": "restricted",
  "status": "active",
  "createdAt": "2024-01-01T00:00:00Z"
}

// Paginated list (Apps only)
{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageCount": 5
  }
}

// Plain array (Rooms and Actors)
[
  { "roomId": "...", "name": "General", ... },
  { "roomId": "...", "name": "Private", ... }
]

Error responses return a structured object with a unique ID for support reference:

{
  "id": "01939f83-8b57-7c3e-a456-426614174000",
  "message": "Description of the error",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

See Error Reference for details on HTTP status codes and error handling.

SDKs

For most use cases, we recommend using our official SDKs which wrap this API:

• JavaScript/TypeScript
• Python
• Go