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&search=chat

Returns a paginated list of apps in your project.

Create App

POST /apps

{
  "name": "My Chat App",
  "description": "A real-time chat application",
  "blueprintId": "optional-blueprint-id"
}

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}

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

Create Room

POST /apps/{appId}/rooms

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

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}

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

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}

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. Paginated endpoints wrap results in a data array with a pagination object:

// Single resource
{
  "appId": "01939f83-8b57-7c3e-a456-426614174000",
  "name": "My App",
  "description": "...",
  "status": "active",
  "createdAt": "2024-01-01T00:00:00Z"
}

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

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.

Rate Limits

SDKs

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

• JavaScript/TypeScript
• Python
• Go