---
title: "Shows"
canonical: "https://docs.pbs.org/space/CDA/3053062/Shows"
format: markdown
---
- [Overview](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Overview)
- [Endpoints](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Endpoints)
- [Show Fields](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Show-Fields)
- [List Shows](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#List-Shows)
- [Get Show](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Get-Show)
- [Update Show](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Update-Show)
- [Search Shows](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Search-Shows)
- [Query Parameters (List and Get)](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Query-Parameters-(List-and-Get))
- [Genre List](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Genre-List)
- [Platform List](https://pbsdigital.atlassian.net/wiki/spaces/PROD/pages/edit-v2/1141047312#Platform-List)

## Overview

A show resource is a top-level container representing a PBS program. It holds metadata, images, and links to related child resources including specials, seasons, episodes, collections, and show-level video assets (clips and previews that belong directly to the show rather than to an episode). A show cannot include full length video assets.

A show can be uniquely identified by `id`, `slug`. If retrieving a resource by its slug, do not store the slug value as it may change. The `id` never changes.

Shows are not created or deleted via the API. The only writable field is `metadatabankid` (via PATCH), which is managed by PBS internal staff.

## Endpoints

| Method | URL | Description |
| --- | --- | --- |
| GET | `/shows/` | List all shows |
| GET | `/franchises/{franchise_id}/shows/` | List shows for a franchise |
| GET | `/shows/{id|slug|metadatabankid}/` | Get a single show by ID, slug, or Metadata Bank ID |
| PATCH | `/shows/{id}/` | Update a show (metadatabankid only) |
| GET | `/shows/search/` | Search shows |

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

## Show Fields

Fields returned on GET requests. The only field available for update is `metadatabankid`.

| Field | Type | Description | Update |
| --- | --- | --- | --- |
| `type` | string | Object type |  |
| `id` | string (UUID) | Unique PBS content identifier | — |
| `title` | string | Show title (256 characters max) | — |
| `title_sortable` | string | Title without leading articles, used for alphabetical sorting | — |
| `slug` | string | URL-friendly identifier. Unique across all shows. | — |
| `tms_id` | string | Gracenote/TMS identifier (e.g., `SH000031630000`). Read-only. | — |
| `nola` | string | Four-character ID for national shows, assigned by PBS Programming | — |
| `description_short` | string | Short description (100 characters max) | — |
| `description_long` | string | Long description (400 characters max) | — |
| `premiered_on` | date (YYYY-MM-DD) | Earliest release date – broadcast or digital | — |
| `funder_message` | string | Show funder messaging. May contain HTML. Not inherited from franchise. | — |
| `is_excluded_from_dfp` | boolean | Whether the show is excluded from advertising requirements. Default: `false` | — |
| `hashtag` | string | Social media hashtag for the show | — |
| `language` | string | Language code (e.g., `en`, `es`) | — |
| `display_episode_number` | boolean | Whether to display episode numbers. Default: `true` | — |
| `can_embed_player` | boolean | Whether the viral player can be embedded. Restricts content length to 20 minutes. | — |
| `ordinal_season` | boolean | Whether seasons use ordinal numbering (1, 2, 3) vs. year-based (2017, 2018, 2019) | — |
| `sort_episodes_descending` | boolean | Whether episodes within seasons are sorted in descending order | — |
| `private` | boolean | Whether the show and its child objects should be hidden from front-end client applications | — |
| `featured_preview` | string (nullable) | PBS Content ID (UUID) of the assigned Featured Preview video asset for the show, or `null`. When assigned, used as the preview video on [pbs.org](http://pbs.org) show pages. Can only be edited in the Media Manager console. | — |
| `drm_enabled` | boolean | When `true`, all child assets ingested (or re-ingested) going forward will be DRM-enabled. Not retroactive. Managed by PBS internal staff only. | — |
| `tracking_ga_page` | string | Google Analytics page tracking ID | — |
| `tracking_ga_event` | string | Google Analytics event tracking ID | — |
| `genre` | object | Genre classification. Contains `id`, `slug`, `title`, `title_sortable`, `updated_at`. See Genre List below. | — |
| `links` | list of objects | External links associated with the show (e.g., producer site, social media, purchase links). Each object contains `value` (URL), `profile` (string), and `updated_at` (datetime). Read-only. | — |
| `images` | list of objects | Show images (logos, banners, posters, etc.). Each object contains `profile` (string), `image` (URL), and `updated_at` (datetime). Read-only. | — |
| `franchise` | object (nullable) | Parent franchise, if one exists. Contains `id`, `title`, `slug`, and resource links. `null` if the show is not part of a franchise. | — |
| `api_countries` | list of objects (nullable) | Calculated field indicating country availability for the show's published, full-length video assets. Updated hourly; reflects publish state only, not date/time-based availability windows.<br>A list of country objects means at least one full-length asset is geo-restricted to those countries; an empty list means at least one is set to All Countries; `null` means no full-length assets are published.<br>[Note] `api_countries`** **is **not** a representation of (or synced with) the Geo Availability fields for the show object in the MM console UI. It is expected that the values of both fields may *not necessarily* match. | — |
| `audience` | list of objects | Audience configuration. Each object contains `scope` (string: `national`, `local`, or `kids`) and `station` (string or `null`). | — |
| `platforms` | list of objects | Platforms on which the show is available (e.g., All Platforms, Partner Player, [PBS.org](http://PBS.org)). Each object contains `id`, `name`, `slug`, `updated_at`. See Platform List below. Can filter shows by platform — see Query Parameters. | — |
| `episodes_count` | integer | Total number of episodes belonging to the show | — |
| `external_metadata` | object (nullable) | Metadata collected from external systems (e.g., Metadata Bank). Contains the resource's `metadatabankid` when assigned. **Only returned when **`fetch-related`** is used.** [Note] This field is a work in progress — not all shows will have it populated, and the data should not be relied upon until this notice is removed. | — |
| `metadatabankid` | string | Metadata Bank ID (e.g., `cid:org:pbs.org:Series503`). Pass `null` to remove. Internal PBS use only. Not returned as a top-level attribute — available within `external_metadata` when using `fetch-related`. | Optional |
| `updated_at` | datetime | Timestamp of last update in UTC (read-only) | — |

### Related Object Fields (in GET responses)

GET responses include nested **genre**, **franchise** (when present), **audience**, and **platforms** objects as part of the show attributes. When using the `fetch-related` parameter, **assets** (show-level clips and previews — the 10 most recent by encore date), **seasons** (the 10 most recent), **specials** (the 10 most recent), **collections**, and **external_metadata** (metadata from external systems such as Metadata Bank) 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 Shows

`GET /shows/`

Returns all shows. Results are paginated. Response is similar to the single show response below, but this one returns a list of all shows.

Shows can also be listed for a specific franchise:

`GET /franchises/{franchise_id}/shows/`

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `franchise_id` | string | PBS content ID of the franchise (only for franchise-scoped listing) |

### Example Request

```
GET https://media.services.pbs.org/api/v1/shows/​
```

## Get Show

`GET /shows/{id|slug|metadatabankid}/`

Returns a single show by its ID, slug, or Metadata Bank ID.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | PBS content ID of the show |
| `slug` | string | URL slug of the show (alternative to ID) |
| `metadatabankid` | string | Metadata Bank ID (alternative to ID or slug). Uses the format `cid:org:pbs.org:Series{id}`. |

### Example Requests

**By ID:**

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

**By Metadata Bank ID:**

```
GET https://media.services.pbs.org/api/v1/shows/cid:org:pbs.org:Series503/​
```

### Example Response

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "type": "show",
    "id": "adfb2f9d-f61e-4613-ac58-ab3bde582afb",
    "attributes": {
      "slug": "nova",
      "nola": "NOVA",
      "title": "NOVA",
      "title_sortable": "NOVA",
      "tms_id": "SH000031630000",
      "description_short": "Explore scientific discoveries on television's most acclaimed science documentary series.",
      "description_long": "NOVA brings you stories from the frontlines of science and engineering, answering the big questions of today and tomorrow, from how our ancestors lived, to whether parallel universes exist, to how technology will transform our lives. Visit the official website to watch full-length documentaries, or explore our world through short-form video, on our digital publication NOVA Next.",
      "premiered_on": "2022-05-25",
      "is_excluded_from_dfp": false,
      "funder_message": "National Corporate funding for NOVA is provided by <a href=\"https://www.carlisle.com/\" target=\"_blank\">Carlisle Companies</a>. Major funding for NOVA is provided by the NOVA Science Trust and PBS viewers.",
      "tracking_ga_page": "UA-3988832-1",
      "tracking_ga_event": "UA-3988832-2",
      "updated_at": "2026-06-24T14:31:26.538876Z",
      "hashtag": "novapbs",
      "display_episode_number": true,
      "can_embed_player": true,
      "language": "en",
      "ordinal_season": true,
      "sort_episodes_descending": true,
      "private": false,
      "featured_preview": null,
      "drm_enabled": false,
      "genre": {
        "id": "09684cc5-9a7e-460f-841f-4d95987a8f53",
        "slug": "science-and-nature",
        "title": "Science and Nature",
        "title_sortable": "Science and Nature",
        "updated_at": "2018-01-29T12:16:58.141587Z"
      },
      "links": [
        {
          "value": "https://www.pbs.org/wgbh/nova/",
          "profile": "producer",
          "updated_at": "2024-09-30T20:48:30.200080Z"
        },
        {
          "value": "https://tv.apple.com/season/season-1/umc.cmc.isols7d6bxnwgqbsvwrc2ewl?showId=umc.cmc.4ea0iyht1e3466mbex6illnw6&itscg=30200&itsct=tv_box_link&mttnsubad=umc.cmc.isols7d6bxnwgqbsvwrc2ewl",
          "profile": "itunes",
          "updated_at": "2025-12-04T14:32:58.953347Z"
        },
        {
          "value": "https://www.amazon.com/gp/video/detail/B0FXZ9VHQZ?sr=1-1&pageTypeIdSource=ASIN&pageTypeId=B0FXZ8JYM2&qid=1764624102520&linkCode=ll2&tag=p05a2-20&linkId=924724058c6aed70fdb5bc9ffb2a6830&language=en_US&ref_=as_li_ss_tl",
          "profile": "amazon",
          "updated_at": "2025-12-04T14:32:58.895519Z"
        },
        {
          "value": "https://www.facebook.com/NOVApbs/",
          "profile": "facebook",
          "updated_at": "2017-05-04T19:01:43.779234Z"
        },
        {
          "value": "https://www.instagram.com/novapbs/",
          "profile": "instagram",
          "updated_at": "2018-03-13T16:06:18.737120Z"
        },
        {
          "value": "https://twitter.com/novapbs",
          "profile": "twitter",
          "updated_at": "2017-05-04T19:01:43.779290Z"
        },
        {
          "value": "https://tv.apple.com/season/season-1/umc.cmc.isols7d6bxnwgqbsvwrc2ewl?showId=umc.cmc.4ea0iyht1e3466mbex6illnw6&itscg=30200&itsct=tv_box_link&mttnsubad=umc.cmc.isols7d6bxnwgqbsvwrc2ewliOS",
          "profile": "ios",
          "updated_at": "2025-12-04T14:32:58.836967Z"
        },
        {
          "value": "https://tv.apple.com/season/season-1/umc.cmc.isols7d6bxnwgqbsvwrc2ewl?showId=umc.cmc.4ea0iyht1e3466mbex6illnw6&itscg=30200&itsct=tv_box_link&mttnsubad=umc.cmc.isols7d6bxnwgqbsvwrc2ewlAppleTV",
          "profile": "apple-tv",
          "updated_at": "2025-12-04T14:32:58.762154Z"
        },
        {
          "value": "http://dun96pyxwe2yl.cloudfront.net/apple-universal-search/images/nova.lsr",
          "profile": "apple-lsr-format",
          "updated_at": "2018-09-25T20:38:56.872374Z"
        }
      ],
      "images": [
        {
          "profile": "show-logo",
          "image": "https://image.pbs.org/contentchannels/x84ICtA-show-logo-QwNUUpm.png",
          "updated_at": "2018-11-16T13:57:54.163338Z"
        },
        {
          "profile": "show-mezzanine16x9",
          "image": "https://image.pbs.org/contentchannels/0McsXg0-show-mezzanine16x9-4PvNQjz.jpg",
          "updated_at": "2019-09-05T20:45:40.890733Z"
        },
        {
          "profile": "show-poster2x3",
          "image": "https://image.pbs.org/contentchannels/ED6PSZP-show-poster2x3-Ve6hmZh.jpg",
          "updated_at": "2019-09-05T20:45:44.733860Z"
        },
        {
          "profile": "show-banner",
          "image": "https://image.pbs.org/contentchannels/OXIB9I7-show-banner-gzPZlcB.jpg",
          "updated_at": "2019-09-05T20:45:36.566703Z"
        },
        {
          "profile": "show-showcase",
          "image": "https://image.pbs.org/contentchannels/mVlNXsP-show-showcase-RFTayxC.jpg",
          "updated_at": "2019-09-05T20:45:48.627041Z"
        },
        {
          "profile": "show-white-logo",
          "image": "https://image.pbs.org/contentchannels/bpUrnFT-show-white-logo-Lta9Ovj.png",
          "updated_at": "2018-11-16T13:59:49.426558Z"
        },
        {
          "profile": "show-black-logo",
          "image": "https://image.pbs.org/contentchannels/Mn2m9YZ-show-black-logo-WeZsTgk.png",
          "updated_at": "2018-11-16T13:59:48.909188Z"
        },
        {
          "profile": "show-color-logo",
          "image": "https://image.pbs.org/contentchannels/ELT3Coa-show-color-logo-lGR9Jbo.png",
          "updated_at": "2018-11-16T13:59:49.330029Z"
        },
        {
          "profile": "white-logo-41",
          "image": "https://image.pbs.org/contentchannels/iAn87U1-white-logo-41-7WCUoLi.png",
          "updated_at": "2018-11-16T13:58:58.722015Z"
        },
        {
          "profile": "black-logo-41",
          "image": "https://image.pbs.org/contentchannels/2QgZxea-black-logo-41-Ljoc6Rt.png",
          "updated_at": "2018-11-16T13:56:49.316187Z"
        },
        {
          "profile": "color-logo-41",
          "image": "https://image.pbs.org/contentchannels/6bOWWC4-color-logo-41-OsgcRfx.png",
          "updated_at": "2018-11-16T13:56:49.601939Z"
        }
      ],
      "franchise": null,
      "api_countries": [],
      "audience": [
        {
          "scope": "national",
          "station": null
        }
      ],
      "platforms": [
        {
          "id": "e5a289b8-01b3-41ce-92c1-3eb5a4e14bc0",
          "name": "All Platforms",
          "slug": "allplatforms",
          "updated_at": "2017-04-03T15:57:09.459445Z"
        }
      ],
      "episodes_count": 398
    }
  },
  "meta": {
    "type": "resource"
  },
  "links": {
    "self": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/",
    "assets": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/assets/",
    "seasons": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/seasons/",
    "specials": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/specials/",
    "collections": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/collections/",
    "taxonomies": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/taxonomies/"
  }
}
```

## Update Show

`PATCH /shows/{id}/`

Updates an existing show. A successful request returns **204 No Content**. The only field that can be updated via the API is `metadatabankid`.

### URL Parameters

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

### Required Headers

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

### Payload Fields

| Field | Type | Notes |
| --- | --- | --- |
| `metadatabankid` | string | Metadata Bank ID. Pass `null` to remove. Internal PBS use only. |

### Example Payload

```
{
  "data": {
    "type": "show",
    "id": "{show_id}",
    "attributes": {
      "metadatabankid": "cid:org:pbs.org:Series503"
    }
  }
}​
```

> 📝 To remove a Metadata Bank ID, pass `"metadatabankid": null`. This field is expected to be used only by the PBS internal Metadata Bank team.

### Response

**204 No Content** on success.

## Search Shows

`GET /shows/search/`

Full-text search across show titles. The `query` parameter is required.

### Query Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search term — matches against show title. Values must be URL-encoded. |
| `show-slug` | string | No | Filter by exact show slug |
| `country` | string | No | Upper-case two-letter country code. Shows with at least one full-length asset available in the specified country. Multiple values supported. Secondary filter — does not work standalone. |
| `drm-enabled` | boolean | No | Filter shows by DRM protection status |
| `platform-slug` | string | No | Filter by platform slug |
| `platform-id` | string | No | Filter by platform ID |
| `page-size` | integer | No | Results per page (max 50) |
| `page` | integer | No | Page number |

### Example Request

```
GET https://media.services.pbs.org/api/v1/shows/search/?query=nova​
```

## 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 in the response: show-level `assets` (clips and previews — the 10 most recent by encore date), `seasons` (the 10 most recent), `specials` (the 10 most recent), `collections`, and `external_metadata` (metadata from external systems, when available). |
| `slug` | string | Filter by exact show slug |
| `franchise-slug` | string | Filter shows by franchise slug. Multiple values supported. |
| `franchise-id` | string | Filter shows by franchise ID. Multiple values supported. |
| `genre-slug` | string | Filter shows by genre slug. Multiple values supported. See Genre List below. |
| `genre-id` | string | Filter shows by genre ID. Multiple values supported. See Genre List below. |
| `audience-scope` | string | Filter by audience scope: `national`, `local`, or `kids`. If `local`, the `audience` parameter must also be provided. |
| `audience` | string | Station call sign. Only has an effect when `audience-scope=local`. Multiple values supported (comma-separated). |
| `nola` | string | Filter by show/franchise root NOLA code |
| `platform-slug` | string | Filter by platform slug. If not specified, only shows available to All Platforms are returned. Multiple values supported. See Platform List below. |
| `platform-id` | string | Filter by platform ID. Multiple values supported. See Platform List below. |
| `drm-enabled` | boolean | Filter shows by DRM protection status |
| `sort` | string | Sort results by a specific field. Available sort fields are listed in the response `meta.sort` block. |
| `page` | integer | Page number |
| `id` | string | Filter by one or more show IDs (repeat parameter for multiple) |

### Filtering Examples

**Filtering by multiple IDs**

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

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

**Filtering by slug**

```
GET https://media.services.pbs.org/api/v1/shows/?slug=downton-abbey​
```

Returns 1 or 0 results (exact match).

**Filtering by franchise slug**

```
GET https://media.services.pbs.org/api/v1/shows/?franchise-slug={slug}&franchise-slug={slug}​
```

Returns 0 or more shows belonging to the specified franchise(s).

**Filtering by franchise ID**

```
GET https://media.services.pbs.org/api/v1/shows/?franchise-id={id}&franchise-id={id}​
```

**Filtering by genre slug**

```
GET https://media.services.pbs.org/api/v1/shows/?genre-slug={slug}&genre-slug={slug}​
```

Returns 0 or more shows matching the specified genre(s). See Genre List below.

**Filtering by genre ID**

```
GET https://media.services.pbs.org/api/v1/shows/?genre-id={id}&genre-id={id}​
```

**Filtering by audience**

```
GET https://media.services.pbs.org/api/v1/shows/?audience-scope=national
GET https://media.services.pbs.org/api/v1/shows/?audience-scope=local&audience={call-sign}&audience={call-sign}​
```

When `audience-scope=local`, the `audience` parameter (station call sign) is required. Multiple call signs can be provided.

**Filtering by platform**

```
GET https://media.services.pbs.org/api/v1/shows/?platform-slug=partnerplayer
GET https://media.services.pbs.org/api/v1/shows/?platform-slug=partnerplayer&platform-slug=bento​
```

If no platform filter is applied, only shows available to All Platforms are returned. If a platform filter is applied (e.g., `partnerplayer`), shows available to that platform *and* All Platforms are returned. See Platform List below.

## Genre List

Use the endpoint below to get a list of all available genres:

```
GET https://media.services.pbs.org/api/v1/genres/​
```

Or, get info about an individual genre by passing its slug or id. Examples:

```
GET https://media.services.pbs.org/api/v1/genres/drama/
GET https://media.services.pbs.org/api/v1/genres/a6c8f8a3-fd3a-4ffe-9a0d-d32e6e584d5d/​
```

## Platform List

Use the endpoint below to get a list of all available platforms:

```
GET https://media.services.pbs.org/api/v1/platforms/​
```

Or, get info about an individual platform by passing its slug or id. Examples:

```
GET https://media.services.pbs.org/api/v1/platforms/partnerplayer/
GET https://media.services.pbs.org/api/v1/platforms/22f85aa7-cffc-462f-bd65-14218960ac5c/​
```