> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Topics

Pub/sub topics for fan-out delivery with per-subscription filters and transforms.

Topics enable pub/sub-style fan-out delivery. Create a topic with a unique slug, subscribe destinations to it with optional per-subscription filters and transforms, then publish events to the topic. hookstream delivers the event to all matching subscribers.

Topics run alongside the connection-based pipeline, not replacing it. You can mix both patterns in the same project — use [connections](/api/connections) for direct 1-to-1 routing and topics for fan-out.

## List Topics

GET `/v1/topics`

List all topics.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "topics": [
    {
      "id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
      "name": "Order Events",
      "slug": "order-events",
      "description": "All order lifecycle events",
      "subscription_count": 3,
      "created_at": "2026-02-28T10:00:00Z"
    }
  ]
}
```

## Create Topic

POST `/v1/topics`

Create a new topic.

**Authentication:** API key or session cookie.

### Body Parameters

Display name for the topic.

URL-safe slug for the publish endpoint (e.g., `"order-events"`).

Optional description of the topic.

```bash cURL
curl -X POST https://hookstream.io/v1/topics \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Events",
    "slug": "order-events",
    "description": "All order lifecycle events"
  }'
```

```json 201 Created
{
  "id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
  "name": "Order Events",
  "slug": "order-events",
  "description": "All order lifecycle events",
  "publish_url": "https://hookstream.io/v1/topics/order-events/publish",
  "created_at": "2026-03-01T12:00:00Z"
}
```

## Retrieve Topic

GET `/v1/topics/:id`

Get a single topic by ID with its subscriptions.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "topic": {
    "id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
    "name": "Order Events",
    "slug": "order-events",
    "description": "All order lifecycle events",
    "publish_url": "https://hookstream.io/v1/topics/order-events/publish",
    "created_at": "2026-02-28T10:00:00Z"
  },
  "subscriptions": [
    {
      "id": "sub_e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
      "topic_id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
      "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
      "destination_name": "Backend API",
      "filter_rules": [],
      "transform_expression": null,
      "created_at": "2026-02-28T12:00:00Z"
    }
  ]
}
```

## Update Topic

PATCH `/v1/topics/:id`

Update a topic's name or description.

**Authentication:** API key or session cookie.

```bash cURL
curl -X PATCH https://hookstream.io/v1/topics/top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5 \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Order lifecycle events (created, updated, cancelled)"}'
```

```json 200 OK
{
  "id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
  "name": "Order Events",
  "slug": "order-events",
  "description": "Order lifecycle events (created, updated, cancelled)",
  "updated_at": "2026-03-01T15:00:00Z"
}
```

## Delete Topic

DELETE `/v1/topics/:id`

Delete a topic and all its subscriptions.

**Authentication:** API key or session cookie.

```json 200 OK
{ "success": true }
```

## Subscribe Destination

POST `/v1/topics/:id/subscriptions`

Subscribe a destination to a topic.

**Authentication:** API key or session cookie.

### Body Parameters

The destination to receive events.

Per-subscription content-based filter rules.

Per-subscription JSONata transform expression.

```bash cURL
curl -X POST https://hookstream.io/v1/topics/top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5/subscriptions \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "filter_rules": [
      { "field": "payload.type", "op": "eq", "value": "order.created" }
    ]
  }'
```

```json 201 Created
{
  "subscription": {
    "id": "sub_e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
    "topic_id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "filter_rules": [
      { "field": "payload.type", "op": "eq", "value": "order.created" }
    ],
    "transform_expression": null,
    "created_at": "2026-03-01T12:00:00Z"
  }
}
```

## Update Subscription

PATCH `/v1/topics/:id/subscriptions/:sub_id`

Update a subscription's filter rules or transform expression.

**Authentication:** API key or session cookie.

### Body Parameters

Updated content-based filter rules.

Updated JSONata transform expression.

```json 200 OK
{
  "subscription": {
    "id": "sub_e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
    "topic_id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "destination_name": "Backend API",
    "filter_rules": [
      { "field": "payload.type", "op": "eq", "value": "order.updated" }
    ],
    "transform_expression": null
  }
}
```

## Unsubscribe

DELETE `/v1/topics/:id/subscriptions/:sub_id`

Remove a subscription from a topic.

**Authentication:** API key or session cookie.

```json 200 OK
{ "success": true }
```

## Publish Event

POST `/v1/topics/:slug/publish`

Publish an event to a topic by slug. The event is delivered to all matching subscribers.

**Authentication:** API key or session cookie.

```bash cURL
curl -X POST https://hookstream.io/v1/topics/order-events/publish \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.created",
    "data": { "id": "ord_789", "amount": 2500, "currency": "usd" }
  }'
```

```json 200 OK
{
  "event_id": "evt_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
  "topic": "order-events",
  "received_at": "2026-03-01T14:30:00Z"
}
```