---
title: "Seasons"
canonical: "https://docs.pbs.org/space/CDA/3051747/Seasons"
format: markdown
---
> Macro (toc)

## Overview

A season resource represents a season within a show. It can include some video asset types — clips (any number), previews (any number) — but it primarily serves as a container for all episodes associated to the season. A season cannot include full length video assets.

A season can be uniquely identified by its `id`. Seasons do not have slugs.

Seasons support **Create** and **Update** but have no Delete or Search endpoints.

## Endpoints

| Method | URL | Description |
| --- | --- | --- |
| GET | `/shows/{show_id}/seasons/` | List seasons for a show |
| GET | `/seasons/{id}/` | Get a single season |
| POST | `/shows/{show_id}/seasons/` | Create a season |
| PATCH | `/seasons/{id}/` | Update a season |

> ℹ️ All URLs require the base endpoint prefix and a trailing slash. See [Resources](https://docs.pbs.org/space/CDA/3058039/Resources) for base endpoint and testing environment details.

## Season Fields

Fields returned on GET requests and available for create/update operations.

| Field | Type | Description | Create | Update |
| --- | --- | --- | --- | --- |
| `type` | string | Object type | — | — |
| `id` | string (UUID) | Unique PBS content identifier | — | — |
| `ordinal` | integer | Season number. Can be incremental (1, 2, 3) or year-based (2023, 2024). Must be unique within its show. | Required | Optional |
| `title` | string | Season title (60 characters max). Titles are not commonly used for seasons in Media Manager. | Optional | Optional |
| `title_sortable` | string | Title without leading articles, used for alphabetical sorting (read-only) | — | — |
| `description_short` | string | Short description (100 characters max). Descriptions are not commonly used for seasons. | Optional | Optional |
| `description_long` | string | Long description (400 characters max). Descriptions are not commonly used for seasons. | Optional | Optional |
| `updated_at` | datetime | Timestamp of last update in UTC (read-only) | — | — |
| `latest_asset_images` | list of objects | Most recent asset image associated with the season. Each object contains `image` (URL), `profile` (string, e.g., `asset-mezzanine-16x9`), and `updated_at` (datetime). Read-only. | — | — |
| `image` | object | Source URL of the 16:9 Mezzanine image to be ingested. Recommended to use PBS-hosted ITS images. Images are not commonly used for seasons. Payload format: `{"source": "https://..."}` | Optional | Optional |
| `show` | object | Nested object containing details about the episode’s parent show. | — | — |
| `links` | list of objects | External links associated with the season (e.g., Amazon, iTunes). Each object contains `value` (URL), `profile` (string, e.g., `amazon`, `itunes`), and `updated_at` (datetime). Read-only. | — | — |
| `metadatabankid` | string | Metadata Bank ID. **Internal PBS use only. **Available if `external_metadata` is populated in GET responses when using the `fetch-related` parameter.<br>Pass `null` to remove. | — | Optional |

### Related Object Fields (in GET responses)

GET responses include a nested **show** object. When using the `fetch-related` parameter, **episodes** and **assets** are also included. See the example responses below for the structure of these nested objects, or refer to each resource's own page for full field documentation.

## List Seasons

`GET /shows/{show_id}/seasons/`

Returns all seasons belonging to a show. Results are paginated. Note: seasons are listed via the show-scoped endpoint, not a top-level `/seasons/` list.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `show_id` | string | PBS content ID of the show |

### Example Request

```
GET https://media.services.pbs.org/api/v1/shows/{show_id}/seasons/
```

### Example Response

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "type": "season",
      "id": "112d1b49-1b25-48b7-931b-eec680be42ec",
      "attributes": {
        "ordinal": 2,
        "title": "",
        "title_sortable": "",
        "description_short": "Charlie is determined to honor her heritage. Samy leaves forensic medicine.",
        "description_long": "Charlie is determined to honor her heritage. Samy leaves forensic medicine and moves into the Holmes house. As the duo shakes things up, they tackle surprising cases across new worlds. From Walter Presents, in French with English subtitles.",
        "updated_at": "2026-03-30T15:05:02.344165Z",
        "latest_asset_images": [
          {
            "image": "https://image.pbs.org/video-assets/CIk8ELg-asset-mezzanine-16x9-a5hFxQl.jpg",
            "profile": "asset-mezzanine-16x9",
            "updated_at": "2026-03-30T14:12:54.539537Z"
          }
        ],
        "image": null,
        "links": []
      },
      "links": {
        "self": "https://media.services.pbs.org/api/v1/seasons/112d1b49-1b25-48b7-931b-eec680be42ec/",
        "episodes": "https://media.services.pbs.org/api/v1/seasons/112d1b49-1b25-48b7-931b-eec680be42ec/episodes/",
        "assets": "https://media.services.pbs.org/api/v1/seasons/112d1b49-1b25-48b7-931b-eec680be42ec/assets/"
      }
    },
    {
      "type": "season",
      "id": "52f1ccbb-2990-4fe5-8047-81b3a8f294c3",
      "attributes": {
        "ordinal": 1,
        "title": "Season 1",
        "title_sortable": "Season 1",
        "description_short": "Charlie teams up with her new intern, Samy--her very own Watson!",
        "description_long": "Charlie teams up with her new intern, Samy--her very own Watson! Together, they tackle all manner of crime, and Charlie finally accept herself as a police officer--and a Holmes. From Walter Presents, in French with English subtitles.",
        "updated_at": "2025-08-25T14:05:00.802333Z",
        "latest_asset_images": [
          {
            "image": "https://image.pbs.org/video-assets/9ZT2t0d-asset-mezzanine-16x9-1AfTFwO.jpg",
            "profile": "asset-mezzanine-16x9",
            "updated_at": "2025-08-25T13:26:29.807118Z"
          }
        ],
        "image": null,
        "links": []
      },
      "links": {
        "self": "https://media.services.pbs.org/api/v1/seasons/52f1ccbb-2990-4fe5-8047-81b3a8f294c3/",
        "episodes": "https://media.services.pbs.org/api/v1/seasons/52f1ccbb-2990-4fe5-8047-81b3a8f294c3/episodes/",
        "assets": "https://media.services.pbs.org/api/v1/seasons/52f1ccbb-2990-4fe5-8047-81b3a8f294c3/assets/"
      }
    }
  ],
  "meta": {
    "type": "collection",
    "filter": {
      "ordinal": "https://media.services.pbs.org/api/v1/shows/4c139a09-d4f9-4a62-b808-a4d587b71d57/seasons/?ordinal=",
      "id": "https://media.services.pbs.org/api/v1/shows/4c139a09-d4f9-4a62-b808-a4d587b71d57/seasons/?id="
    },
    "sort": {
      "ordinal": {
        "asc": "https://media.services.pbs.org/api/v1/shows/4c139a09-d4f9-4a62-b808-a4d587b71d57/seasons/?sort=ordinal",
        "desc": "https://media.services.pbs.org/api/v1/shows/4c139a09-d4f9-4a62-b808-a4d587b71d57/seasons/?sort=-ordinal"
      },
      "title_sortable": {
        "asc": "https://media.services.pbs.org/api/v1/shows/4c139a09-d4f9-4a62-b808-a4d587b71d57/seasons/?sort=title_sortable",
        "desc": "https://media.services.pbs.org/api/v1/shows/4c139a09-d4f9-4a62-b808-a4d587b71d57/seasons/?sort=-title_sortable"
      }
    },
    "pagination": {
      "per_page": 25,
      "count": 2
    }
  },
  "links": {
    "self": "https://media.services.pbs.org/api/v1/shows/4c139a09-d4f9-4a62-b808-a4d587b71d57/seasons/",
    "first": null,
    "prev": null,
    "next": null,
    "last": null
  }
}
```

## Get Season

`GET /seasons/{id}/`

Returns a single season by its ID.

> ℹ️ The single-resource response embeds the parent `show` object under `attributes`. The collection response omits it (see [Season collection example] above) — the parent show is implied by the request path (`/shows/{id}/seasons/`).

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | PBS content ID of the season |

### Example Request

```
GET https://media.services.pbs.org/api/v1/seasons/{id}/
```

### Example Response

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "type": "season",
    "id": "52f1ccbb-2990-4fe5-8047-81b3a8f294c3",
    "attributes": {
      "ordinal": 1,
      "title": "Season 1",
      "title_sortable": "Season 1",
      "description_short": "Charlie teams up with her new intern, Samy--her very own Watson!",
      "description_long": "Charlie teams up with her new intern, Samy--her very own Watson! Together, they tackle all manner of crime, and Charlie finally accept herself as a police officer--and a Holmes. From Walter Presents, in French with English subtitles.",
      "updated_at": "2025-08-25T14:05:00.802333Z",
      "latest_asset_images": [
        {
          "image": "https://image.pbs.org/video-assets/9ZT2t0d-asset-mezzanine-16x9-1AfTFwO.jpg",
          "profile": "asset-mezzanine-16x9",
          "updated_at": "2025-08-25T13:26:29.807118Z"
        }
      ],
      "image": null,
      "show": {
        "type": "show",
        "id": "4c139a09-d4f9-4a62-b808-a4d587b71d57",
        "attributes": {
          "title": "Mademoiselle Holmes",
          "title_sortable": "Mademoiselle Holmes",
          "slug": "mademoiselle-holmes",
          "display_episode_number": true,
          "updated_at": "2025-08-25T13:45:11.700502Z",
          "featured_preview": null
        },
        "links": {
          "self": "https://media.services.pbs.org/api/v1/shows/4c139a09-d4f9-4a62-b808-a4d587b71d57/"
        }
      },
      "links": []
    }
  },
  "meta": {
    "type": "resource"
  },
  "links": {
    "self": "https://media.services.pbs.org/api/v1/seasons/52f1ccbb-2990-4fe5-8047-81b3a8f294c3/",
    "episodes": "https://media.services.pbs.org/api/v1/seasons/52f1ccbb-2990-4fe5-8047-81b3a8f294c3/episodes/",
    "assets": "https://media.services.pbs.org/api/v1/seasons/52f1ccbb-2990-4fe5-8047-81b3a8f294c3/assets/"
  }
}
```

## Create Season

`POST /shows/{show_id}/seasons/`

Creates a new season within a show. A successful request returns **204 No Content**. The `Location` response header contains the URL of the newly created season.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `show_id` | string | PBS content ID of the parent show |

### Required Headers

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |

### Payload Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `type` | string | Yes |  |
| `ordinal` | integer | Yes | Must be unique within the show |
| `title` | string | No | Titles are not commonly used for seasons |
| `description_short` | string | No | 100 characters max |
| `description_long` | string | No | 400 characters max |
| `image` | object | No | Source URL of 16:9 Mezzanine image. Format: `{"source": "https://..."}` |

Fields not supported in create payload: `title_sortable`, `latest_asset_images`, `links`

### Minimal Payload

```json
{
  "data": {
    "type": "season",
    "attributes": {
      "ordinal": 1
    }
  }
}
```

### Full Payload

```json
{
  "data": {
    "type": "season",
    "attributes": {
      "ordinal": 1,
      "title": "Season One Title",
      "description_short": "Short desc",
      "description_long": "Long desc",
      "image": {
        "source": "https://image.pbs.org/image.jpg"
      }
    }
  }
}
```

### Response

**204 No Content** on success. Check the `Location` header for the new season's URL.

## Update Season

`PATCH /seasons/{id}/`

Updates an existing season. A successful request returns **204 No Content**. Include only the fields you want to change.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | PBS content ID of the season |

### Required Headers

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |

### Payload Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `type` | string | Yes |  |
| `id` | string | Yes |  |
| `ordinal` | integer | No | Must be unique within the show |
| `title` | string | No |  |
| `description_short` | string | No | 100 characters max |
| `description_long` | string | No | 400 characters max |
| `image` | object | No | Source URL of 16:9 Mezzanine image. Format: `{"source": "https://..."}` |
| `metadatabankid` | string | No | Metadata Bank ID. Pass `null` to remove. Internal PBS use only. |

Fields not supported in update payload: `title_sortable`, `latest_asset_images`, `links`

### Example Payload

```json
{
  "data": {
    "type": "season",
    "id": "{season_id}",
    "attributes": {
      "ordinal": 1,
      "title": "Season One Title",
      "description_short": "Short desc",
      "description_long": "Long desc",
      "image": {
        "source": "https://image.pbs.org/image.jpg"
      }
    }
  }
}
```

### Editing Metadata Bank ID

```json
{
  "data": {
    "type": "season",
    "id": "{season_id}",
    "attributes": {
      "metadatabankid": "cid:org:pbs.org:Season12345"
    }
  }
}
```

> 📝 The `metadatabankid` field is expected to be used only by the internal PBS Metadata Bank team.

### Response

**204 No Content** on success.

## Query Parameters (List and Get)

These parameters can be used with the List and Get endpoints.

| Parameter | Type | Description |
| --- | --- | --- |
| `fetch-related` | flag | Include related objects (Episodes and Assets) in the response. Returns the 10 most recent of each by encore date. Also surfaces additional fields like `metadatabankid`. Note: the `full_length_asset` property returns only full-length content types (null if none exist); the `assets` property returns all content types. |
| `sort` | string | Sort results. Available field: `title_sortable`. Prefix with `-` for descending. |
| `id` | string | Filter by one or more season IDs (repeat parameter for multiple) |

### Filtering by Multiple IDs

```
GET https://media.services.pbs.org/api/v1/seasons/?id={id1}&id={id2}&id={id3}
```

Returns 0 or more matching seasons. Recommend filtering no more than 50 IDs per request.