Skip to content

Topical Tags API

Standalone topical hashtag rules allow you to mark any hashtag as topical for a specific day of the week or calendar date, without needing a dedicated stream for it.

When a consumer requests topical content from the curated queue (via include_topical=true on GET /api/v1/curated/next), FenLiu checks all TopicalHashtag rules to identify eligible posts.

Overview

Day values

topical_day_of_week accepts one of the following string values (case-sensitive):

Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday

Calendar date format

topical_month_day accepts a date string in MM-DD format, e.g. 03-17 for 17 March.

Authentication

All endpoints require API key authentication via X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  http://localhost:8000/api/v1/topical-tags

See Authentication Guide for details.

Endpoints

GET /api/v1/topical-tags

List all standalone topical hashtag rules.

Request

curl -H "X-API-Key: your-api-key" \
  http://localhost:8000/api/v1/topical-tags

Response (200 OK)

[
  {
    "id": 1,
    "hashtag": "caturday",
    "topical_day_of_week": "Saturday",
    "topical_month_day": null,
    "created_at": "2026-03-01T10:00:00Z"
  },
  {
    "id": 2,
    "hashtag": "stpatricksday",
    "topical_day_of_week": null,
    "topical_month_day": "03-17",
    "created_at": "2026-03-01T10:05:00Z"
  }
]

Response Fields

Field Type Description
id integer Rule identifier
hashtag string Hashtag name (without #)
topical_day_of_week string|null Day name (e.g., "Saturday")
topical_month_day string|null Calendar date in MM-DD format
created_at string ISO 8601 creation timestamp

POST /api/v1/topical-tags

Create a new standalone topical hashtag rule.

Request

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"hashtag": "caturday", "topical_day_of_week": "Saturday"}' \
  http://localhost:8000/api/v1/topical-tags

Request Body

Field Type Required Description
hashtag string Yes Hashtag to mark as topical (without #)
topical_day_of_week string|null No Day name (e.g., "Saturday")
topical_month_day string|null No Calendar date in MM-DD format (e.g., "03-17")

Response (201 Created)

{
  "id": 1,
  "hashtag": "caturday",
  "topical_day_of_week": "Saturday",
  "topical_month_day": null,
  "created_at": "2026-03-19T12:00:00Z"
}

Error Responses

{ "detail": "Hashtag 'caturday' already has a topical rule" }  // 409 Conflict
{ "detail": "topical_month_day must be in MM-DD format" }      // 422 Unprocessable Entity

PATCH /api/v1/topical-tags/{id}

Update an existing topical hashtag rule.

Request

curl -X PATCH \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"topical_month_day": "03-17"}' \
  http://localhost:8000/api/v1/topical-tags/1

Request Body

All fields are optional. Only fields provided are updated.

Field Type Description
hashtag string New hashtag name
topical_day_of_week string|null Day name; null clears it
topical_month_day string|null Calendar date MM-DD; null clears it

Response (200 OK)

{
  "id": 1,
  "hashtag": "stpatricksday",
  "topical_day_of_week": null,
  "topical_month_day": "03-17",
  "created_at": "2026-03-01T10:00:00Z"
}

Error Responses

{ "detail": "Topical tag not found" }  // 404

DELETE /api/v1/topical-tags/{id}

Delete a topical hashtag rule.

Request

curl -X DELETE \
  -H "X-API-Key: your-api-key" \
  http://localhost:8000/api/v1/topical-tags/1

Response (204 No Content)

Error Responses

{ "detail": "Topical tag not found" }  // 404

Examples

Mark common topical hashtags

export API_KEY="your-api-key"
export BASE_URL="http://localhost:8000/api/v1"

# Weekly topical hashtags
curl -X POST "$BASE_URL/topical-tags" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hashtag": "caturday", "topical_day_of_week": "Saturday"}'

curl -X POST "$BASE_URL/topical-tags" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hashtag": "mossmonday", "topical_day_of_week": "Monday"}'

curl -X POST "$BASE_URL/topical-tags" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hashtag": "followfriday", "topical_day_of_week": "Friday"}'

# Annual calendar date
curl -X POST "$BASE_URL/topical-tags" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hashtag": "stpatricksday", "topical_month_day": "03-17"}'