Upload Catalogs

For the best user experience with your music skill, you should upload your content catalogs to Alexa. The catalogs that you upload contain information about all the items in your entire music library. After you upload your catalogs, they are integrated with the models that are used to train Alexa.

The maximum number of entities in a catalog is 500,000. This limit is cumulative, so if you upload 250,000 entities to your artist catalog one day, then upload an additional 250,000 entities to your artist catalog the next day, you have reached the limit for your artist catalog. If you require support for catalogs with more than 500,000 entities, contact us to request an increase to this limit.

Why upload catalogs?

Alexa uses your catalogs for two primary purposes:

Help Alexa understand voice commands for your content

Your catalogs help train Alexa to recognize voice commands for your music content. For example, if you have a playlist called "Exciting Hockey Songs", uploading a catalog that contains this playlist name helps Alexa understand that a user asking to "play exciting hockey songs on your skill name" is asking for a playlist.

Help Alexa perform more accurate entity resolution

Your catalogs help Alexa with entity resolution, which is the process where Alexa determines which skills can provide the content that users request. For example, if a user says "Alexa, play music by Lady Gaga", Alexa understands that "Lady Gaga" is an artist. During the entity resolution step, Alexa searches the uploaded catalogs to see if "Lady Gaga" is an artist supported by your skill. If a match is found in your catalogs, your skill might be invoked to provide music to the user. If no match is found in your catalogs, your skill is not invoked.

Catalog data is always live

After you publish your music skill, you can continue to work on the development version of your skill. Changes that you make to your development skill don't affect the live, published skill. You must submit your development skill for certification for the changes to be promoted to your live, published skill. For more information about the different skill statuses (Live, In Development, etc.) and how to continue working on a skill after it's published, see publication status and revise and update your skill after publication.

Music catalogs are different, and are always live. The music catalogs that you upload are shared by your development and published skills. When you upload new versions of your catalogs they affect your development skill and your published skill. Because of this, it's important to make sure that the catalogs you upload are correct and will not negatively impact your users. For example, when you upload a new catalog that removes items, these items are no longer available to your development skill and your published skill.

Create and manage your catalogs

You create and manage your catalogs separately from your skill. First you create a catalog, then you associate the catalog with your skill, then you upload the catalog data. You can do all of this with the ASK Command Line Interface (ASK CLI) or with the Alexa Catalog API, which is part of the Skill Management API (SMAPI).

Multiple skills can use the same catalog, but each skill can use only one catalog of each catalog type. That is, a skill can have a maximum of six associated catalogs.

For more information about the format that catalogs should take, see the catalog reference.

Steps to create and manage catalogs

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

  1. To create a catalog with ASK CLI, use the create-catalog command.

    To create a catalog with SMAPI, send a POST /catalogs request.

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

    Create a catalog for each kind of music item that your skill supports. For example, create a catalog for albums (MusicAlbum), songs (MusicRecording), artists (MusicGroup), playlists (MusicPlaylist), and so on.

  2. To associate the catalog with a skill using ASK CLI, use the associate-catalog-with-skill command.

    To associate the catalog with a skill using SMAPI, send a PUT /skills/skill ID/catalogs/catalogId request.

    You can associate a skill with only one catalog of each catalog type.

  3. To upload catalog data with ASK CLI, use the upload-catalog command.

    To upload catalog data with SMAPI, send a POST /catalogs/catalog ID/uploads request.

    Catalogs are JSON documents. For more information about catalog formats, see the catalog reference.

    You can use this same command or API 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.

  4. To check the status of a catalog upload with ASK CLI, use the get-catalog-upload command.

    To check the status of a catalog upload with SMAPI, send a GET /catalogs/catalog ID/uploads/upload ID request.

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

Catalog type and usage

Use the following values for catalog type and catalog usage.

Items in the catalog Type value Usage value
Artists, actors, composers, etc. AMAZON.MusicGroup AlexaMusic.Catalog.MusicGroup
Songs, tracks AMAZON.MusicRecording AlexaMusic.Catalog.MusicRecording
Albums AMAZON.MusicAlbum AlexaMusic.Catalog.MusicAlbum
Playlists (collections of songs) AMAZON.MusicPlaylist AlexaMusic.Catalog.MusicPlaylist
Genres AMAZON.Genre AlexaMusic.Catalog.Genre
Stations, radio AMAZON.BroadcastChannel AlexaMusic.Catalog.BroadcastChannel

Catalog upload status values

The following table explains the values for catalog upload status.

Status Description
UPLOAD The catalog has been uploaded and is ready for additional processing steps.
SCHEMA_VALIDATION The catalog has passed schema validation for the specified catalog type.
ER_INGESTION The catalog was successfully ingested for entity resolution (ER). When the status changes to SUCCEEDED, you can test voice requests for your catalog data with your skill. The ER_INGESTION step typically takes less than 30 minutes to complete.
SLU_MODELING_VALIDATION The catalog has passed initial validation for the Alexa speech and language understanding (SLU) process.
SLU_MODELING The catalog has been ingested and deployed in the Alexa SLU models. You can use your skill before this step completes. This step improves Alexa's accuracy in understanding requests for unique content in your catalog, and can take several weeks to complete.