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

GET /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

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

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

Response

[
  {
    "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

GET /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

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

Returns 404 if no category with that slug exists.

---

Get category tree

GET /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

{
  "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

GET /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

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

---

Popular categories

GET /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

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

---

Category statistics

GET /api/v1/streams/categories/by-slug/{slug}/stats

Get detailed statistics for a specific category.

Auth required: No

Response

{
  "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)

GET /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

{
  "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

GET /api/v1/streams/tags

Get all available tags with usage counts.

Popular tags

GET /api/v1/streams/tags/popular

Get the most-used tags.

Get stream tags

GET /api/v1/streams/{stream_id}/tags

Get all tags on a specific stream.

Update stream tags

PUT /api/v1/streams/{stream_id}/tags

Replace all tags on a stream. Owner only.

Auth required: Yes

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

Tag suggestions

GET /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