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

​
Overview

This endpoint creates a new episode within a specific season of a series. Episodes contain video content, metadata, and can be played back using the MediaStream player.

​
Path Parameters

​
showId
string
required
The unique identifier of the series
​
seasonId
string
required
The unique identifier of the season

​
Body Parameters

​
title
string
required
The episode title (e.g., “Episode 1: Pilot”, “Introduction to Laravel”)
​
description
string
required
A description of what happens in this episode
​
content
array
required
The video content associated with this episode. Must contain video IDs from MediaStream.
[
  {
    "value": {
      "_id": "5f8a3d2b1c9d440000123456"
    }
  }
]
​
images
array
Optional array of thumbnail images for the episode

​
Request Example

curl -X POST "https://your-domain.com/api/series/abc123/seasons/def456/chapters" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "Episode 1: Getting Started",
    "description": "An introduction to the series and what to expect",
    "content": [
      {
        "value": {
          "_id": "5f8a3d2b1c9d440000123456"
        }
      }
    ]
  }'

​
Response

​
_id
string
Unique identifier for the newly created episode
​
title
string
The episode title
​
description
string
The episode description
​
content
array
The video content array
​
images
array
Episode thumbnail images

​
Success Response Example

{
  "_id": "64a7f2b1c8d4e12345abcdef",
  "title": "Episode 1: Getting Started",
  "description": "An introduction to the series and what to expect",
  "content": [
    {
      "value": {
        "_id": "5f8a3d2b1c9d440000123456"
      }
    }
  ],
  "images": [],
  "createdAt": "2024-03-05T10:30:00Z",
  "updatedAt": "2024-03-05T10:30:00Z"
}

​
Error Responses

Missing required fields or invalid data format.
{
  "error": "Validation failed",
  "details": {
    "title": "The title field is required",
    "content": "The content field is required"
  }
}
The specified series or season does not exist.
{
  "error": "Season not found"
}
Invalid or missing API authentication.
{
  "error": "Unauthorized access"
}
Server error while creating the episode.
{
  "error": "Failed to create episode"
}

​
Notes

Before creating an episode, ensure that:
  1. The parent series and season exist
  2. Video content has been uploaded to MediaStream
  3. You have valid video IDs from MediaStream
The content field must contain valid MediaStream video IDs. Invalid or non-existent video IDs will cause playback errors.
You can create episodes without images initially and add them later using the update endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us