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

## Overview

A special resource is a container object associated directly to a show (not a season). Like episodes, it can include multiple video asset types — full episode (max 1), clips (any number), previews (any number). A special is for one-time-only or movie programs.

A special can be uniquely identified by `id` or `slug`. 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 | `/shows/{show_id}/specials/` | List specials for a show |
| GET | `/specials/{id|slug}/` | Get a single special |
| POST | `/shows/{show_id}/specials/` | Create a special |
| PATCH | `/specials/{id}/` | Update a special |
| DELETE | `/specials/{id}/` | Delete a special |
| GET | `/specials/search/` | Search specials |

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

## Special 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 | — | — |
| `title` | string | Special title (120 characters max) | Required | Optional |
| `title_sortable` | string | Title without leading articles, used for alphabetical sorting | Optional | Optional |
| `slug` | string | URL-friendly identifier. Must be unique across all specials. **Set on create only** — cannot be updated. | Required | — |
| `tms_id` | string | Gracenote/TMS identifier, if available. Read-only. | — | — |
| `description_short` | string | Short description (90 characters max) | Required | Optional |
| `description_long` | string | Long description (400 characters max) | Required | Optional |
| `premiered_on` | date (YYYY-MM-DD) | Original on-air or online broadcast date (no time) | Optional | Optional |
| `encored_on` | date (YYYY-MM-DD) | The on-air or online rebroadcast date (no time) | Optional | Optional |
| `nola` | string | NOLA code (National Online Locator for Archives) | Optional | Optional |
| `language` | string | Language code (e.g., `en`) | Optional | Optional |
| `updated_at` | datetime | Timestamp of last update in UTC (read-only) | — | — |
| `show` | object | Nested object containing details about the episode’s parent show. | — | — |
| `links` | list of objects | External links associated with the special (e.g., Amazon, iTunes). Each object contains `value` (URL), `profile` (string), and `updated_at` (datetime). Read-only. | — | — |
| `metadatabankid` | string | Metadata Bank ID. Pass `null` to remove. Internal PBS use only. | — | Optional |

### Related Object Fields (in GET responses)

GET responses include a nested **show** object. When using the `fetch-related` parameter, **assets**, **collections**, **full_length_asset** (a single asset object for the full-length video, if one exists), and **external_metadata** 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 Specials

`GET /shows/{show_id}/specials/`

Returns all specials belonging to a show. Results are paginated.

### 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}/specials/
```

### Example Response

```
{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "type": "special",
      "id": "0779a240-3225-44b4-9597-aee391872999",
      "attributes": {
        "title": "Interview: Dark Matter = Black Holes? with David Kaiser",
        "slug": "interview-dark-matter-black-holes-with-david-kaiser-xtpxmx",
        "title_sortable": "Interview: Dark Matter = Black Holes? with David Kaiser",
        "tms_id": "",
        "description_short": "Dark matter may be primordial black holes from the Big Bang. David Kaiser explains.",
        "description_long": "Dark matter remains one of physics' biggest open questions. MIT physicist David Kaiser joins Hakeem Oluseyi to explore the evidence, and why primordial black holes, tiny objects from the Big Bang's earliest moments, may answer it. Going back to Stephen Hawking’s early explanations of the universe, this new idea may be based on principles astrophysics has been using all along.",
        "premiered_on": "2026-06-18",
        "encored_on": "2026-06-18",
        "nola": "",
        "language": "en",
        "updated_at": "2026-06-18T00:22:58.614299Z",
        "links": []
      },
      "links": {
        "self": "https://media.services.pbs.org/api/v1/specials/0779a240-3225-44b4-9597-aee391872999/",
        "assets": "https://media.services.pbs.org/api/v1/specials/0779a240-3225-44b4-9597-aee391872999/assets/",
        "collections": "https://media.services.pbs.org/api/v1/specials/0779a240-3225-44b4-9597-aee391872999/collections/"
      }
    },
    // ... additional specials
  ],
  "meta": {
    "type": "collection",
    "filter": {
      "id": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/specials/?id=",
      "slug": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/specials/?slug=",
      "encored-on-gt":
```

## Get Special

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

Returns a single special by its ID or slug.

### URL Parameters

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

### Example Request

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

### Example Response

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "type": "special",
    "id": "42827a98-bad8-4f8b-94bf-dedbefe31a81",
    "attributes": {
      "title": "Condor Canyon",
      "slug": "condor-canyon-g1vw8d",
      "title_sortable": "Condor Canyon",
      "tms_id": "",
      "description_short": "A California condor survives lead poisoning as her mate raises their chick in her absence.",
      "description_long": "California condors navigate threats like wildfires, lead poisoning, and pesticide DDT. Filmed in Big Sur and Pinnacles National Park, it captures the struggles of Traveler (Red 71), who overcomes lead poisoning while her mate, Shadow (Yellow 9), raises their chick. The film showcases the battle for survival, conservation efforts, and a hopeful future for the condors. Narrated by Catherine Cavadini",
      "premiered_on": "2025-05-28",
      "encored_on": "2025-05-28",
      "nola": "",
      "language": "en",
      "updated_at": "2025-06-02T20:58:53.177165Z",
      "show": {
        "type": "show",
        "id": "14f3747a-2559-4f05-aa59-c8b741cf38ea",
        "attributes": {
          "title": "Detroit PBS Specials",
          "title_sortable": "Detroit PBS Specials",
          "slug": "dptv-specials",
          "display_episode_number": true,
          "updated_at": "2026-06-08T15:24:01.514752Z",
          "featured_preview": null
        },
        "links": {
          "self": "https://media.services.pbs.org/api/v1/shows/14f3747a-2559-4f05-aa59-c8b741cf38ea/"
        }
      },
      "links": [
        {
          "value": "https://www.ventanaws.org/condorcanyon.html",
          "profile": "producer",
          "updated_at": "2025-06-02T20:57:24.802436Z"
        }
      ]
    }
  },
  "meta": {
    "type": "resource"
  },
  "links": {
    "self": "https://media.services.pbs.org/api/v1/specials/42827a98-bad8-4f8b-94bf-dedbefe31a81/",
    "assets": "https://media.services.pbs.org/api/v1/specials/42827a98-bad8-4f8b-94bf-dedbefe31a81/assets/",
    "collections": "https://media.services.pbs.org/api/v1/specials/42827a98-bad8-4f8b-94bf-dedbefe31a81/collections/"
  }
}
```

## Create Special

`POST /shows/{show_id}/specials/`

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

### 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 |  |
| `title` | string | Yes | 120 characters max |
| `slug` | string | Auto-generated or can be assigned on create | Must be unique across all specials. Set on create only. |
| `description_short` | string | Yes | 90 characters max |
| `description_long` | string | Yes | 400 characters max |
| `title_sortable` | string | No |  |
| `premiered_on` | date | No | YYYY-MM-DD format |
| `encored_on` | date | No | YYYY-MM-DD format |
| `nola` | string | No |  |
| `language` | string | No |  |

Fields not supported in create payload: `tms_id`, `links`

### Minimal Payload

```json
{
  "data": {
    "type": "special",
    "attributes": {
      "title": "Special Title",
      "slug": "special-title",
      "description_short": "A brief description of the special",
      "description_long": "A more detailed description of the special content"
    }
  }
}
```

### Full Payload

```json
{
  "data": {
    "type": "special",
    "attributes": {
      "title": "Special Title",
      "slug": "special-title",
      "description_short": "A brief description of the special",
      "description_long": "A more detailed description of the special content",
      "premiered_on": "2024-09-15",
      "encored_on": "2024-09-22",
      "nola": "ABCD1001",
      "language": "en"
    }
  }
}
```

### Response

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

## Update Special

`PATCH /specials/{id}/`

Updates an existing special. 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 special |

### Required Headers

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

### Payload Fields

The `slug` field cannot be updated.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `type` | string | Yes |  |
| `id` | string | Yes |  |
| `title` | string | No | 120 characters max |
| `title_sortable` | string | No |  |
| `description_short` | string | No | 90 characters max |
| `description_long` | string | No | 400 characters max |
| `premiered_on` | date | No | YYYY-MM-DD format |
| `encored_on` | date | No | YYYY-MM-DD format |
| `nola` | string | No |  |
| `language` | string | No |  |
| `metadatabankid` | string | No | Metadata Bank ID. Pass `null` to remove. Internal PBS use only. |

Fields not supported in update payload: `slug`, `tms_id`, `links`

### Example Payload

```json
{
  "data": {
    "type": "special",
    "id": "{special_id}",
    "attributes": {
      "title": "Updated Special Title",
      "description_short": "Updated short description"
    }
  }
}
```

### Moving a Special to a Different Show

To move a special from one show to another, include the target show's ID:

```json
{
  "data": {
    "type": "special",
    "id": "{special_id}",
    "attributes": {
      "show": "{target_show_id}"
    }
  }
}
```

### Converting a Special to an Episode

To convert a special into an episode, include the target season's ID in a `season` attribute:

```json
{
  "data": {
    "type": "special",
    "id": "{special_id}",
    "attributes": {
      "season": "{season_id}"
    }
  }
}
```

> 📝 When converting a special to an episode, the special is removed from the show and becomes an episode under the specified season.

### Response

**204 No Content** on success.

## Delete Special

`DELETE /specials/{id}/`

Permanently deletes the specified special and all associated assets.

### URL Parameters

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

### Required Headers

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

### Response

**204 No Content** on success.

## Search Specials

`GET /specials/search/`

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

### Query Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search term — matches against special 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 (max 50) |
| `page` | integer | No | Page number |

### Example Request

```
GET https://media.services.pbs.org/api/v1/specials/search/?query=dark%20energy
```

## 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: `assets` (all asset types), `collections`, `full_length_asset` (convenience field returning just the full-length asset, or null), and `external_metadata`. Returns the 10 most recent assets by encore date. |
| `encored_on_or_after` | date | Filter specials with `encored_on` on or after this date (YYYY-MM-DD) |
| `encored_on_or_before` | date | Filter specials with `encored_on` on or before this date (YYYY-MM-DD) |
| `id` | string | Filter by one or more special IDs (repeat parameter for multiple) |

### Filtering by Multiple IDs

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

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