---
title: API Reference
description: Complete REST API reference for NoLag. Manage apps, rooms, actors, and more programmatically.
---

# 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

```bash [Terminal]
https://api.nolag.app/v1
```

## Authentication

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

```bash [Terminal]
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

```bash [Terminal]
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

```bash [Terminal]
POST /apps

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

Required fields: `name`. Optional fields: `description`, `blueprintId`, `slug` (auto-generated from name if omitted), `topics` (array of topic names), `topicConfigs` (per-topic logging and webhook settings).

### Get App

```bash [Terminal]
GET /apps/{appId}
```

### Update App

```bash [Terminal]
PATCH /apps/{appId}

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

Updatable fields: `name`, `description`, `status` (`"active"` | `"disabled"`), `config`, `files`, `topics`, `topicConfigs` (including per-topic `webhooks`), `pinnedBlueprintVersion`, `hydrationWebhook` (deprecated), `triggerWebhook` (deprecated). Prefer configuring webhooks via `topicConfigs.webhooks`.

### Delete App

```bash [Terminal]
DELETE /apps/{appId}
```

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

### Reset App to Blueprint

```bash [Terminal]
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

```bash [Terminal]
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

```bash [Terminal]
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

```bash [Terminal]
GET /apps/{appId}/rooms/{roomId}
```

### Update Room

```bash [Terminal]
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

```bash [Terminal]
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.

**Important:** The access token is only returned when creating an actor. Save it immediately!

### List Actors

```bash [Terminal]
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

```bash [Terminal]
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

```bash [Terminal]
GET /actors/{actorId}
```

### Update Actor

```bash [Terminal]
PATCH /actors/{actorId}

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

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

### Delete Actor

```bash [Terminal]
DELETE /actors/{actorId}
```

Returns `204 No Content` with an empty response body.

## Topic Patterns

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

```bash [Terminal]
# 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.

```json [JSON]
// Single resource (e.g. GET /apps/{appId})
{
  "appId": "01939f83-8b57-7c3e-a456-426614174000",
  "name": "My App",
  "description": "...",
  "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:

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

See [Error Reference](/docs/api-reference/errors) 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](/docs/sdks/javascript)
- [Python](/docs/sdks/python)
- [Go](/docs/sdks/go)