Skip to content
Long TailLong Tail

Topics

The topic catalog is a persistent registry of known event topics with descriptions, payload schemas and subscriber counts. See Agents and events for how agents subscribe to them.

All endpoints require authentication. Registering, updating, deleting and publishing require builder access (superadmin or the engineer role). Publishing a subject that starts with system. or agent. requires superadmin.

List topics

Section titled “List topics”
GET /api/topics

Returns topics with subscriber counts, computed from active subscriptions.

Query parameters

Parameter Type Required Description
category string No Filter by category: task, workflow, escalation, activity, knowledge, agent, app, milestone.
search string No Search topic name or description (case-insensitive).
limit number No Max results (default 50).
offset number No Pagination offset.

Example request

Terminal window
curl -s "https://lt.acme.dev/api/topics?category=task&search=created&limit=50&offset=0" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "topics": [
    {
      "topic": "task.created",
      "description": "A new task has been created and queued for execution.",
      "category": "task",
      "payload_schema": {
        "type": "object",
        "properties": {
          "taskId": { "type": "string" },
          "status": { "type": "string" },
          "workflowId": { "type": "string" }
        }
      },
      "example_payload": { "taskId": "tsk-001", "status": "pending" },
      "source": "system",
      "tags": ["lifecycle", "core"],
      "subscriber_count": 2,
      "last_seen_at": "2026-05-20T12:00:00Z",
      "created_at": "2026-05-20T00:00:00Z",
      "updated_at": "2026-05-20T00:00:00Z"
    }
  ],
  "total": 22
}

Get topic

Section titled “Get topic”
GET /api/topics/by-name/:topic

Returns one topic with its full schema, example payload and the agents whose subscription patterns match it. Subscribers match with NATS-style patterns, so an agent subscribed to task.* appears on task.created.

Path parameters

Parameter Description
topic Topic name, URL-encoded (for example task.created).

Example request

Terminal window
curl -s https://lt.acme.dev/api/topics/by-name/task.created \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "topic": "task.created",
  "description": "A new task has been created and queued for execution.",
  "category": "task",
  "payload_schema": { "..." },
  "example_payload": { "..." },
  "source": "system",
  "tags": ["lifecycle", "core"],
  "subscribers": [
    {
      "id": "uuid",
      "agent_id": "uuid",
      "agent_name": "health-monitor",
      "topic": "task.*",
      "reaction_type": "durable"
    }
  ],
  "created_at": "2026-05-20T00:00:00Z",
  "updated_at": "2026-05-20T00:00:00Z"
}

Response 404: { "error": "Topic not found" }

Register topic

Section titled “Register topic”
POST /api/topics

Registers a topic in the catalog. Use it to declare a topic before its first publish.

Auth: Requires builder access.

Request body

Field Type Required Description
topic string Yes Unique topic name (dot-delimited).
category string Yes One of task, workflow, escalation, activity, knowledge, agent, app, milestone.
description string No Human-readable description.
payload_schema object No JSON Schema for event.data.
example_payload object No Concrete example of event.data.
source string No Source identifier (default 'app').
tags string[] No Filterable tags.

Example request

Terminal window
curl -s https://lt.acme.dev/api/topics \
  -X POST \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "app.acme.orders.created",
    "description": "Fired when a new order is placed.",
    "category": "app",
    "payload_schema": {
      "type": "object",
      "properties": {
        "orderId": { "type": "string" },
        "total": { "type": "number" }
      }
    },
    "tags": ["orders", "lifecycle"]
  }'

Response 201: The created topic.

Response 409: { "error": "Topic \"app.acme.orders.created\" already exists" }

Update topic

Section titled “Update topic”
PUT /api/topics/by-name/:topic

Partially updates a topic: send only the fields to change. System topics (source: 'system') accept updates to description and tags, and cannot be deleted.

Auth: Requires builder access.

Path parameters

Parameter Description
topic Topic name, URL-encoded.

Request body

Field Type Required Description
description string No Human-readable description.
category string No Topic category.
payload_schema object No JSON Schema for event.data.
example_payload object No Concrete example of event.data.
tags string[] No Filterable tags.

Example request

Terminal window
curl -s https://lt.acme.dev/api/topics/by-name/app.acme.orders.created \
  -X PUT \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "tags": ["orders", "lifecycle", "critical"]}'

Response 200: The updated topic.

Response 404: { "error": "Topic not found" }

Delete topic

Section titled “Delete topic”
DELETE /api/topics/by-name/:topic

Permanently removes a topic from the catalog. System topics are protected.

Auth: Requires builder access.

Path parameters

Parameter Description
topic Topic name, URL-encoded.

Example request

Terminal window
curl -s https://lt.acme.dev/api/topics/by-name/app.acme.orders.created \
  -X DELETE \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200: { "deleted": true }

Response 403: { "error": "System topics cannot be deleted" }

Response 404: { "error": "Topic not found" }

Publish an event

Section titled “Publish an event”
POST /api/topics/by-name/:topic/publish

Publishes an event to the event bus on the topic. The request body is the event envelope. The server sets type to the subject and stamps timestamp.

Auth: Requires builder access. A subject that starts with system. or agent. requires superadmin.

Path parameters

Parameter Description
topic Topic name or pattern, URL-encoded.

Request body

Field Type Required Description
subject string No Concrete subject to publish on. Must be a valid variant of the topic pattern. Defaults to the topic.
data object No Event payload (default {}).
source string No Event source (default 'dashboard').

Example request

Terminal window
curl -s https://lt.acme.dev/api/topics/by-name/app.acme.orders.created/publish \
  -X POST \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"orderId": "order-456", "total": 120}}'

Response 200

{
  "published": true,
  "topic": "app.acme.orders.created",
  "timestamp": "2026-05-20T12:00:00.000Z"
}

Response 400: The subject does not match the topic pattern.

Response 403: { "error": "Forbidden: only superadmin can publish a system subject" }