---
title: "Categories & Discovery"
description: "Content categories and discovery for live streams — tagging, search, and recommendations"
canonical: "https://docs.ainative.studio/docs/live-streaming/categories"
last-updated: "2026-10-26T19:08:16.785Z"
---

# Categories & Discovery

Source: https://docs.ainative.studio/docs/live-streaming/categories

> Content categories and discovery for live streams — tagging, search, and recommendations

## Categories & Discovery

Stream categories organize content so viewers can find what they want to watch. Categories support a hierarchy — top-level categories can contain subcategories. Each category tracks live stream counts and current viewer counts.

All category endpoints are public (no auth required) unless noted.

## List categories

<span className="badge badge--get">GET</span> `/api/v1/streams/categories`

List all active stream categories. Optionally filter by a parent category to get its subcategories.

**Auth required:** No

### Query parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `parent_id` | UUID | Filter to subcategories of this parent |

```bash
## All top-level categories
GET /api/v1/streams/categories

## Subcategories of "Gaming"
GET /api/v1/streams/categories?parent_id=abc123-...
```

### Response

```json
[
  {
    "id": "7a2f3c80-e11b-4d8a-9e3c-1f2a3b4c5d6e",
    "name": "Technology",
    "slug": "technology",
    "description": "Programming, engineering, and tech content",
    "icon_url": "https://...",
    "parent_id": null,
    "is_active": true,
    "stream_count": 12,
    "viewer_count": 4321
  }
]
```

---

## Get category by slug

<span className="badge badge--get">GET</span> `/api/v1/streams/categories/by-slug/{slug}`

Get a category by its URL slug with the live streams currently in that category embedded.

**Auth required:** No

```bash
GET /api/v1/streams/categories/by-slug/technology
```

Returns `404` if no category with that slug exists.

---

## Get category tree

<span className="badge badge--get">GET</span> `/api/v1/streams/categories/tree`

Get all categories organized as a hierarchical tree — top-level categories with their subcategories nested under them. Each node includes live stream counts and viewer counts.

**Auth required:** No

### Response

```json
{
  "categories": [
    {
      "id": "...",
      "name": "Technology",
      "slug": "technology",
      "stream_count": 25,
      "viewer_count": 8763,
      "children": [
        {
          "id": "...",
          "name": "Web Development",
          "slug": "web-development",
          "stream_count": 8,
          "viewer_count": 2100,
          "children": []
        }
      ]
    }
  ],
  "total_categories": 45
}
```

---

## Trending categories

<span className="badge badge--get">GET</span> `/api/v1/streams/categories/trending`

Get categories sorted by total concurrent viewer count across all live streams in each category.

**Auth required:** No

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | `20` | Max results (max 100) |

### Response

```json
[
  {
    "id": "...",
    "name": "Gaming",
    "slug": "gaming",
    "description": "Gaming streams",
    "thumbnail_url": "https://...",
    "stream_count": 42,
    "viewer_count": 15432
  }
]
```

---

## Popular categories

<span className="badge badge--get">GET</span> `/api/v1/streams/categories/popular`

Get categories ranked by total concurrent viewers. Only categories that currently have at least one live stream are returned.

**Auth required:** No

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | `20` | Max results (max 100) |

### Response

```json
{
  "categories": [
    {
      "id": "...",
      "name": "Technology",
      "live_stream_count": 25,
      "total_viewers": 4321
    }
  ],
  "total": 20
}
```

---

## Category statistics

<span className="badge badge--get">GET</span> `/api/v1/streams/categories/by-slug/{slug}/stats`

Get detailed statistics for a specific category.

**Auth required:** No

### Response

```json
{
  "id": "...",
  "name": "Technology",
  "slug": "technology",
  "live_stream_count": 12,
  "total_viewers": 4321,
  "total_streams": 1542,
  "peak_viewers": 18900,
  "average_viewers": 360.1
}
```

Returns `404` if the category does not exist.

---

## Streams in a category (with sorting)

<span className="badge badge--get">GET</span> `/api/v1/streams/categories/by-slug/{slug}/streams`

Get live streams in a specific category with flexible sorting options.

**Auth required:** No

### Query parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sort_by` | string | `viewers` | Sort by: `viewers`, `recent`, or `alphabetical` |
| `page` | integer | `1` | Page number |
| `per_page` | integer | `20` | Items per page (max 100) |

| Sort option | Behavior |
|-------------|----------|
| `viewers` | Descending viewer count |
| `recent` | Most recently started streams first |
| `alphabetical` | A–Z by title |

### Response

```json
{
  "category": {
    "id": "...",
    "name": "Technology",
    "slug": "technology"
  },
  "streams": [...],
  "total": 12,
  "page": 1,
  "per_page": 20,
  "has_more": false,
  "sort_by": "viewers"
}
```

Returns `404` if the category does not exist.

---

## Tags

Tags provide additional discovery metadata on streams. They are separate from the formal category hierarchy and are user-defined.

### List all tags

<span className="badge badge--get">GET</span> `/api/v1/streams/tags`

Get all available tags with usage counts.

### Popular tags

<span className="badge badge--get">GET</span> `/api/v1/streams/tags/popular`

Get the most-used tags.

### Get stream tags

<span className="badge badge--get">GET</span> `/api/v1/streams/{stream_id}/tags`

Get all tags on a specific stream.

### Update stream tags

<span className="badge badge--put">PUT</span> `/api/v1/streams/{stream_id}/tags`

Replace all tags on a stream. Owner only.

**Auth required:** Yes

```json
{
  "tags": ["python", "fastapi", "backend", "tutorial"]
}
```

### Tag suggestions

<span className="badge badge--get">GET</span> `/api/v1/streams/tags/suggestions`

Get tag suggestions based on partial input for autocomplete.

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Partial tag query |
| `limit` | integer | Max results |