Skip to main content
POST
/
api
/
series
/
{showId}
/
seasons
Create Season
curl --request POST \
  --url https://api.example.com/api/series/{showId}/seasons \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "description": "<string>"
}
'
{
  "_id": "<string>",
  "title": "<string>",
  "description": "<string>",
  "images": [
    {}
  ],
  "error": {
    "message": "<string>",
    "status": 123
  }
}

​
Overview

Creates a new season within a specific series. Seasons organize episodes into logical groups, typically representing different production periods or story arcs.

​
Endpoint

POST /api/series/{showId}/seasons

​
Path Parameters

​
showId
string
required
The unique identifier of the series to which this season will be added. This is the MongoDB ObjectId of the series.

​
Body Parameters

​
title
string
required
The title of the season. Common formats include:
  • “Season 1”, “Season 2”, etc.
  • “Temporada 1”, “Temporada 2” (Spanish)
  • Custom names like “The Beginning”, “Origins”
​
description
string
required
A description of the season’s content, themes, or story arc. This helps users understand what to expect from the season.

​
Response

​
_id
string
Unique identifier for the newly created season (MongoDB ObjectId)
​
title
string
The title of the season as provided in the request
​
description
string
The description of the season as provided in the request
​
images
array
Array of image objects. Initially empty unless images are uploaded during creation.

​
Example Request

curl -X POST "https://your-domain.com/api/series/507f1f77bcf86cd799439011/seasons" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Season 1",
    "description": "The first season introduces the main characters and establishes the core storyline"
  }'

​
Example Response

{
  "_id": "507f191e810c19729de860ea",
  "title": "Season 1",
  "description": "The first season introduces the main characters and establishes the core storyline",
  "images": []
}

​
Error Responses

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

​
400 Bad Request

Returned when required fields are missing or invalid: 
{
  "error": {
    "message": "Validation failed",
    "status": 400,
    "details": {
      "title": ["The title field is required"],
      "description": ["The description field is required"]
    }
  }
}

​
404 Not Found

Returned when the parent series does not exist: 
{
  "error": {
    "message": "Series not found",
    "status": 404
  }
}

​
500 Internal Server Error

Returned when there’s a server-side error: 
{
  "error": {
    "message": "Failed to create season",
    "status": 500
  }
}

​
Implementation Notes

  • The endpoint is defined in routes/api.php using Laravel’s nested resource routing
  • The SeasonController::store method in app/Http/Controllers/Api/SeasonController.php handles the request
  • All request data is forwarded to the MediaStream API service via MediastreamService::request()
  • The season is automatically associated with the parent series via the showId path parameter
  • Images can be added to the season later through the media upload endpoints

​
Frontend Integration

The frontend uses Inertia.js forms to create seasons. Here’s the Vue.js implementation: 
<Form
  v-bind="apiSeasons.store.form({ showId: props.showId })"
  :reset-on-success="['title', 'description']"
  v-slot="{ errors, processing }"
>
  <Input 
    id="title" 
    name="title" 
    type="text" 
    placeholder="Nombre de la temporada" 
    :disabled="processing" 
    required 
  />
  
  <Input 
    id="description" 
    name="description" 
    type="text" 
    placeholder="Descripción de la temporada" 
    :disabled="processing" 
    required 
  />
  
  <Button type="submit" :disabled="processing">
    Añadir temporada
  </Button>
</Form>
See resources/js/pages/(media)/series/[showId]/seasons/create/index.vue for the complete implementation.

List Seasons

View all seasons for a series

Update Season

Modify season details

Get Season

Retrieve a specific season

Create Episode

Add episodes to the season

Build docs developers (and LLMs) love

Get started for freeTalk to us