Skip to main content

​
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:
ParameterTypeDescription
typesstringFilter by post types
platformstringFilter by platform
creatorstringFilter by creator username
sortstringasc or desc by date
limitintegerResults per page
offsetintegerPagination 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:
ParameterTypeDescription
topic_filterstringFilter by related topics
type_filterstringFilter by post type or platform
creator_filterstringFilter by creator
sortstringasc 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:
ParameterTypeDescription
yearintegerYear (required)
monthintegerMonth (required)
topic_filterstringFilter by related topics
type_filterstringFilter by post type
creator_filterstringFilter by creator
sortstringasc or desc

​
Paginated Posts

GET /api/topics/{topic_name}/posts/paginated
Standard offset-based pagination as an alternative to chunk loading. 
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
  }
]

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
  }
]

GET /api/topics/featured
Returns featured topics for homepage display. Query Parameters:
ParameterTypeDescription
topicsstringComma-separated topic names to filter
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.