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

# 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](/dev/architecture/timeline-chunks) for architecture details.

***

## Endpoints

### Topic Info

```
GET /api/topics/{topic_name}/info
```

Returns metadata about a topic.

**Response:**

```json theme={null}
{
  "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](/dev/architecture/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:**

```json theme={null}
{
  "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:**

```json theme={null}
[
  {
    "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:**

```json theme={null}
[
  {
    "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](/dev/architecture/tag-system) for relationship types.