Catalog Management REST API Reference

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

Use the Catalog Management REST API to upload your catalog content so that Alexa can resolve customer utterances dynamically. Alexa references the catalog data to recognize voice commands for your skill. For more details about catalog content, see Catalog Reference for Music, Radio, and Podcast Skills.

Catalog uploads

For catalogs that are less than 5 GB, you can upload the entire catalog in one request. For larger sizes, use multi-part upload to load the catalog in parts. You can also use multi-part upload for catalogs that are 5 MB or more.

To use multi-part upload, split your catalog content file into parts. Each part must be at least 5 MB but no more than 5 GB. The last part can be less than 5 MB. For each part, send an upload request to the presigned URL or URLs that you receive when you created the upload. You can send these upload requests independently, in any order, and in parallel.

Important: The total catalog size must be less than 5 TB. If the catalog is more than 5 GB, you must use multi-part upload. You can split your content into 1–1000 parts.

Steps to upload a catalog

You can host your catalog content on Amazon S3, an Alexa-hosted site, or a self-hosted site. Complete the following steps to create the catalog and upload the contents for your hosting option.

Create catalog and upload content to Amazon S3

Complete the following steps to create a catalog and upload content to an Amazon S3 bucket. These steps use interface version v0 APIs.

To create a catalog and upload content to Amazon S3

To create a new catalog and receive a catalogId, use Create catalog.
If you already created a catalog, you can skip this step.
Before you upload to the catalog, use Associate catalog to associate the catalog with one or more skills. You must associate a skill to a catalog before you can upload content.
To create a presigned URL to upload content to an S3 bucket, use Create S3 upload URL. If you split your catalog into multiple parts, the response contains one URL for each part.
You can reuse this API to get new URLs to upload additions or changes to your catalog.
To upload the catalog, send an HTTP PUT request to each presigned URL with the catalog or catalog part in the body of the request. Typically, you create a catalog and upload the entire contents in one or multiple parts. Then, you upload additions or changes to your catalog content. When you upload a catalog with new, updated, or deleted entries, make sure to update the lastUpdatedTime value.
The response header contains an ETag value. Save the ETag values from each response to complete the upload in the next step.
For more details about how to upload content to Amazon S3, see Uploading objects with presigned URLs.
To complete the upload, send the ETag values and part numbers with the Complete the upload API.
After you complete the upload, the parts are assembled back into a single catalog.
(Optional) To get the status of an upload, see Get upload status v0.
(Optional) To get the details of a catalog, use Get catalog.
(Optional) To get the list of catalogs, use List catalogs v0.

Create catalog and upload content to an Alexa-hosted site

Complete the following steps to create a catalog in an Alexa-hosted site and upload catalog content. These steps use interface version v0 and v1 APIs. For more details about Alexa-hosted resources, see About Alexa-hosted Skills.

To create a catalog and upload content to an Alexa-hosted site

To create the catalog and receive a catalogId, use Create catalog.
Before you upload to the catalog, use Associate catalog to associate the catalog with one or more skills. You must associate a skill to a catalog before you can upload content.
To create a presigned URL to upload the catalog to an Alexa-hosted site, use Create Alexa-hosted upload URL v1.
To upload the entire catalog to an Alexa-hosted URL, send a PUT request to the presigned URL with the catalog in the body of the request.
To upload the catalog in multiple parts, send a PUT request to the presigned URLs with the catalog part in the body of the request.
The response to each PUT request contains an ETag value in the ETag header. You need this ETag value to complete the upload in the following step.
To complete the upload, send the ETag values and part numbers with the Complete the upload API.
(Optional) To get the status of an upload, see Get upload status v1.
(Optional) To get the details of a catalog, use Get catalog.
(Optional) To get the list of catalogs, use List catalogs v0.

Create catalog and upload content to self-hosted site

Complete the following steps to create a catalog on a self-hosted site and upload catalog content. These steps use interface version v0 and v1 APIs.

To create a catalog and upload content to a self-hosted site

To create the catalog and receive a catalogId, use Create catalog.
Before you upload to the catalog, use Associate catalog to associate the catalog with one or more skills. You must associate a skill to a catalog before you can upload content.
To create a URL to upload the catalog, use Create self-hosted upload URL v1.
Upload the catalog to the self-hosted URL from the previous step.
(Optional) To get the status of an upload, see Get upload status v1.
(Optional) To get the details of a catalog, use Get catalog.
(Optional) To get the list of catalogs, use List catalogs v0.

API endpoint

The endpoint of the Catalog Management API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.

Operations

The Catalog Management API includes the following operations.

Operation	HTTP method and URI
Associate catalog	`PUT /v0/skills/{skillId}/catalogs/{catalogId}`
Complete upload	`POST /v0/catalogs/{catalogId}/uploads/{uploadId}`
Create catalog	`POST /v0/catalogs`
Create S3 upload URL	`POST /v0/catalogs/{catalogId}/uploads`
Create Alexa-hosted upload URL v1	`POST /v1/catalogs/{catalogId}/urls`
Create self-hosted upload URL v1	`POST /v1/catalogs/{catalogId}/uploads`
Get catalog	`GET /v0/catalogs/{catalogId}`
Get upload status v0	`GET /v0/catalogs/{catalogId}/uploads/{uploadId}`
Get upload status v1	`GET /v1/catalogs/{catalogId}/uploads/{uploadId}`
List catalogs	`GET /v0/catalogs?vendorId={vendorId}&maxResults={num}&nextToken={token}`
List uploads	`GET /v0/catalogs/{catalogId}/uploads?maxResults={maxResults}&nextToken={nextToken}`

Associate catalog

Associate the specified skill to the specified catalog. You must associate a skill to a catalog before you can upload content.

Request

To associate a skill with a catalog, you make a PUT request to the /v0/skills/{skillId}/catalogs resource.

Request path and header example

Copied to clipboard.

PUT /v0/skills/{skillId}/catalogs/{catalogId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`skillId`	Path	Identifies the skill to associate with the catalog. Valid values: 1 – 255 characters.	String	Yes
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 201 Created. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`HTTP 201 Created`	Skill associated with the specified catalog successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Complete upload

Complete an upload to Amazon S3 using presigned URLs. Call this API after you upload all parts of the catalog content to S3. For more details about how to create a catalog in S3, see Create catalog and upload content to Amazon S3.

Request

To complete an S3 upload, you make a POST request to the /v0/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v0/catalogs/{catalogId}/uploads/{uploadId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`uploadId`	Path	Unique identifier of the upload.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "partETags": [{
            "eTag": "etag.1",
            "partNumber": 1
        },
        {
            "eTag": "etag.2",
            "partNumber": 2
        }
    ]
}

Request body properties

Property	Description	Type	Required
`partETags`	List of `eTag` and part number pairs for each part of the catalog content file uploaded.	Array of objects	Yes
`partETags[].eTag`	Opaque identifier for last successful upload of this part.	String	Yes
`partETags[].partNumber`	Part number of the upload. For more details about multi-part uploads, see Catalog uploads. Valid values: 1–1000.	Integer	Yes

Response

A successful response returns HTTP 202 Accepted. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
` 202 Accepted`	Successfully completed the upload.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create catalog

Create a new catalog with no records. You upload the records in a separate operation. The API associates the catalog with the vendorId of your developer account.

Request

To create a catalog, you make a POST request to the /v0/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v0/catalogs
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "title": "My.Music.Catalog",
  "type": "AMAZON.MusicGroup",
  "usage": "AlexaMusic.Catalog.MusicGroup",
  "vendorId": "your.vendor.id.1"
}

Request body properties

Property	Description	Type	Required
`title`	Title of the catalog.	String	Yes
`type`	Type of catalog. The `type` value must match the `usage` value. For example, if you specify `AMAZON.MusicAlbum` as the `type`, you must specify `AlexaMusic.Catalog.MusicAlbum` as the `usage`. Valid values: `AMAZON.AudioRecording`, `AMAZON.BroadcastChannel`, `AMAZON.Genre`, `AMAZON.MusicAlbum`, `AMAZON.MusicGroup`, `AMAZON.MusicPlaylist`, `AMAZON.MusicRecording`, `AMAZON.ProgramSeries`, or `AMAZON.TerrestrialRadioChannel`.	String	Yes
`usage`	How you expect the catalog to be used. The `usage` value must correspond to the `type` value. Valid values: `AlexaTest.Catalog.AudioRecording`, `AlexaMusic.Catalog.BroadcastChannel`, `AlexaMusic.Catalog.Genre`, `AlexaMusic.Catalog.MusicAlbum`, `AlexaMusic.Catalog.MusicGroup`, `AlexaMusic.Catalog.MusicPlaylist`, `AlexaMusic.Catalog.MusicRecording`, `AlexaMusic.Catalog.ProgramSeries`, or `AlexaMusic.Catalog.TerrestrialRadioChannel`.	String	Yes
`vendorId`	Identifies the vendor that creates the catalog. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	Yes

Response

A successful response returns HTTP 201 Created, along with the catalog details. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "catalog": {
        "id": "catalog.id.1",
        "title": "My.Music.Catalog",
        "type": "AMAZON.MusicGroup",
        "usage": "AlexaMusic.Catalog.MusicGroup",
        "createdDate": "2019-04-06T23:52:20.528Z",
        "lastUpdatedDate": "2019-04-06T23:52:20.528Z",
        "associatedSkills": []
    }
}

Response body properties

Property	Description	Type
`catalogId`	Unique identifier of the new catalog.	String
`title`	Title of the catalog.	String
`type`	Type of catalog. The `type` value must match the `usage` value. For example, if you specify `AMAZON.MusicAlbum` as the `type`, you must specify `AlexaMusic.Catalog.MusicAlbum` as the `usage`. Valid values: `AMAZON.AudioRecording`, `AMAZON.BroadcastChannel`, `AMAZON.Genre`, `AMAZON.MusicAlbum`, `AMAZON.MusicGroup`, `AMAZON.MusicPlaylist`, `AMAZON.MusicRecording`, `AMAZON.ProgramSeries`, or `AMAZON.TerrestrialRadioChannel`.	String
`usage`	How you expect the catalog to be used. The `usage` value must correspond to the `type` value. Valid values: `AlexaTest.Catalog.AudioRecording`, `AlexaMusic.Catalog.BroadcastChannel`, `AlexaMusic.Catalog.Genre`, `AlexaMusic.Catalog.MusicAlbum`, `AlexaMusic.Catalog.MusicGroup`, `AlexaMusic.Catalog.MusicPlaylist`, `AlexaMusic.Catalog.MusicRecording`, `AlexaMusic.Catalog.ProgramSeries`, or `AlexaMusic.Catalog.TerrestrialRadioChannel`.	String
`createdDateTime`	Date and time when the catalog was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`lastUpdatedDateTime`	Date and time when the catalog was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`associatedSkills`	List of skills associated with the catalog.	Array of strings

HTTP status codes

Status	Description
`201 Created`	Catalog created successfully. Response body contains the catalog details.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create S3 upload URL

Create one or more presigned URLs to upload content to an Amazon S3 bucket. If you break up your catalog content into multiple parts, you indicate the number of parts in the request. The response contains one URL for each part.

You can use this API to get URLs to upload the initial catalog contents, and later to upload additions or changes to your catalog content.

Request

To create a presigned URL, you make a POST request to the /v0/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v0/catalogs/{catalogId}/uploads
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "numberOfUploadParts": 3
}

Request body properties

Property	Description	Type	Required
`numberOfUploadParts`	For multi-part uploads, specify the number of parts the content is split into. For more details about multi-part uploads, see Catalog uploads. Default = 1.	Integer	No

Response

A successful response returns HTTP 201 Created, along with upload ID and one or more presigned URLs. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "id": "upload.id.1",
    "catalogId": "catalog.id.1",
    "createdDate": "2019-04-06T23:52:20.528Z",
    "lastUpdatedDate": "2019-04-06T23:52:20.528Z",
    "status": "PENDING",
    "ingestionSteps": [{
        "name": "UPLOAD",
        "status": "PENDING",
        "logUrl": "https://example.com/log.URL",
        "errors": []
    }],
    "presignedUploadParts": [{
        "url": "https://example.com/upload.url.1",
        "partNumber": 1
    }]
}

Response body properties

Property	Description	Type
`id`	Unique identifier of the upload.	String
`catalogId`	Unique identifier of the new catalog.	String
`createdDateTime`	Date and time when the catalog was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`lastUpdatedDateTime`	Date and time when the catalog was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`status`	Status of the upload. Valid values: `PENDING`, `PROCESSING`, `FAILED`, `SUCCEEDED`.	String
`ingestionSteps`	List of ingestion steps.	Array of objects
`ingestionSteps.name`	Name of the ingestion step. Valid values: `UPLOAD`, `SCHEMA_VALIDATION`.	String
`ingestionSteps.status`	Status of the ingestion step. Valid values: `PENDING`, `IN_PROGRESS`, `FAILED`, `SUCCEEDED`, `CANCELLED`.	String
`ingestionSteps.logUrl`	(Optional) URL to the log file containing information about the ingestion step.	String
`ingestionSteps.errors`	List of errors that occurred during this ingestion step.	Array of objects
`ingestionSteps.errors[]`	Indicates errors that occurred executing the upload. If the upload succeeded, an empty array is included.	Object
`ingestionSteps.errors[].code`	HTTP status code that reflects the error.	String
`ingestionSteps.errors[].message`	Human readable error message.	String
`presignedUploadParts`	Ordered list of presigned URLs to perform a multi-part upload. The array contains the same number of URLs as parts specified in the request. For more details about multi-part uploads, see Catalog uploads.	Array of objects
`presignedUploadParts[].url`	URL to use to upload the part specified by `partNumber`.	String
`presignedUploadParts[].partNumber`	Part number to upload at the presigned URL. Valid values: 1–1000.	Integer

HTTP status codes

Status	Description
`201 Created`	Response body contains the upload ID and one or more presigned URLs.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create Alexa-hosted upload URL v1

Create one or more presigned URLs to upload content to an Alexa-hosted site. If you break up your catalog content into multiple parts, you indicate the number of parts in the request. The response contains one URL for each part.

You can use this API to get URLs to upload the initial catalog contents, and later to upload additions or changes to your catalog content.

Request

To create a presigned URL, you make a POST request to the /v1/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v1/catalogs/{catalogId}/urls
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "numberOfUploadParts": 3
}

Request body properties

Property	Description	Type	Required
`numberOfUploadParts`	For multi-part uploads, specify the number of parts the content is split into. For more details about multi-part uploads, see Catalog uploads. Default = 1.	Integer	No

Response

Response body example

{
    "urlId": "upload.id.1",
    "presignedUploadParts": [{
        "url": "https://example.com/upload.url.1",
        "partNumber": 1,
        "expiresAt": "2019-04-06T23:52:20.528Z"
    }]
}

Response body properties

Property	Description	Type
`urlId`	Unique identifier of the upload.	String
`presignedUploadParts`	Ordered list of presigned URLs to perform a multi-part upload. The array contains the same number of URLs as parts specified in the request. For more details about multi-part uploads, see Catalog uploads.	Array of objects
`presignedUploadParts[].url`	URL to use to upload the part specified by `partNumber`.	String
`presignedUploadParts[].partNumber`	Part number to upload at the presigned URL. Valid values: 1–1000.	Integer
`presignedUploadParts[].expiresAt`	Date and time when the URL expires. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String

HTTP status codes

Status	Description
`201 Created`	Response body contains the upload ID and one or more presigned URLs.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create self-hosted upload URL v1

Create one or more presigned URLs to upload content to a self-hosted.

You can use this API to get URLs to upload the initial catalog contents, and later to upload additions or changes to your catalog content.

Request

To create a URL, you make a POST request to the /v1/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v1/catalogs/{catalogId}/uploads
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The following example shows a request to create an upload URL for a self-hosted site.

Copied to clipboard.

{
  "location": "https://example.com/upload.url"
}

The following example shows a request to create an URLs for a multi-part upload.

Copied to clipboard.

{
  "preSignedUrl": {
    "urlId": "https://www.example.com",
    "partETags": [
      {
        "eTag": "string",
        "partNumber": 1
      },
      {
        "eTag": "string",
        "partNumber": 2
      }
    ]
  }
}

Request body properties

Property	Description	Type	Required
`location`	Unique URL for the upload. Either `location` or `preSignedUrl` is required.	Integer	No
`preSignedUrl`	Information for a multi-part upload. Either `location` or `preSignedUrl` is required.	Object	No
`preSignedUrl.urlId`	Unique URL for the upload.	String	Yes
`preSignedUrl.partETags`	List of `eTag` and part number pairs for each part of the catalog content file uploaded.	Array of objects	Yes
`preSignedUrl.partETags[].eTag`	Opaque identifier for last successful upload of this part.	String	Yes
`preSignedUrl.partETags[].partNumber`	Part number of the upload. For more details about multi-part uploads, see Catalog uploads. Valid values: 1–1000.	Integer	Yes

Response

A successful response returns HTTP 202 Accepted. The Location header contains a relative URL to track the upload. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`202 Accepted`	Upload created successfully. The `Location` header contains a relative URL to track the upload.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get catalog

Get the details about a specified catalog.

Request

To get a catalog, you make a GET request to the /v0/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v0/catalogs/{catalogId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the details about the requested catalog. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "catalog": {
        "id": "catalog.id.1",
        "title": "My.Music.Catalog",
        "type": "AMAZON.MusicGroup",
        "usage": "AlexaMusic.Catalog.MusicGroup",
        "createdDate": "2019-04-06T23:52:20.528Z",
        "lastUpdatedDate": "2019-04-06T23:52:20.528Z",
        "associatedSkills": []
    }
}

Response body properties

Property	Description	Type
`catalogId`	Unique identifier of the new catalog.	String
`title`	Title of the catalog.	String
`type`	Type of catalog. The `type` value must match the `usage` value. For example, if you specify `AMAZON.MusicAlbum` as the `type`, you must specify `AlexaMusic.Catalog.MusicAlbum` as the `usage`. Valid values: `AMAZON.AudioRecording`, `AMAZON.BroadcastChannel`, `AMAZON.Genre`, `AMAZON.MusicAlbum`, `AMAZON.MusicGroup`, `AMAZON.MusicPlaylist`, `AMAZON.MusicRecording`, `AMAZON.ProgramSeries`, or `AMAZON.TerrestrialRadioChannel`.	String
`usage`	How you expect the catalog to be used. The `usage` value must correspond to the `type` value. Valid values: `AlexaTest.Catalog.AudioRecording`, `AlexaMusic.Catalog.BroadcastChannel`, `AlexaMusic.Catalog.Genre`, `AlexaMusic.Catalog.MusicAlbum`, `AlexaMusic.Catalog.MusicGroup`, `AlexaMusic.Catalog.MusicPlaylist`, `AlexaMusic.Catalog.MusicRecording`, `AlexaMusic.Catalog.ProgramSeries`, or `AlexaMusic.Catalog.TerrestrialRadioChannel`.	String
`createdDateTime`	Date and time when the catalog was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`lastUpdatedDateTime`	Date and time when the catalog was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`associatedSkills`	List of skills associated with the catalog.	Array of strings

HTTP status codes

Status	Description
`200 OK`	Response body contains details about the requested catalog.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get upload status v0

Get the upload status for the specified catalog and upload IDs. An upload is a file that contributes content to a catalog. If you uploaded your catalog content to an Amazon S3 bucket, use version 0; otherwise use Get upload status v1.

Request

To get the upload status, you make a GET request to the /v0/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v0/catalogs/{catalogId}/uploads/{uploadId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`uploadId`	Path	Unique identifier of the upload.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the upload status. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "id": "upload.id.1",
    "catalogId": "catalog.id.1",
    "createdDate": "2019-04-06T23:52:20.528Z",
    "lastUpdatedDate": "2019-04-07T23:52:20.528Z",
    "status": "SUCCEEDED",
    "ingestionSteps": [{
        "name": "UPLOAD",
        "status": "SUCCEEDED",
        "logUrl": "https://example.com/log.URL",
        "errors": []
    }],
    "file": {
        "presignedDownloadUrl": "https://example.com/download.url.1",
        "status": "AVAILABLE"
    }
}

Response body properties

Property	Description	Type
`id`	Unique identifier of the upload.	String
`catalogId`	Unique identifier of the catalog.	String
`createdDateTime`	Date and time when the catalog was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`lastUpdatedDateTime`	Date and time when the catalog was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`status`	Status of the upload. Valid values: `PENDING`, `PROCESSING`, `FAILED`, `SUCCEEDED`.	String
`ingestionSteps`	List of ingestion steps.	Array of objects
`ingestionSteps.name`	Name of the ingestion step. Valid values: `UPLOAD`, `SCHEMA_VALIDATION`.	String
`ingestionSteps.status`	Status of the ingestion step. Valid values: `PENDING`, `IN_PROGRESS`, `FAILED`, `SUCCEEDED`, `CANCELLED`.	String
`ingestionSteps.logUrl`	(Optional) URL to the log file containing information about the ingestion step.	String
`ingestionSteps.errors`	List of errors that occurred during this ingestion step.	Array of objects
`ingestionSteps.errors[]`	Indicates errors that occurred executing the upload. If the upload succeeded, an empty array is included.	Object
`ingestionSteps.errors[].code`	HTTP status code that reflects the error.	String
`ingestionSteps.errors[].message`	Human readable error message.	String
`file`	Status of the content upload specified by the `uploadId`.	Object
`file.presignedDownloadUrl`	If the file is available for download, use the presigned download URL to download the uploaded catalog content.	String
`file.FileUploadStatus`	Status of the catalog upload. `AVAILABLE` indicates that you can download the content. Valid values: `PENDING`, `AVAILABLE`, `PURGED`, `UNAVAILABLE`.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the status of the specified upload.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get upload status v1

Get the upload status for the specified catalog and upload ID. An upload is a file that contributes content to a catalog. Use version 1 to get the status of an upload to Amazon S3, Alexa-hosted, or self-hosted sites.

Request

To get the upload status, you make a GET request to the /v1/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v1/catalogs/{catalogId}/uploads/{uploadId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`uploadId`	Path	Unique identifier of the upload.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

Response body example

{
    "id": "upload.id.1",
    "catalogId": "catalog.id.1",
    "createdDate": "2019-04-06T23:52:20.528Z",
    "lastUpdatedDate": "2019-04-07T23:52:20.528Z",
    "status": "SUCCEEDED",
    "ingestionSteps": [{
        "name": "UPLOAD",
        "status": "SUCCEEDED",
        "logUrl": "https://example.com/log.URL",
        "violations": []
    }],
    "file": {
        "presignedDownloadUrl": "https://example.com/download.url.1",
        "expiresAt": "2019-04-08T23:52:20.528Z",
        "status": "AVAILABLE"
    }
}

Response body properties

Property	Description	Type
`id`	Unique identifier of the upload.	String
`catalogId`	Unique identifier of the catalog.	String
`createdDateTime`	Date and time when the catalog was created, if known. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`lastUpdatedDateTime`	Date and time when the catalog was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`status`	Status of the upload. Valid values: `PENDING`, `IN_PROGRESS`, `FAILED`, `SUCCEEDED`.	String
`ingestionSteps`	List of ingestion steps.	Array of objects
`ingestionSteps.name`	Name of the ingestion step. Valid values: `UPLOAD`, `SCHEMA_VALIDATION`.	String
`ingestionSteps.status`	Status of the ingestion step. Valid values: `PENDING`, `IN_PROGRESS`, `FAILED`, `SUCCEEDED`, `CANCELLED`.	String
`ingestionSteps.logUrl`	(Optional) URL to the log file containing information about the ingestion step.	String
`ingestionSteps.violations`	List of errors that occurred during this ingestion step.	Array of objects
`ingestionSteps.violations[]`	Indicates errors that occurred executing the upload. If the upload succeeded, an empty array is included.	Object
`ingestionSteps.violations[].code`	HTTP status code that reflects the error.	String
`ingestionSteps.errors[].message`	Human readable error message.	String
`file`	Status of the content upload specified by the `uploadId`.	Object
`file.downloadUrl`	If the file is available for download, use the presigned download URL to download the uploaded catalog content.	String
`file.status`	Status of the catalog upload. `AVAILABLE` indicates that you can download the content. Valid values: `PENDING`, `AVAILABLE`, `PURGED`, `UNAVAILABLE`.	String
`file.expiresAt`	Date and time when the URL expires. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the status of the specified upload.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List catalogs

List the catalogs associated with a vendor.

Request

To list a list of catalogs, you make a GET request to the /v0/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v0/catalogs?vendorId={vendorId}&maxResults={num}&nextToken={token}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`vendorId`	Query	Identifies the vendor that creates the catalog. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–50. Default: 50.	Number	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response.	String	No
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of catalogs owned by the vendor. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "_links": {
        "self": {
            "href": "Link to first catalog"
        },
        "next": {
            "href": "Link to next catalog, if any"
        }
    },
    "catalogs": [{
            "id": "catalog.id.1",
            "title": "My.Music.Catalog",
            "type": "AMAZON.MusicGroup",
            "usage": "AlexaMusic.Catalog.MusicGroup",
            "createdDate": "2019-04-06T23:52:20.528Z",
            "lastUpdatedDate": "2019-04-06T23:52:20.528Z",
            "associatedSkills": ["amzn1.ask.skill.1"]
        },
        {
            "id": "catalog.id.1",
            "title": "My.Music.Catalog",
            "type": "AMAZON.MusicPlaylist",
            "usage": "AlexaMusic.Catalog.MusicPlaylist",
            "createdDate": "2019-04-10T14:52:20.528Z",
            "lastUpdatedDate": "2019-04-10T15:12:20.528Z",
            "associatedSkills": ["amzn1.ask.skill.1"]
        }
    ],
    "isTruncated": true,
    "nextToken": "someToken1"
}

Response body properties

Property	Description	Type
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object
`catalogs`	List of catalogs owned by the specified vendor ID.	Array of objects
`catalogs[].catalogId`	Unique identifier of the catalog.	String
`catalogs[].title`	Title of the catalog.	String
`catalogs[].type`	Type of catalog. The `type` value must match the `usage` value. For example, if you specify `AMAZON.MusicAlbum` as the `type`, you must specify `AlexaMusic.Catalog.MusicAlbum` as the `usage`. Valid values: `AMAZON.AudioRecording`, `AMAZON.BroadcastChannel`, `AMAZON.Genre`, `AMAZON.MusicAlbum`, `AMAZON.MusicGroup`, `AMAZON.MusicPlaylist`, `AMAZON.MusicRecording`, `AMAZON.ProgramSeries`, or `AMAZON.TerrestrialRadioChannel`.	String
`catalogs[].usage`	How you expect the catalog to be used. The `usage` value must correspond to the `type` value. Valid values: `AlexaTest.Catalog.AudioRecording`, `AlexaMusic.Catalog.BroadcastChannel`, `AlexaMusic.Catalog.Genre`, `AlexaMusic.Catalog.MusicAlbum`, `AlexaMusic.Catalog.MusicGroup`, `AlexaMusic.Catalog.MusicPlaylist`, `AlexaMusic.Catalog.MusicRecording`, `AlexaMusic.Catalog.ProgramSeries`, or `AlexaMusic.Catalog.TerrestrialRadioChannel`.	String
`catalogs[].createdDateTime`	Date and time when the catalog was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`catalogs[].lastUpdatedDateTime`	Date and time when the catalog was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`catalogs[].associatedSkills`	List of skills associated with the catalog.	Array of strings
`isTruncated`	Indicates whether there are more items to return. If set to `true`, include `nextToken` a subsequent request. Or, you can get the remaining items by using the `next` link in the `_links` object.	Boolean
`nextToken`	(Optional) Included when there are more results to return. Use this value in a subsequent request.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of catalogs for the specified vendor.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List uploads

List the uploads for the specified catalog.

Request

To list the uploads, you make a GET request to the /v0/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v0/catalogs/{catalogId}/uploads?maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`catalogId`	Path	Unique identifier of the catalog.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–50. Default: 50.	Number	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response.	String	No
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of uploads to the specified catalog. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "_links": {
        "self": {
            "href": "Link to first upload"
        },
        "next": {
            "href": "Link to next upload, if any"
        }
    },
    "uploads": [{
            "id": "upload.id.1",
            "catalogId": "catalog.id.1",
            "createdDate": "2020-10-27T05:10:15.811Z",
            "lastUpdatedDate": "2020-10-27T05:26:15.811Z",
            "status": "SUCCEEDED",
        },
        {
            "id": "upload.id.2",
            "catalogId": "catalog.id.1",
            "createdDate": "2020-10-27T05:10:15.811Z",
            "lastUpdatedDate": "2020-11-17T05:26:15.811Z",
            "status": "PENDING"
        }
    ],
    "isTruncated": true,
    "nextToken": "someToken1"
}

Response body properties

Property	Description	Type
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object
`uploads`	List of uploads for the specified catalog.	Array of objects
`uploads[].id`	Unique identifier of the upload.	String
`uploads[].catalogId`	Unique identifier of the catalog.	String
`uploads[].createdDateTime`	Date and time when the catalog was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`uploads[].lastUpdatedDateTime`	Date and time when the catalog was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`uploads[].status`	Status of the upload. Valid values: `PENDING`, `PROCESSING`, `FAILED`, `SUCCEEDED`.	String
`isTruncated`	Indicates whether there are more items to return. If set to `true`, include `nextToken` a subsequent request. Or, you can get the remaining items by using the `next` link in the `_links` object.	Boolean
`nextToken`	(Optional) Included when there are more results to return. Use this value in a subsequent request.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of uploads for the specified catalog.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023