Upload Podcast Catalogs

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 items in your podcast library. This catalog metadata is used to train the Alexa service 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 understand that a customer who says, "Alexa, play The John Smith Program" is 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.

Prerequisites

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

  • Access token – Each catalog API request must include an access token retrieved from Login with Amazon. For information on how to acquire this access token, see Get an Access Token for SMAPI.

  • Vendor ID – The vendor ID of your Amazon developer account. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.

  • Skill ID – Every catalog must be associated with a skill. You can find the skill ID for your skill in the Alexa Skills Kit developer console.

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

  1. 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}"
       }
    }
    
  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

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

You can use POST /v0/catalogs/{catalogId}/uploads requests to upload additions or changes to a catalog. 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, you must explicitly specify "deleted": true. For more information, see deleted entities on the catalog reference page.

Podcast catalog type and usage

Use the following values for podcast catalog type and catalog usage.

Items in the catalog Type value Usage value Required
Program series AMAZON.ProgramSeries AlexaMusic.Catalog.ProgramSeries Yes