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 must upload your podcast catalogs separately.

Create and upload your catalog

You upload, monitor, and manage your podcast catalog by using the Catalog Management REST API 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 REST APIs to monitor the catalog upload and ingestion processes and view error logs if there is a catalog upload failure.

For more details 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 Copy Skill ID link for the skill.

Steps to create and upload podcast catalogs

Complete the following steps to create the 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 Create catalog API 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. For more details about the values to use, see Podcast catalog type and usage.

A successful response returns a HTTP 201 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 an Associate catalog API request with the catalog ID that 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 to Amazon S3 and get a pre-signed S3 upload URL, send Create S3 upload URL.

Catalogs are JSON documents. For more details 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 Complete upload.

There is no request body.

A successful response returns a HTTP 202 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 Get upload status v0.

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

There is no request body.

A successful response returns a 200 HTTP 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, send subsequent Create S3 upload URL requests. A typical workflow is to upload the entire catalog initially, and then 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.

Was this page helpful?

Provide feedback

Last updated: Sep 10, 2024