Topics API

The Topics API manages domain topics — the named channels that clients subscribe to for receiving real-time events.

Info

Topics are the central routing unit of the platform. To understand how topics relate to schemas, mappings, and webhooks, see Core Concepts.

List Topics

GET /api/topics

Returns all topics scoped to the current application and environment.

Response:

[
  {
    "name": "session.status",
    "description": "Session status changes",
    "owner": "platform-team",
    "activeSchemaVersion": 2,
    "applicationId": "app_abc123",
    "environment": "development",
    "createdAt": 1710000000000
  }
]

Get Topic

GET /api/topics/:name

Example:

curl http://localhost:3000/api/topics/session.status

Create Topic

POST /api/topics

Request Body:

{
  "name": "session.status",
  "description": "Session status changes",
  "owner": "platform-team"
}

Validation Rules:

name — required, dot-separated, lowercase (e.g. session.status, order.updated)
description — required, non-empty string
owner — required, identifies the owning team or service

Response: 201 Created with the new topic object.

Update Topic

PATCH /api/topics/:name

Request Body (all fields optional):

{
  "description": "Updated description",
  "owner": "new-team",
  "activeSchemaVersion": 3
}

Delete Topic

DELETE /api/topics/:name

Response: 200 OK

Warning

Deleting a topic does not automatically remove associated schemas, mappings, or active subscriptions. Clean these up separately.

Topic Naming Convention

Topics use dot-separated, lowercase names that follow a domain-driven convention:

session.status
order.updated
chat.room.message
proctor.session.started
user.profile.changed

The TopicValidator enforces this format — names must match the pattern: lowercase letters, numbers, and dots, with at least one segment.