API DOCUMENTATION

Base URL: https://rekkit.pages.dev

Contents

Quick Start Health Check List Hubs Get Hub Detail List Subreddits Get Stats Error Codes

Quick Start

The Rekkit API is free, public, and requires no authentication. All endpoints are read-only (GET).

curl https://rekkit.pages.dev/api/hubs?limit=5

Response:

{
  "total": 84,
  "limit": 5,
  "offset": 0,
  "hubs": [
    {
      "slug": "edge-of-your-seat-thrillers",
      "title": "Edge-of-Your-Seat Thrillers",
      "subreddit": "MovieSuggestions",
      "title_count": 42,
      "types": ["movie"]
    },
    ...
  ]
}

All responses include CORS headers — you can call the API directly from the browser.

Health Check

GET /health

Returns service status and version. Also available at /.

Response

{
  "service": "rekkit",
  "version": "0.3.0",
  "status": "ok"
}

List Hubs

GET /api/hubs

List all recommendation hubs with pagination and optional filtering.

Query Parameters

Param	Type	Default	Description
`subreddit`	string	—	Filter by subreddit name (case-insensitive)
`type`	string	—	Filter by title type: `movie`, `tv`, `podcast`, `music`
`limit`	number	50	Results per page (max 100)
`offset`	number	0	Number of results to skip

Example

curl "https://rekkit.pages.dev/api/hubs?subreddit=MovieSuggestions&limit=2"

Response

{
  "total": 28,
  "limit": 2,
  "offset": 0,
  "hubs": [
    {
      "slug": "edge-of-your-seat-thrillers",
      "title": "Edge-of-Your-Seat Thrillers",
      "subreddit": "MovieSuggestions",
      "title_count": 42,
      "types": ["movie"]
    },
    {
      "slug": "movies-that-haunt-you-for-weeks",
      "title": "Movies That Haunt You for Weeks",
      "subreddit": "MovieSuggestions",
      "title_count": 38,
      "types": ["movie"]
    }
  ]
}

The type filter matches hubs that contain titles of that type. A hub may include multiple types (e.g. both movie and tv).

Get Hub Detail

GET /api/hubs/:slug

Get full details for a hub, including its titles array.

Path Parameters

Param	Type	Description
`:slug`	string	Hub slug (lowercase, hyphenated)

Query Parameters

Param	Type	Default	Description
`type`	string	—	Filter titles: `movie`, `tv`, `podcast`, `music`

Example

curl https://rekkit.pages.dev/api/hubs/edge-of-your-seat-thrillers

Response

{
  "slug": "edge-of-your-seat-thrillers",
  "title": "Edge-of-Your-Seat Thrillers",
  "description": "Heart-pounding thrillers recommended by r/MovieSuggestions",
  "subreddit": "MovieSuggestions",
  "thread_url": "https://reddit.com/r/MovieSuggestions/...",
  "titles": [
    {
      "name": "Sicario",
      "type": "movie",
      "year": 2015,
      "rating": 7.6,
      "poster": "https://image.tmdb.org/..."
    },
    ...
  ]
}

The titles array contains the full recommendation list. Use the type query param to filter it server-side.

List Subreddits

GET /api/subreddits

Get a sorted list of all unique subreddits that have hubs.

Response

{
  "subreddits": [
    "MovieSuggestions",
    "ifyoulikeblank",
    "musicsuggestions",
    "podcasts",
    "televisionsuggestions"
  ]
}

Get Stats

GET /api/stats

Get aggregate statistics about the Rekkit dataset.

Response

{
  "total_hubs": 84,
  "total_titles": 2847,
  "subreddits": 5
}

Error Codes

All errors return JSON with an error field.

HTTP	Response	Description
404	`{"error": "Hub not found"}`	Hub slug does not exist
404	`{"error": "Not found"}`	Unknown endpoint
405	`{"error": "Method not allowed"}`	Only GET requests are supported

The API is read-only. All endpoints accept only GET requests. OPTIONS is handled for CORS preflight.