Upload Podcast Catalogs

Note: Sign in to the developer console to build or publish your skill.

Important: Anyone can build a music skill for public distribution in the United States. However, radio and podcast skills are currently in developer preview. To register your radio or podcast skill for the preview, contact your Alexa Music, Radio, or Podcast representative.

To provide the best user experience for your podcast skill, you should upload your podcast catalogs to Alexa. The catalogs that you upload contain information about all the programs in your podcast library. The Alexa service uses the catalog metadata to recognize voice commands for your streaming content.

For example, if you have a podcast named "The John Smith Podcast," uploading a podcast catalog containing this program name helps Alexa learn that when a customer says, "Alexa, play The John Smith Program" they're asking for a podcast.

If you've already uploaded catalogs for an existing music skill, you'll need to upload your podcast catalogs separately.

Create and upload your catalog

You upload, monitor, and manage your podcast catalog by using the Alexa Skill Management API (SMAPI) as follows. First you create a new catalog, associate it with a skill, and upload it. After you upload your catalog, Alexa validates the file for compliance with the podcast catalog schema specifications. Finally, Alexa ingests the catalog into the voice models that help Alexa understand voice commands for your content. You can call Alexa SMAPI APIs to monitor the catalog upload and ingestion processes and view error logs if there is a catalog upload failure.

For more information about the format that your podcast catalogs should use, see the Podcast Catalog Reference.

Note: You can only upload a single podcast catalog in each catalog upload. Multi-part catalog upload isn't supported. The catalog file size must be less than 5 GB. Each API invocation should be less than 3 TPS.

Podcast catalog type and usage

Use the following values for podcast catalog type and usage:

Items in the catalog	`type` value	`usage` value	Required
Program series	`AMAZON.ProgramSeries`	`AlexaMusic.Catalog.ProgramSeries`	Yes

Catalog naming conventions

Podcast catalog names must start with the prefix podcast_. A catalog name can be up to 80 characters long. It can only contain alphanumeric characters (uppercase, lowercase and numbers), hyphens, and underscores. Amazon recommends that you use the following naming convention when uploading catalogs:

podcast_YYYYMMDD_N.json

YYYYMMDD is the podcast catalog upload date. N is the catalog version number.

Prerequisites

Before you create and upload your catalog, make sure you have the following information:

Access token – Each catalog API request must include an access token retrieved from Login with Amazon. For details, see Get an Access Token for SMAPI.
Vendor ID – The vendor ID of your Amazon developer account. For details, see Locate your vendor ID in the Alexa Skills Kit developer console.
Skill ID – The skill ID of the your podcast skill. To find it, navigate to the list of skills in the developer console and click the View Skill ID link for the skill.

Steps to create and upload podcast catalogs

Use the following steps to create a podcast catalog, associate it with a skill, and then upload content to the catalog.

To create and upload a catalog

To create a catalog to host your upload records, send a POST /v0/catalogs request.

The request body must be in the following format:

{
   "title": "string",
   "type": "AMAZON.ProgramSeries",
   "usage": "AlexaMusic.Catalog.ProgramSeries",
   "vendorId": "{vendorId}"
}

In addition to the catalog title, you must provide a catalog type and a catalog usage. See Podcast catalog type and usage for the values to use.

A successful response returns a 201 HHTP status and the catalog ID, as shown in the following example:

{
   catalog: { 
      "associatedSkills": [],
      "catalogScope": "AlexaMusic.Catalog.ProgramSeries",
      "catalogType":"AMAZON.ProgramSeries",
      "createdDateTime": 1594234199.394,
      "id": "{catalogId}",
      "lastUpdatedDateTime": 1594234199.394,
      "title": "{catalogTitle}",
      "vendorId": "{vendorId}"
   }
}

To associate the catalog with your podcast skill, send a PUT /v0/skills/{skillId}/catalogs/{catalogId} request.

Replace {catalogId} with the catalog ID you received in the response to the previous step.

There is no request body.

You can associate a skill with only one catalog.
Contact your Alexa Podcast representative to provide them with the catalog ID for your podcast catalog, so that they can create monitors for your catalog ingestion processes.

To create a content upload and get a pre-signed S3 upload URL, send a POST /v0/catalogs/{catalogId}/uploads request.

Catalogs are JSON documents. For more information about catalog formats, see the Podcast Catalog Reference.

A successful response returns the pre-signed upload URL, as shown in the following example:

{
    "id": "{catalogUploadId}",
    "catalogId": "{catalogId}",
    "status": "PENDING",
    "locales": [],
    "createdDate": "2019-04-06T23:52:20.528Z",
    "lastUpdatedDate": "2019-04-06T23:52:20.528Z",
    "ingestionSteps": [
        {
            "errors": [],
            "logUrl": "",
            "name": "ER_INGESTION",
            "status": "PENDING"
        },
        {
            "errors": [],
            "logUrl": "",
            "name": "UPLOAD",
            "status": "PENDING"
        },
        {
            "errors": [],
            "logUrl": "",
            "name": "SCHEMA_VALIDATION",
            "status": "PENDING"
        },
        {
            "errors": [],
            "logUrl": "",
            "name": "SLU_MODELING",
            "status": "PENDING"
        },
        {
            "errors": [],
            "logUrl": "",
            "name": "SLU_MODELING_VALIDATION",
            "status": "PENDING"
        }
    ],
    "presignedUploadParts": [
        {
            "url": "{presignedUploadUrl}",
            "partNumber": 1
        }
    ]
}

Save the {catalogUploadId} and {presignedUploadUrl} values.

Important: The pre-signed URL ({presignedUploadUrl}) expires after one hour.

To upload your catalog data, send a PUT {presignedUploadUrl} request to the pre-signed upload URL you received in the previous step:

Include your catalog file in the request body. You can only upload one catalog file at a time.
To complete the catalog upload and start the catalog ingestion workflow, send a POST /v0/catalogs/{catalogId}/uploads/{uploadId} request.

There is no request body.

A successful response returns a 202 HHTP status to indicate that the upload was accepted.
To upload additional catalog files, repeat steps 4 through 6.

To check the status of a catalog upload

To check the status of a catalog upload, send a GET /v0/catalogs/{catalogId}/uploads/{uploadId} request.

The response includes the processing status of the catalog. For information about the status values, see catalog upload status values.

There is no request body.

A successful response returns a 200 HHTP status and an upload object with status information, as shown in the following example:

 {
     "id": "{catalogUploadId}",
     "catalogId": "{catalogId}",
     "locales": [],
     "createdDate": "2019-04-06T23:52:20.528Z",
     "file": {
         "presignedDownloadUrl": "{presignedUploadUrl}",
         "status": "AVAILABLE"
     },
     "ingestionSteps": [
         {
             "errors": [
                   
             ],
             "logUrl": "",
             "name": "ER_INGESTION",
             "status": "SUCCEEDED"
         },
         {
             "errors": [
                   
             ],
             "logUrl": "",
             "name": "UPLOAD",
             "status": "SUCCEEDED"
         },
         {
             "errors": [
                   
             ],
             "logUrl": "",
             "name": "SCHEMA_VALIDATION",
             "status": "SUCCEEDED"
         },
         {
             "errors": [
                   
             ],
             "logUrl": "",
             "name": "SLU_MODELING",
             "status": "PENDING"
         },
         {
             "errors": [
                   
             ],
             "logUrl": "",
             "name": "SLU_MODELING_VALIDATION",
             "status": "PENDING"
         }
     ],
     "status": "IN_PROGRESS",
     "lastUpdatedDate": "2019-04-06T23:52:20.528Z"
 }

Manage your catalog

To upload additions or changes to an existing catalog, make a POST /v0/catalogs/{catalogId}/uploads request. A typical workflow is to upload the entire catalog initially, and then subsequently upload only the additions or changes.

To delete entries from a catalog, see How to mark a program series as deleted.

Important: When you upload a catalog with new, updated, or removed entries, make sure to update the corresponding lastUpdatedTime field. The Alexa service uses this field to help determine what's changed. If you upload a catalog with changed entries but an unchanged lastUpdatedTime field, the changes might be ignored.

Last updated: Sep 20, 2021