--- title: "Media Manager API" canonical: "https://docs.pbs.org/space/CDA/3047426/Media%20Manager%20API" format: markdown --- ## Overview This guide walks you through your first interactions with the Media Manager API — from authenticating to creating and publishing a video asset. By the end, you'll have a working understanding of the API's core workflow. ## Prerequisites - A Media Manager API key and secret (contact [PBS Digital Support](https://digitalsupport.pbs.org/support/tickets/new) to request access) - A tool for making HTTP requests (e.g., `curl`, Postman, or your language's HTTP client) > ℹ️ **Staging vs. Production:** We recommend testing with the staging environment first. Staging uses a separate API key and does not affect live data. See [Resources](https://docs.pbs.org/space/CDA/3058039/Resources) for endpoint details. ## Authentication The API uses HTTP Basic Authentication. Include your API key and secret with every request: ``` curl -u YOUR_API_KEY:YOUR_API_SECRET \ https://media.services.pbs.org/api/v1/shows/ ``` > ℹ️ If authentication fails, you'll receive a **401 Unauthorized** response. Verify your credentials and ensure you're using the correct key for the environment (production vs. staging). ## Step 1: Retrieve a Show Start by fetching a show to confirm your credentials work and to find the show's ID. ### Request ``` curl -u YOUR_API_KEY:YOUR_API_SECRET \ https://media.services.pbs.org/api/v1/shows/{show_slug}/ ``` ### Response (abbreviated) ``` { "data": { "type": "show", "id": "20c92dfc-8b08-4fcf-856e-71512aa38332", "attributes": { "title": "Antiques Roadshow", "slug": "antiques-roadshow" // ... additional fields } } } ``` > ℹ️ Note the `id` — you'll use it in subsequent steps. ## Step 2: List Seasons for the Show Find the season to which you want to add an episode. ### Request ``` curl -u YOUR_API_KEY:YOUR_API_SECRET \ https://media.services.pbs.org/api/v1/shows/{show_id}/seasons/ ``` ### Response (abbreviated) ``` { "data": [ { "type": "season", "id": "f5c7c4e2-...", "attributes": { "ordinal": 1, "title": "Season 1" } } // ... additional seasons ] } ``` ## Step 3: Create an Episode Create an episode within a season. A successful response returns **204 No Content** with the new episode's URL in the `Location` header. ### Request ``` curl -u YOUR_API_KEY:YOUR_API_SECRET \ -H "Content-Type: application/json" \ -X POST \ -d '{ "data": { "type": "episode", "attributes": { "title": "My First Episode", "description_short": "A brief description", "description_long": "A longer description", "ordinal": 1 } } }' \ https://media.services.pbs.org/api/v1/seasons/{season_id}/episodes/ ``` > ℹ️ `ordinal` is not required; if omitted, the first/next ordinal in the season will be used. ### Response ``` HTTP/1.1 204 No Content Location: https://media.services.pbs.org/api/v1/episodes/{new_episode_id}/ ``` > ℹ️ Save the `Location` URL — you'll need the episode ID to create assets. ## Step 4: Create an Asset Create a video asset (video container) under the episode. Common (but not all) available attributes are included in the example requests below. ### Request – for creating a `full-length` video asset ``` curl -u YOUR_API_KEY:YOUR_API_SECRET \ -H "Content-Type: application/json" \ -X POST \ -d '{ "data": { "type": "asset", "attributes": { "object_type": "full_length", "premiered_on": "2026-01-01", "encored_on": "2026-05-01", "captions_language": [ { "language": "English", "source": "http://caption-file-en.scc" }, { "language": "Spanish", "source": "https://caption-file-es.scc" } ], "video": { "source": "https://video-file.mp4" }, "images": [ { "source": "https://image-file.jpg", "profile": "asset-mezzanine-16x9" } ], "availabilities": { "public": { "start": "2021-08-03T00:30:00Z", "end": "2021-10-11T03:59:59Z", "geo_profile": "495585bd-a963-4245-b602-6ae4f2675c3a" }, "all_members": { "start": "2021-07-18T23:30:00Z", "end": "2022-07-05T03:59:59Z", "geo_profile": "495585bd-a963-4245-b602-6ae4f2675c3a" }, "station_members": { "start": "2018-07-18T23:30:00Z", "end": "2028-07-05T03:59:59Z", "geo_profile": "495585bd-a963-4245-b602-6ae4f2675c3a" } }, "content_rating": "TV-PG", "auto_publish": true } } }' \ https://media.services.pbs.org/api/v1/episodes/{episode_id}/assets/ ``` > ℹ️ The `title`, `description_short`, and `description_long` *are not* included for the `full_length` video asset, since they inherit from the asset’s parent `episode` object. > ℹ️ > ℹ️ `auto_publish` is not required, but a useful time saver. > ℹ️ > ℹ️ `content_rating` may not be required for the show, but strongly recommended. ### Request – for creating a `preview` video asset ``` curl -u YOUR_API_KEY:YOUR_API_SECRET \ -H "Content-Type: application/json" \ -X POST \ -d '{ "data": { "type": "asset", "attributes": { "title": "Episode Preview", "object_type": "preview", "description_short": "short description", "description_long": "long description", "premiered_on": "2026-01-01", "encored_on": "2026-05-01", "captions_language": [ { "language": "English", "source": "http://caption-file-en.scc" }, { "language": "Spanish", "source": "https://caption-file-es.scc" } ], "video": { "source": "https://video-file.mp4" }, "images": [ { "source": "https://image-file.jpg", "profile": "asset-mezzanine-16x9" } ], "availabilities": { "public": { "start": "2021-08-03T00:30:00Z", "end": "2021-10-11T03:59:59Z", "geo_profile": "495585bd-a963-4245-b602-6ae4f2675c3a" }, "all_members": { "start": "2021-07-18T23:30:00Z", "end": "2022-07-05T03:59:59Z", "geo_profile": "495585bd-a963-4245-b602-6ae4f2675c3a" }, "station_members": { "start": "2018-07-18T23:30:00Z", "end": "2028-07-05T03:59:59Z", "geo_profile": "495585bd-a963-4245-b602-6ae4f2675c3a" } }, "content_rating": "TV-PG", "auto_publish": true } } }' \ https://media.services.pbs.org/api/v1/episodes/{episode_id}/assets/ ``` > ℹ️ The `title`, `description_short`, and `description_long` *are* included for the `preview` (or `clip`) video asset, since they *do not* inherit from the asset’s parent `episode` object. > ℹ️ > ℹ️ `auto_publish` is not required, but a useful time saver. > ℹ️ > ℹ️ `content_rating` may not be required for the show, but strongly recommended. ### Response ``` HTTP/1.1 204 No Content Location: https://media.services.pbs.org/api/v1/assets/{new_asset_id}/edit/ ``` ### Check Ingestion Status Video and caption ingestion happens asynchronously. Check progress with a GET request: ``` curl -u YOUR_API_KEY:YOUR_API_SECRET \ https://media.services.pbs.org/api/v1/assets/{asset_id}/edit/ ``` Look for `ingest_status` in the video and caption objects of the response. **Done!** Your asset is now published and will be available on platforms according to the show's audience and availability rules. ## Next Steps - **[Resources](https://docs.pbs.org/space/CDA/3058039/Resources)** — Full reference for all resource types, endpoints, and query parameters - **[HTTP Response Status Codes](https://docs.pbs.org/space/CDA/3053894/HTTP+Response+Status+Codes)** — Error handling and response format reference - **[Audience and Availability Rules](https://docs.pbs.org/space/CDA/3057298/Audience+and+Availability+Rules)** — How content visibility works across platforms and membership levels