Skip to main content
GET
/
api
/
series
/
{showId}
/
seasons
/
{seasonId}
Get Season
curl --request GET \
  --url https://api.example.com/api/series/{showId}/seasons/{seasonId}
{
  "_id": "<string>",
  "title": "<string>",
  "description": "<string>",
  "images": [
    {
      "_id": "<string>",
      "path": "<string>",
      "basePath": "<string>"
    }
  ],
  "error": {
    "message": "<string>",
    "status": 123
  }
}

​
Overview

Retrieves detailed information about a specific season, including its title, description, and associated images. This endpoint is useful for displaying season details and managing individual season content.

​
Endpoint

GET /api/series/{showId}/seasons/{seasonId}

​
Path Parameters

​
showId
string
required
The unique identifier of the series that contains the season. This is the MongoDB ObjectId of the parent series.
​
seasonId
string
required
The unique identifier of the season to retrieve. This is the MongoDB ObjectId of the season.

​
Response

​
_id
string
Unique identifier for the season (MongoDB ObjectId)
​
title
string
The title of the season
​
description
string
A description of the season’s content and themes
​
images
array
Array of image objects associated with the season
​
_id
string
Unique identifier for the image
​
path
string
Relative path to the image file
​
basePath
string
Base path for constructing the full CDN URL. Prepend https://platform-static.cdn.mdstrm.com to access the image.

​
Example Request

curl -X GET "https://your-domain.com/api/series/507f1f77bcf86cd799439011/seasons/507f191e810c19729de860ea" \
  -H "Accept: application/json"

​
Example Response

{
  "_id": "507f191e810c19729de860ea",
  "title": "Season 1",
  "description": "The first season introduces the main characters and establishes the core storyline",
  "images": [
    {
      "_id": "507f191e810c19729de860eb",
      "path": "/seasons/season1-cover.jpg",
      "basePath": "/images/seasons/507f191e810c19729de860ea/season1-cover.jpg"
    }
  ]
}

​
Image URL Construction

To display season cover images, construct the full URL by combining the CDN base URL with the basePath: 
const imageUrl = (season) => {
  const basePath = season?.images?.[0]?.basePath
  return basePath
    ? `https://platform-static.cdn.mdstrm.com${basePath}`
    : 'https://mxplus.tv/images/mini-78.png' // fallback image
}
See resources/js/components/template/series/season-template.vue for the frontend implementation.

​
Error Responses

​
error
object
Error object returned when the request fails
​
message
string
Description of the error
​
status
number
HTTP status code

​
404 Not Found

Returned when the series or season does not exist: 
{
  "error": {
    "message": "Season not found",
    "status": 404
  }
}

​
400 Bad Request

Returned when the IDs are invalid: 
{
  "error": {
    "message": "Invalid season ID or series ID",
    "status": 400
  }
}

​
500 Internal Server Error

Returned when there’s a server-side error: 
{
  "error": {
    "message": "Internal server error",
    "status": 500
  }
}

​
Implementation Notes

  • The endpoint is implemented in app/Http/Controllers/Api/SeasonController.php in the show method
  • Both showId and seasonId are extracted from the route parameters
  • The request is proxied to the MediaStream API at /show/{showId}/season/{seasonId}
  • The controller returns the raw JSON response from the MediaStream service

​
Controller Implementation

From app/Http/Controllers/Api/SeasonController.php: 
public function show(Request $request)
{
    $showId = $request->route('showId');
    $seasonId = $request->route('seasonId');

    $response = MediastreamService::request(
        '/show/' . $showId . '/season/' . $seasonId,
        'get'
    );

    return $response->json();
}

List Seasons

View all seasons for a series

Update Season

Modify season information

Delete Season

Remove the season

List Episodes

View episodes in this season

Build docs developers (and LLMs) love

Get started for freeTalk to us