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

## Overview

A franchise resource represents the metadata and images associated with an umbrella/parent brand, such as Masterpiece or Walter Presents. It can include some video asset types — clips (any number), previews (any number) — but it primarily serves as a container for all shows associated to the franchise. A franchise cannot include full length video assets.

A franchise can be uniquely identified by `id` or `slug`. You can also query the franchise list endpoint by slug (case sensitive). If retrieving a resource by its slug, do not store the slug value as it may change. The `id` never changes.

## Endpoints

| Method | URL | Description |
| --- | --- | --- |
| GET | `/franchises/` | List all franchises |
| GET | `/franchises/{id|slug}/` | Get a single franchise |
| GET | `/franchises/search/` | Search franchises |

> ℹ️ 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.

## Franchise Fields

Fields returned on GET requests. Since there is no Create endpoint, the Create column is not applicable. The Update column reflects the PATCH endpoint, but the public docs do not specify which fields are updatable — see the note below the table.

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Object type |
| `id` | string (UUID) | Unique PBS content identifier |
| `slug` | string | URL-friendly identifier (unique across all franchises) |
| `nola` | string | Four-letter NOLA identifier of the franchise |
| `title` | string | Franchise title (256 characters max) |
| `title_sortable` | string | Title without leading articles, used for alphabetical sorting |
| `genre` | object or null | Genre associated with the franchise |
| `description_short` | string | Short description (100 characters max) |
| `description_long` | string | Long description (400 characters max) |
| `premiered_on` | datetime | Date on which the franchise premiered |
| `is_excluded_from_dfp` | boolean | Whether the franchise is excluded from DFP/Google Ad Manager sponsorship |
| `funder_message` | string | Franchise funder messaging |
| `tracking_ga_page` | string | Google Analytics page tracking code |
| `tracking_ga_event` | string | Google Analytics event tracking code |
| `updated_at` | datetime | Timestamp of last update in UTC (read-only) |
| `links` | list of objects | External links associated with the franchise (producer site, social media) |
| `hashtag` | string | Social media hashtag or handle |
| `images` | list of objects | Images associated with the franchise (see example response for structure) |
| `platforms` | list of objects | Platforms on which the franchise is available (see example response for structure) |

### Related Object Fields (in GET responses)

GET responses include nested objects for **genre**, **images**, **platforms**, and **links** as part of the franchise attributes. When using the `fetch-related` parameter, **assets** are also included. See the example responses below for the structure of these nested objects.

## List Franchises

`GET /franchises/`

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

### Example Request

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

## Get Franchise

`GET /franchises/{id|slug}/`

Returns a single franchise by its ID or slug.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | PBS content ID of the franchise |
| `slug` | string | URL slug of the franchise (alternative to ID) |

### Example Request

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

### Example Response

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "type": "franchise",
    "id": "f7062296-fa3d-4393-8b50-c0cac2db9a6d",
    "attributes": {
      "slug": "ken-burns",
      "nola": "",
      "title": "Ken Burns",
      "title_sortable": "Ken Burns",
      "genre": {
        "id": "d68d138e-dae6-4fa9-9148-addc88fa6efb",
        "slug": "history",
        "title": "History",
        "title_sortable": "History",
        "updated_at": "2017-04-04T10:27:45.732884Z"
      },
      "description_short": "Ken Burns and colleagues produce critically acclaimed documentaries for public television.",
      "description_long": "For more than four decades, Ken Burns and his colleagues at Florentine Films—directors, writers, producers, editors, and cinematographers—have produced some of the most critically acclaimed and most-watched documentaries on public television.",
      "premiered_on": null,
      "is_excluded_from_dfp": false,
      "funder_message": "Florentine Films is grateful for the generous support over the years from numerous funders including Bank of America; Members of The Better Angels Society National Endowment for the Humanities; The Arthur Vining Davis Foundations; Corporation for Public Broadcasting; The Pew Charitable Trusts; General Motors Corporation; and the Park Foundation Inc.",
      "tracking_ga_page": "",
      "tracking_ga_event": "",
      "updated_at": "2026-05-19T18:02:34.728394Z",
      "links": [
        {
          "value": "https://www.pbs.org/kenburns/",
          "profile": "producer",
          "updated_at": "2020-07-24T17:08:34.160107Z"
        },
        {
          "value": "https://www.facebook.com/kenburnspbs/",
          "profile": "facebook",
          "updated_at": "2017-09-14T15:53:24.537921Z"
        },
        {
          "value": "https://twitter.com/KenBurns",
          "profile": "twitter",
          "updated_at": "2017-09-14T15:53:24.653676Z"
        }
      ],
      "hashtag": "",
      "images": [
        {
          "profile": "franchise-poster2x3",
          "image": "https://image.pbs.org/contentchannels/JAtpYf7-franchise-poster2x3-XiKpcHP.jpg",
          "updated_at": "2017-09-14T15:31:36.155992Z"
        },
        {
          "profile": "black-logo-41",
          "image": "https://image.pbs.org/contentchannels/fFNdO4G-black-logo-41-BxxqqW8.png",
          "updated_at": "2023-06-21T13:56:05.908533Z"
        },
        {
          "profile": "color-logo-41",
          "image": "https://image.pbs.org/contentchannels/chBiQAw-color-logo-41-iUDq24I.png",
          "updated_at": "2023-06-21T13:56:05.438219Z"
        },
        {
          "profile": "white-logo-41",
          "image": "https://image.pbs.org/contentchannels/Pdd5KQc-white-logo-41-0IJv1Ft.png",
          "updated_at": "2023-06-21T13:56:05.654010Z"
        },
        {
          "profile": "background",
          "image": "https://image.pbs.org/contentchannels/NyFTXyc-background-JFL5XDk.jpg",
          "updated_at": "2021-03-17T15:57:01.901559Z"
        }
      ],
      "platforms": [
        {
          "id": "e5a289b8-01b3-41ce-92c1-3eb5a4e14bc0",
          "name": "All Platforms",
          "slug": "allplatforms",
          "updated_at": "2017-04-03T15:57:09.459445Z"
        }
      ]
    }
  },
  "meta": {
    "type": "resource"
  },
  "links": {
    "self": "https://media.services.pbs.org/api/v1/franchises/f7062296-fa3d-4393-8b50-c0cac2db9a6d/",
    "assets": "https://media.services.pbs.org/api/v1/franchises/f7062296-fa3d-4393-8b50-c0cac2db9a6d/assets/",
    "shows": "https://media.services.pbs.org/api/v1/franchises/f7062296-fa3d-4393-8b50-c0cac2db9a6d/shows/",
    "taxonomies": "https://media.services.pbs.org/api/v1/franchises/f7062296-fa3d-4393-8b50-c0cac2db9a6d/taxonomies/"
  }
}
```

### Required Headers

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

### Response

**204 No Content** on success.

## Search Franchises

`GET /franchises/search/`

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

### Query Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search term — matches against franchise title. Values must be URL-encoded. |
| `platform-slug` | string | No | Filter by platform slug |
| `platform-id` | string | No | Filter by platform ID |
| `page-size` | integer | No | Results per page |
| `page` | integer | No | Page number |

### Example Request

```
GET https://media.services.pbs.org/api/v1/franchises/search/?query=america
```

## Query Parameters (List and Get)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `slug` | string | Filter by exact slug match. Returns 0 or 1 result. |
| `fetch-related` | flag | Include related assets in the response. Returns the 10 most recent assets by encore date. |
| `platform-slug` | string | Filter by platform slug. Can be repeated for multiple platforms (e.g., `?platform-slug=partnerplayer&platform-slug=bento`). If no platform filter is applied, only franchises available to All Platforms are returned. |
| `platform-id` | string | Filter by platform ID |
| `sort` | string | Sort results. Available fields: `title`, `title_sortable`. Prefix with `-` for descending (e.g., `?sort=-title`). |
| `page` | integer | Page number |
| `id` | string | Filter by one or more franchise IDs (repeat parameter for multiple) |

### Filtering by Slug

```
GET https://media.services.pbs.org/api/v1/franchises/?slug=masterpiece
```

Returns 0 or 1 result (exact match).

### Filtering by Multiple IDs

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

Returns 0 or more matching franchises.