Topics

Topic pages, feeds, timeline chunks, and search

Overview

Topics (tags) are the organizational backbone of Sports Index. Each topic has a page with a timeline feed, related topics, members, and curated content. The timeline uses a chunk-based loading strategy for performance — see Timeline Chunks for architecture details.

---

Endpoints

Topic Info

GET /api/topics/{topic_name}/info

Returns metadata about a topic.

Response:

{
  "id": "uuid",
  "name": "ben-johns",
  "display_name": "Ben Johns",
  "description": "Professional pickleball player",
  "type": "player",
  "post_count": 248,
  "contributor_count": 15,
  "hero_image_url": "https://..."
}

---

Topic Header

GET /api/topics/{topic_name}/header

Returns the topic’s hero image and display information for page rendering.

---

Topic Posts

GET /api/topics/{topic_name}/posts

Returns posts tagged with this topic. Supports extensive filtering.

Query Parameters:

Parameter	Type	Description
types	string	Filter by post types
platform	string	Filter by platform
creator	string	Filter by creator username
sort	string	asc or desc by date
limit	integer	Results per page
offset	integer	Pagination offset

---

Timeline Legend

GET /api/topics/{topic_name}/posts/legend

Returns year/month buckets with post counts for building timeline navigation. See Timeline Chunks.

Query Parameters:

Parameter	Type	Description
topic_filter	string	Filter by related topics
type_filter	string	Filter by post type or platform
creator_filter	string	Filter by creator
sort	string	asc or desc

Response:

{
  "legend": [
    { "year": 2026, "month": 3, "count": 15 },
    { "year": 2026, "month": 2, "count": 28 }
  ]
}

---

Timeline Chunk

GET /api/topics/{topic_name}/posts/chunk?year=2026&month=3

Returns posts within a specific time range. Loaded progressively as the user scrolls.

Query Parameters:

Parameter	Type	Description
year	integer	Year (required)
month	integer	Month (required)
topic_filter	string	Filter by related topics
type_filter	string	Filter by post type
creator_filter	string	Filter by creator
sort	string	asc or desc

---

Paginated Posts

GET /api/topics/{topic_name}/posts/paginated

Standard offset-based pagination as an alternative to chunk loading.

---

Related Topics

GET /api/topics/{topic_name}/related

Returns topics related to this one (e.g., a player’s teams, leagues).

Response:

[
  {
    "name": "ppa-tour",
    "display_name": "PPA Tour",
    "relationship_type": "competes_in",
    "post_count": 89
  }
]

---

Related by Type

GET /api/topics/{topic_name}/related-by-type?type=plays_for

Filter related topics by relationship type.

---

Topic Members

GET /api/topics/{topic_name}/members

Returns users who have claimed or are affiliated with this topic.

---

Topic Tabs

GET /api/topics/{topic_name}/tabs

Returns the portfolio tabs configured for this topic page.

---

Topic Settings

GET /api/topics/{topic_name}/settings

Returns topic configuration (display options, tab ordering, etc.).

---

Topic Stats

GET /api/topics/{topic_name}/stats/{tag_name}

Returns engagement statistics for a topic.

---

Search Topics

GET /api/topics/search?q={query}

Search topics by name.

Response:

[
  {
    "id": "uuid",
    "name": "ben-johns",
    "display_name": "Ben Johns",
    "post_count": 248
  }
]

---

Featured Topics

GET /api/topics/featured

Returns featured topics for homepage display.

Query Parameters:

Parameter	Type	Description
topics	string	Comma-separated topic names to filter

---

Trending Topics

GET /api/topics/trending

Returns currently trending topics ranked by recent engagement.

---

Topic Relationships

GET /api/topics/{topic_name}/relationships

Returns the full relationship graph for a topic (plays_for, competes_in, etc.). See Tag System for relationship types.