Catalog Management REST API Reference
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.
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 PUTrequest 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 thelastUpdatedTimevalue.
The response header contains anETagvalue. Save theETagvalues 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
ETagvalues 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
PUTrequest to the presigned URL with the catalog in the body of the request.
To upload the catalog in multiple parts, send aPUTrequest 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 theETagheader. You need this ETag value to complete the upload in the following step. - To complete the upload, send the
ETagvalues 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
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
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill to associate with the catalog. |
String |
Yes |
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Header |
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 |
|---|---|
|
|
Skill associated with the specified catalog successfully. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Path |
Unique identifier of the upload. |
String |
Yes |
|
|
Header |
String |
Yes |
Request body example
{
"partETags": [{
"eTag": "etag.1",
"partNumber": 1
},
{
"eTag": "etag.2",
"partNumber": 2
}
]
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
List of |
Array of objects |
Yes |
|
|
Opaque identifier for last successful upload of this part. |
String |
Yes |
|
|
Part number of the upload. |
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. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Header |
String |
Yes |
Request body example
{
"title": "My.Music.Catalog",
"type": "AMAZON.MusicGroup",
"usage": "AlexaMusic.Catalog.MusicGroup",
"vendorId": "your.vendor.id.1"
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Title of the catalog. |
String |
Yes |
|
|
Type of catalog. |
String |
Yes |
|
|
How you expect the catalog to be used. |
String |
Yes |
|
|
Identifies the vendor that creates the catalog. |
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 |
|---|---|---|
|
|
Unique identifier of the new catalog. |
String |
|
|
Title of the catalog. |
String |
|
|
Type of catalog. |
String |
|
|
How you expect the catalog to be used. |
String |
|
|
Date and time when the catalog was created. |
String |
|
|
Date and time when the catalog was last updated. |
String |
|
|
List of skills associated with the catalog. |
Array of strings |
HTTP status codes
| Status | Description |
|---|---|
|
|
Catalog created successfully. Response body contains the catalog details. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Header |
String |
Yes |
Request body example
{
"numberOfUploadParts": 3
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
For multi-part uploads, specify the number of parts the content is split into. |
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 |
|---|---|---|
|
|
Unique identifier of the upload. |
String |
|
|
Unique identifier of the new catalog. |
String |
|
|
Date and time when the catalog was created. |
String |
|
|
Date and time when the catalog was last updated. |
String |
|
|
Status of the upload. |
String |
|
|
List of ingestion steps. |
Array of objects |
|
|
Name of the ingestion step. |
String |
|
|
Status of the ingestion step. |
String |
|
|
(Optional) URL to the log file containing information about the ingestion step. |
String |
|
|
List of errors that occurred during this ingestion step. |
Array of objects |
|
|
HTTP status code that reflects the error. |
String |
|
|
Human readable error message. |
String |
|
|
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. |
Array of objects |
|
|
URL to use to upload the part specified by |
String |
|
|
Part number to upload at the presigned URL. |
Integer |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the upload ID and one or more presigned URLs. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Header |
String |
Yes |
Request body example
{
"numberOfUploadParts": 3
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
For multi-part uploads, specify the number of parts the content is split into. |
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
{
"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 |
|---|---|---|
|
|
Unique identifier of the upload. |
String |
|
|
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. |
Array of objects |
|
|
URL to use to upload the part specified by |
String |
|
|
Part number to upload at the presigned URL. |
Integer |
|
|
Date and time when the URL expires. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the upload ID and one or more presigned URLs. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Header |
String |
Yes |
Request body example
The following example shows a request to create an upload URL for a self-hosted site.
{
"location": "https://example.com/upload.url"
}
The following example shows a request to create an URLs for a multi-part upload.
{
"preSignedUrl": {
"urlId": "https://www.example.com",
"partETags": [
{
"eTag": "string",
"partNumber": 1
},
{
"eTag": "string",
"partNumber": 2
}
]
}
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Unique URL for the upload.
Either |
Integer |
No |
|
|
Information for a multi-part upload.
Either |
Object |
No |
|
|
Unique URL for the upload. |
String |
Yes |
|
|
List of |
Array of objects |
Yes |
|
|
Opaque identifier for last successful upload of this part. |
String |
Yes |
|
|
Part number of the upload. |
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 |
|---|---|
|
|
Upload created successfully. The |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Header |
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 |
|---|---|---|
|
|
Unique identifier of the new catalog. |
String |
|
|
Title of the catalog. |
String |
|
|
Type of catalog. |
String |
|
|
How you expect the catalog to be used. |
String |
|
|
Date and time when the catalog was created. |
String |
|
|
Date and time when the catalog was last updated. |
String |
|
|
List of skills associated with the catalog. |
Array of strings |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains details about the requested catalog. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Path |
Unique identifier of the upload. |
String |
Yes |
|
|
Header |
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 |
|---|---|---|
|
|
Unique identifier of the upload. |
String |
|
|
Unique identifier of the catalog. |
String |
|
|
Date and time when the catalog was created. |
String |
|
|
Date and time when the catalog was last updated. |
String |
|
|
Status of the upload. |
String |
|
|
List of ingestion steps. |
Array of objects |
|
|
Name of the ingestion step. |
String |
|
|
Status of the ingestion step. |
String |
|
|
(Optional) URL to the log file containing information about the ingestion step. |
String |
|
|
List of errors that occurred during this ingestion step. |
Array of objects |
|
|
HTTP status code that reflects the error. |
String |
|
|
Human readable error message. |
String |
|
|
Status of the content upload specified by the |
Object |
|
|
If the file is available for download, use the presigned download URL to download the uploaded catalog content. |
String |
|
|
Status of the catalog upload. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the status of the specified upload. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Path |
Unique identifier of the upload. |
String |
Yes |
|
|
Header |
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",
"violations": []
}],
"file": {
"presignedDownloadUrl": "https://example.com/download.url.1",
"expiresAt": "2019-04-08T23:52:20.528Z",
"status": "AVAILABLE"
}
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Unique identifier of the upload. |
String |
|
|
Unique identifier of the catalog. |
String |
|
|
Date and time when the catalog was created, if known. |
String |
|
|
Date and time when the catalog was last updated. |
String |
|
|
Status of the upload. |
String |
|
|
List of ingestion steps. |
Array of objects |
|
|
Name of the ingestion step. |
String |
|
|
Status of the ingestion step. |
String |
|
|
(Optional) URL to the log file containing information about the ingestion step. |
String |
|
|
List of errors that occurred during this ingestion step. |
Array of objects |
|
|
HTTP status code that reflects the error. |
String |
|
|
Human readable error message. |
String |
|
|
Status of the content upload specified by the |
Object |
|
|
If the file is available for download, use the presigned download URL to download the uploaded catalog content. |
String |
|
|
Status of the catalog upload. |
String |
|
|
Date and time when the URL expires. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the status of the specified upload. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Query |
Identifies the vendor that creates the catalog. |
String |
Yes |
|
|
Query |
Maximum number of results to return in the response. |
Number |
No |
|
|
Query |
Token from the previous response. |
String |
No |
|
|
Header |
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 for item navigation. |
_links object |
|
|
List of catalogs owned by the specified vendor ID. |
Array of objects |
|
|
Unique identifier of the catalog. |
String |
|
|
Title of the catalog. |
String |
|
|
Type of catalog. |
String |
|
|
How you expect the catalog to be used. |
String |
|
|
Date and time when the catalog was created. |
String |
|
|
Date and time when the catalog was last updated. |
String |
|
|
List of skills associated with the catalog. |
Array of strings |
|
|
Indicates whether there are more items to return. If set to |
Boolean |
|
|
(Optional) Included when there are more results to return. Use this value in a subsequent request. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains a list of catalogs for the specified vendor. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Unique identifier of the catalog. |
String |
Yes |
|
|
Query |
Maximum number of results to return in the response. |
Number |
No |
|
|
Query |
Token from the previous response. |
String |
No |
|
|
Header |
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 for item navigation. |
_links object |
|
|
List of uploads for the specified catalog. |
Array of objects |
|
|
Unique identifier of the upload. |
String |
|
|
Unique identifier of the catalog. |
String |
|
|
Date and time when the catalog was created. |
String |
|
|
Date and time when the catalog was last updated. |
String |
|
|
Status of the upload. |
String |
|
|
Indicates whether there are more items to return. If set to |
Boolean |
|
|
(Optional) Included when there are more results to return. Use this value in a subsequent request. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains a list of uploads for the specified catalog. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
Last updated: Aug 01, 2024