📖 REST API Reference¶

Complete reference for all REST API endpoints.

Base URL

Public: https://epguides.frecar.no Local: http://localhost:3000

📋 Endpoints¶

Method	Endpoint	Description
`GET`	`/shows/`	List all shows (paginated)
`GET`	`/shows/search`	Search shows by title
`GET`	`/shows/{key}`	Get show metadata
`GET`	`/shows/{key}/seasons`	List seasons with posters
`GET`	`/shows/{key}/seasons/{n}/episodes`	Get episodes for a season
`GET`	`/shows/{key}/episodes`	Get all episodes with filtering
`GET`	`/shows/{key}/episodes/next`	Get next unreleased episode
`GET`	`/shows/{key}/episodes/latest`	Get latest released episode
`GET`	`/health`	Health check
`GET`	`/health/llm`	LLM status
`POST`	`/mcp`	MCP JSON-RPC endpoint

📺 Shows¶

List Shows¶

GET /shows/

Returns a paginated list of all TV shows.

Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`page_size`	integer	50	Items per page (max 100)

curl "https://epguides.frecar.no/shows/?page=1&page_size=20"

Search Shows¶

GET /shows/search

Search for shows by title.

Parameters

Parameter	Type	Required	Description
`query`	string	✅	Search query (show title)

curl "https://epguides.frecar.no/shows/search?query=breaking"

Get Show¶

GET /shows/{epguides_key}

Get detailed metadata for a specific show.

Parameters

Parameter	Type	Description
`epguides_key`	path	Show identifier (e.g., `BreakingBad`)
`include`	query	Set to `episodes` to include episode list
`refresh`	query	Set to `true` to bypass cache

Show OnlyWith EpisodesForce Refresh

curl "https://epguides.frecar.no/shows/BreakingBad"

curl "https://epguides.frecar.no/shows/BreakingBad?include=episodes"

curl "https://epguides.frecar.no/shows/BreakingBad?refresh=true"

Response

{
  "epguides_key": "BreakingBad",
  "title": "Breaking Bad",
  "imdb_id": "tt0903747",
  "network": "AMC",
  "run_time_min": 60,
  "start_date": "2008-01-20",
  "end_date": "2013-09-29",
  "country": "US",
  "total_episodes": 63,
  "poster_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/2400.jpg",
  "external_epguides_url": "http://www.epguides.com/BreakingBad",
  "external_imdb_url": "https://www.imdb.com/title/tt0903747",
  "api_self_url": "https://epguides.frecar.no/shows/BreakingBad",
  "api_seasons_url": "https://epguides.frecar.no/shows/BreakingBad/seasons",
  "api_episodes_url": "https://epguides.frecar.no/shows/BreakingBad/episodes"
}

📅 Seasons¶

List Seasons¶

GET /shows/{epguides_key}/seasons

List all seasons for a show with poster images and summaries.

curl "https://epguides.frecar.no/shows/BreakingBad/seasons"

Response

[
  {
    "number": 1,
    "episode_count": 7,
    "premiere_date": "2008-01-20",
    "end_date": "2008-03-09",
    "poster_url": "https://static.tvmaze.com/uploads/images/original_untouched/24/60941.jpg",
    "summary": "High school chemistry teacher Walter White...",
    "api_episodes_url": "https://epguides.frecar.no/shows/BreakingBad/seasons/1/episodes"
  },
  {
    "number": 2,
    "episode_count": 13,
    "premiere_date": "2009-03-08",
    "end_date": "2009-05-31",
    "poster_url": "https://static.tvmaze.com/uploads/images/original_untouched/24/60942.jpg",
    "summary": null,
    "api_episodes_url": "https://epguides.frecar.no/shows/BreakingBad/seasons/2/episodes"
  }
]

Get Season Episodes¶

GET /shows/{epguides_key}/seasons/{season_number}/episodes

Get all episodes for a specific season.

curl "https://epguides.frecar.no/shows/BreakingBad/seasons/1/episodes"

Response

[
  {
    "number": 1,
    "season": 1,
    "title": "Pilot",
    "release_date": "2008-01-20",
    "is_released": true,
    "run_time_min": 60,
    "episode_number": 1,
    "summary": "A high school chemistry teacher...",
    "poster_url": "https://static.tvmaze.com/uploads/images/original_untouched/36/92299.jpg"
  }
]

Episode Images

Each episode has a poster_url with a still image from that episode (from TVMaze).

🎬 Episodes¶

Get All Episodes¶

GET /shows/{epguides_key}/episodes

Get all episodes with optional filtering and AI-powered search.

Filter Parameters

Parameter	Type	Description
`season`	integer	Filter by season number
`episode`	integer	Filter by episode (requires `season`)
`year`	integer	Filter by release year
`title_search`	string	Search in episode titles
`nlq`	string	Natural language query (requires LLM)
`refresh`	boolean	Bypass cache

All EpisodesBy SeasonSpecific EpisodeTitle SearchNatural Language

curl "https://epguides.frecar.no/shows/BreakingBad/episodes"

curl "https://epguides.frecar.no/shows/BreakingBad/episodes?season=2"

curl "https://epguides.frecar.no/shows/BreakingBad/episodes?season=2&episode=5"

curl "https://epguides.frecar.no/shows/BreakingBad/episodes?title_search=pilot"

curl "https://epguides.frecar.no/shows/BreakingBad/episodes?nlq=finale+episodes"

Get Next Episode¶

GET /shows/{epguides_key}/episodes/next

Get the next unreleased episode for a show.

Smart Caching

This endpoint automatically refreshes if the cached "next" episode date has passed.

curl "https://epguides.frecar.no/shows/Severance/episodes/next"

Response (200)

{
  "number": 11,
  "season": 2,
  "title": "TBA",
  "release_date": "2025-02-15",
  "is_released": false
}

Response (404)

Show has finished airing or no upcoming episodes.

Get Latest Episode¶

GET /shows/{epguides_key}/episodes/latest

Get the most recently aired episode.

curl "https://epguides.frecar.no/shows/BreakingBad/episodes/latest"

🤖 Natural Language Queries¶

AI-Powered Filtering

When LLM is configured, use the nlq parameter for intelligent episode filtering.

How It Works¶

Your query is sent to the configured LLM gateway
The LLM analyzes episode titles, summaries, and metadata
Matching episodes are returned based on semantic understanding

Examples¶

# 🏁 Find finale episodes
curl "https://epguides.frecar.no/shows/BreakingBad/episodes?nlq=finale+episodes"

# ⚔️ Find episodes with major events
curl "https://epguides.frecar.no/shows/GameOfThrones/episodes?nlq=battle+episodes"

# 🎯 Combine with structured filters
curl "https://epguides.frecar.no/shows/BreakingBad/episodes?season=5&nlq=most+intense"

Check LLM Status¶

curl "https://epguides.frecar.no/health/llm"

Graceful Degradation¶

Scenario	Behavior
LLM not configured	`nlq` parameter silently ignored
LLM fails	Falls back to returning all episodes
Structured filters	Always work regardless of LLM

📝 Response Notes¶

Images

Show poster_url: Main show poster from TVMaze
Season poster_url: Season-specific poster (falls back to show poster)
Episode poster_url: Still image from the episode

end_date Field

May be null if not available. Use individual show endpoint for derived values.

summary Field

Episode and season summaries from TVMaze enable AI-powered search.

💚 Health Endpoints¶

Health Check¶

curl "https://epguides.frecar.no/health"

{
  "status": "healthy",
  "service": "epguides-api",
  "version": "123"
}

LLM Health¶

curl "https://epguides.frecar.no/health/llm"

{
  "enabled": true,
  "configured": true,
  "api_url": "https://your-llm-server.example.com/v1",
  "model": "auto",
  "allow_external": false
}