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

  1. To create a new catalog and receive a catalogId, use Create catalog.
    If you already created a catalog, you can skip this step.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. (Optional) To get the status of an upload, see Get upload status v0.
  7. (Optional) To get the details of a catalog, use Get catalog.
  8. (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

  1. To create the catalog and receive a catalogId, use Create catalog.
  2. 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.
  3. To create a presigned URL to upload the catalog to an Alexa-hosted site, use Create Alexa-hosted upload URL v1.
  4. 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.
  5. To complete the upload, send the ETag values and part numbers with the Complete the upload API.
  6. (Optional) To get the status of an upload, see Get upload status v1.
  7. (Optional) To get the details of a catalog, use Get catalog.
  8. (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

  1. To create the catalog and receive a catalogId, use Create catalog.
  2. 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.
  3. To create a URL to upload the catalog, use Create self-hosted upload URL v1.
  4. Upload the catalog to the self-hosted URL from the previous step.
  5. (Optional) To get the status of an upload, see Get upload status v1.
  6. (Optional) To get the details of a catalog, use Get catalog.
  7. (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

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

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

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

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?

Last updated: Nov 27, 2023