Catalog Content Upload


Certain voice model APIs support uploading your catalog content so Alexa can access it. This allows the Alexa voice model to dynamically resolve customer utterances by referencing the catalog data as part of your Alexa skill. You can improve the customer experience for your skill by using the Catalog Content Upload API to upload your content catalog so that Alexa can access it.

You can upload your catalog content to Amazon S3, to a self-hosted URL, or to an Alexa-hosted site.

API endpoint and header

The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

API version

Use the appropriate /v0 APIs to create your catalogs, regardless of where you plan to host them.

If you want to use Amazon S3 to host your catalogs, use the appropriate /v0 APIs to upload and manage your catalog content.

If you want to use a self-hosted site, or an Alexa-hosted site, to host your catalogs, use the appropriate /v1 APIs so you can upload and manage your catalog content using your own domains.

Create and upload a catalog to Amazon S3

Use the following process with the /v0 APIs to create a catalog, associate it with a skill, add content to it, and upload it to Amazon S3.

  1. Create a catalog.
  2. Associate the catalog with a skill. A catalog can be associated with zero, one, or multiple skills. You must associate the catalog with a skill before beginning uploads to the catalog.
  3. Create an upload, v0 to get the uploadId and one or more presigned URLs to use for uploading the catalog.
  4. Upload the catalog to Amazon S3 using the presigned URL or URLs that you got in the previous step. To upload the catalog, send a PUT request to the presigned URL (or URLs when using multi-part upload), with the catalog (or 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. For more information about uploading content to Amazon S3, see Amazon S3–Uploading Objects Using Presigned URLs.

    You can optionally use multi-part upload to upload a large catalog.

    • Single upload – For a catalog that is 5 GB or less, you can send one PUT request to the presigned URL to upload the entire catalog.
    • Multi-part upload – Multi-part upload can help improve the upload experience for large catalogs, because you can upload the catalog in parts instead of all at once. For a catalog that is 5 MB or more, you can optionally use multi-part upload. For a catalog that is more than 5 GB, you must use multi-part upload. The total size of the catalog must be less than 5 TB.

      To use multi-part upload, split your catalog into parts, each of which is at least 5 MB but no more than 5 GB. The last part can be less than 5 MB. Send a PUT request to the presigned URLs from the previous step, with a different catalog part in the body of each request. You can send these PUT requests independently, in any order, and in parallel.

      Save the ETag values that you receive in the response to each PUT request, then provide them in the following step to complete the upload. After you complete the upload, the parts are assembled back into a single catalog.

  5. Complete the upload by providing the ETags from each of the Amazon S3 uploads completed in the previous step.
  6. If desired, get information about a specified upload, v0.
  7. If desired, get the list of catalogs, or get a specified catalog, v0.

Create and upload a catalog to a self-hosted or Alexa-hosted domain

Use the following process with a combination of /v0 and /v1 APIs to create a catalog, associate it with a skill, add content to it, and upload it to your own domain.

  1. Create a catalog with the /v0 API.
  2. Associate the catalog with a skill with the /v0 API. A catalog can be associated with zero, one, or multiple skills. You must associate the catalog with a skill before beginning uploads to the catalog.
  3. If you are uploading your catalog to a self-hosted URL, follow the steps in Create an upload for your catalog for a self-hosted domain, v1.
  4. If you are uploading your catalog to an Alexa-hosted URL, follow the steps in generate a presigned URL to upload catalog content, v1.
  5. If desired, get information about a specified upload, v1.
  6. If desired, get the list of catalogs, v1, or get a specified catalog, v1.
  7. If you are using a self-hosted URL, upload the catalog to that location.
  8. If you are using an Alexa-hosted URL, upload the catalog to the presigned URL or URLs that you have generated in step #4. To upload the catalog, send a PUT request to the presigned URL (or URLs when using multi-part upload), with the catalog (or catalog part) in the body of the request. The response to each PUT request contains an ETag value in the ETag header.

    • Single upload – For a catalog that is 5 GB or less, you can send one PUT request to the presigned URL to upload the entire catalog.
    • Multi-part upload – Multi-part upload can help improve the upload experience for large catalogs, because you can upload the catalog in parts instead of all at once. For a catalog that is 5 MB or more, you can optionally use multi-part upload. For a catalog that is more than 5 GB, you must use multi-part upload. The total size of the catalog must be less than 5 TB.

      To use multi-part upload, split your catalog into parts, each of which is at least 5 MB but no more than 5 GB. The last part can be less than 5 MB. Send a PUT request to the presigned URLs from the previous step, with a different catalog part in the body of each request. You can send these PUT requests independently, in any order, and in parallel.

      Save the ETag values that you receive in the response to each PUT request, then provide them in the following step to complete the upload. After you complete the upload, the parts are assembled back into a single catalog.

Create a catalog

This creates a new catalog based on the basic information provided in the request. When you create a catalog, it does not have any records. You upload the records in a separate operation. When you call the API while using your developer account, the catalog is associated with the vendorId for that account.

Request

POST /v0/catalogs

Example of request body

{
  "title": "string",
  "type": "string",
  "usage": "string",
  "vendorId": "string"
}
ParameterDescriptionRequired
title Title of the catalog. Yes
type

Type of catalog. Must be one of: AMAZON.AudioRecording, AMAZON.BroadcastChannel, AMAZON.Genre, AMAZON.MusicAlbum, AMAZON.MusicGroup, AMAZON.MusicPlaylist, AMAZON.MusicRecording, or AMAZON.TerrestrialRadioChannel . The type value must match the usage value. For example, if you specify AMAZON.MusicAlbum as the type, then you must specify AlexaMusic.Catalog.MusicAlbum as the usage.

Yes
usage

How the catalog will be used. Must be one of: AlexaTest.Catalog.AudioRecording, AlexaMusic.Catalog.BroadcastChannel, AlexaMusic.Catalog.Genre, AlexaMusic.Catalog.MusicAlbum, AlexaMusic.Catalog.MusicGroup, AlexaMusic.Catalog.MusicPlaylist, AlexaMusic.Catalog.MusicRecording, or AlexaMusic.Catalog.TerrestrialRadioChannel. The usage value must correspond to the type value.

Yes
vendorId Unique identifier of a vendor.Yes

Response

A successful response returns a 201 code and the title of the catalog as a string.

Response codes

CodeDescription
201Created
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Associate a catalog with a skill

This API associates the specified catalog with the specified skill.

Request

PUT /v0/skills/{skillId}/catalogs/{catalogId}

No request body.

FieldDescriptionParameter TypeRequired
skillId Unique identifier of the skill.PathYes
catalogId Unique identifier of the catalog.PathYes

Response

A successful response returns a 201 code.

Response codes

CodeDescription
201Successfully associated
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get the list of catalogs, v0

Lists all the catalogs associated with a vendorId. The optional maxResults and nextToken values provide paging for the results.

Request

GET /v0/catalogs?vendorId={vendorId}&maxResults={num}&nextToken={token}

No request body.

FieldDescriptionParameter TypeRequired
vendorId Unique identifier of the vendor.Query parameterYes
maxResults Maximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.Query parameterNo
nextToken Continuation token returned in response object of last list skills response. If this is parameter is null, the response will include skills from first set.Query parameterNo

Response

A successful response returns a 200 code and a _links object, which provides a link for each returned catalogId, and a catalogs object, which is an array of catalogs, each of which is specified by a unique identifier.

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "isTruncated": true,
  "nextToken": "string",
  "catalogs": [
    {
      "id": "string",
      "title": "string",
      "type": "string",
      "usage": "string",
      "lastUpdatedDate": "2018-10-25T08:07:27.057Z",
      "createdDate": "2018-10-25T08:07:27.057Z",
      "associatedSkillIds": [
        "string"
      ]
    }
  ]
}
ParameterDescription
_links Hypertext Application Language links to navigate through resources.
_links.self Object containing the URL for the upload.
_links.self.href String of the URL for the upload.
isTruncated Value is true if there is more than one page of results.
nextToken When the response to this API call is truncated (that is, if the isTruncated value is true), the response also includes the nextToken element. The value of nextToken can be used in the next request as the continuation token to list the next set of objects.
catalogs Array that contains catalog objects.
catalogs.id Unique identifier for the uploads object.
catalogs.title Title of the catalog.
catalogs.type Type of catalog.
catalogs.usage Usage of catalog.
catalogs.createdDate Date upload part was created.
catalogs.lastUpdatedDate Date that the upload part was last updated.
catalogs.associatedSkillIds Array of skillIds associated with this catalog.

Response codes

CodeDescription
200Successful operation
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get a particular catalog, v0

Returns the catalog specified by the catalogId.

Request

GET /v0/catalogs/{catalogId}
FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog. If not included, the entire set of catalogs is returned. PathNo

Response

A successful response returns a 200 code and a catalog object.

{
  "id": "string",
  "title": "string",
  "type": "string",
  "usage": "string",
  "lastUpdatedDate": "2018-10-25T08:07:55.752Z",
  "createdDate": "2018-10-25T08:07:55.752Z",
  "associatedSkillIds": [
    "string"
  ]
}

Parameters for catalog object

ParameterDescription
id Unique identifier for the uploads object.
title Title of the catalog.
type Type of catalog.
usage Usage of catalog.
createdDate Date upload part was created.
lastUpdatedDate Date that the catalog was last updated.
associatedSkillIdsArray of skillIds associated with this catalog.

Response codes

CodeDescription
200Successful operation
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Create an upload, v0

Creates a new upload for a catalog, returning the uploadId and one or more presigned URLs for uploading the catalog.

After calling this API, upload the catalog to Amazon S3 using the presigned URL or URLs that you received in the response. For more information about how to upload a catalog, see Process to create a catalog.

When you finish uploading the catalog, complete the upload by providing the ETag values from each of the Amazon S3 upload requests.

Request

POST /v0/catalogs/{catalogId}/uploads
FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.PathYes

Example of request body

{
  "numberOfUploadParts": 2
}
FieldDescriptionParameter TypeRequired
numberOfUploadParts Specifies the number of upload parts, when using multi-part upload. For the structure, see the following JSON.BodyRequired when using multi-part upload. When this is not included, it defaults to 1.

Response

A successful response returns a 201 code to indicate creation was successful, and an upload, v0 object. See Parameters of upload object, v0.

Example of response body

{
  "id": "string",
  "catalogId": "string",
  "status": "string",
  "locales": [
    "string"
  ],
  "createdDate": "2019-04-06T23:52:20.528Z",
  "lastUpdatedDate": "2019-04-06T23:52:20.528Z",
  "ingestionSteps": [
    {
      "name": "UPLOAD",
      "status": "string",
      "logUrl": "string",
      "errors": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ],
  "presignedUploadParts": [
    {
      "url": "string",
      "partNumber": 1
    }
  ]
}

Response codes

CodeDescription
201Created
400 Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403 The operation being requested is not allowed.
404The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Complete an upload, v0

Completes an upload. Send this request after you upload the catalog to Amazon S3 using presigned URLs. For more information about how to upload a catalog, see Process to create a catalog.

Request

POST /v0/catalogs/{catalogId}/uploads/{uploadId}
FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.PathYes
uploadId Unique identifier of the upload.PathYes

Example of request body

{
  "partETags": [
    {
      "eTag": "string",
      "partNumber": 1
    },
    {
      "eTag": "string",
      "partNumber": 2
    }
  ]
}
FieldDescriptionParameter TypeRequired
partETags A list of ETag (string) and part number (integer) pairs, one for each part of the catalog that was uploaded with multi-part upload. For the structure, see the following JSON.BodyRequired when the catalog was uploaded with multi-part upload.

Response

A successful response returns a 202 code to indicate the upload was accepted.

Response codes

CodeDescription
202Accepted
400 Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403 The operation being requested is not allowed.
404The resource being requested is not found.
409The request could not be completed due to a conflict with the current state of the target resource.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get the list of uploads, v0

Lists the uploads for a particular catalog. An upload is a file that contributes to a catalog, after validation. The optional maxResults and nextToken values provide paging for the results.

Request

GET /v0/catalogs/{catalogId}/uploads?maxResults={num}&nextToken={token}

No request body.

FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.PathYes
maxResults Maximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.Query parameterNo
nextToken Continuation token returned in response object of last list skills response. If this is parameter is null, the response will include skills from first set.Query parameterNo

Response

Successful response returns a 200 code and an object that includes links to the upload parts, and a list of the uploads.

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "isTruncated": true,
  "nextToken": "string",
  "uploads": [
    {
      "id": "string",
      "catalogId": "string",
      "status": "string",
      "createdDate": "2018-10-27T05:26:15.811Z",
      "lastUpdatedDate": "2018-10-27T05:26:15.811Z"
    }
  ]
}
ParameterDescription
_links Hypertext Application Language links to navigate through resources.
_links.self Object containing the URL for the upload.
_links.self.href String for the URL for the upload.
_links.next Object containing the URL for the next upload, if there is one after _links.self. If there are multiple URLs besides _links.self, the _links object contains a _links.next object for each of these URLs.
_links.next.href String for the URL for the next upload.
isTruncated Value is true if there is more than one page of results.
nextToken When the response to this API call is truncated (that is, if the isTruncated value is true), the response also includes the nextToken element. The value of nextToken can be used in the next request as the continuation token to list the next set of objects.
uploads Object array that lists the details for each upload.
uploads.id Unique identifier for the uploads object.
uploads.catalogIdUnique identifier for the catalog.
uploads.status Status of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
uploads.createdDate Date upload part was created.
uploads.lastUpdatedDate Date that the upload part was last updated.

Response codes

CodeDescription
200Successful operation
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get information about a specified upload, v0

Gets information about a specified upload for a specific catalog.

The catalogId identifies the catalog, and the uploadId identifies the upload.

Request

GET /v0/catalogs/{catalogId}/uploads/{uploadId}

No request body.

FieldDescriptionParameter TypeRequired
catalogId Unique identifier for the catalog.Path parameterYes
uploadId Unique identifier for the upload.Path parameterYes

Response

Returns a 200 code and an upload object.

{
  "id": "string",
  "catalogId": "string",
  "status": "string",
  "createdDate": "date time stamp",
  "lastUpdatedDate": "date time stamp",
  "file": {
    "presignedDownloadUrl": "string",
    "status": "string"
  },
  "ingestionSteps": [
    {
      "name": "string",
      "status": "string",
      "logUrl": "string",
      "errors": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ]
}

Parameters for upload object, v0

ParameterDescription
id Unique identifier for the upload object.
catalogId Unique identifier for the catalog.
status Status of the entire upload. One of: PENDING, PROCESSING, FAILED, or SUCCEEDED.
createdDate Date and time that the upload part was created, in the following format: 2018-10-25T08:25:04.679Z.
lastUpdatedDate Date and time that the upload part was last updated, in the following format: 2018-10-25T08:25:04.679Z.
file A file object represents a previously uploaded file for a specific catalog.
file.presignedDownloadUrl A URL where you can download the previously uploaded file.
file.status The status of the file. One of: PENDING, AVAILABLE, UNAVAILABLE, or PURGED.
ingestionSteps An ingestion step represents a single step in the ingestion process of a new upload.
ingestionSteps.name Indicates which ingestion step. One of: UPLOAD, SCHEMA_VALIDATION.
ingestionSteps.status Represents the status of the given step in the ingestion process of the upload. One of: PENDING, SUCCEEDED, FAILED, or CANCELLED.
ingestionSteps.logUrl Represents the url for the file containing logs of ingestion step.
ingestionSteps.errors Contains any errors that occur. If no errors occur, this array is empty.

Response codes

CodeDescription
200Successful operation
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Create an upload for a self-hosted domain, v1

Creates a new upload for a catalog, and returns a relative URL in the Location header to track the upload.

Request

POST /v1/catalogs/{catalogId}/uploads
FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.PathYes

Request body

The request body can either contain a self-hosted URL location, or a presigned URL object that references one or more parts if you are using an Alexa-hosted URL. If your catalog is larger than 5 GB, you should upload it using multiple parts.

Example request body for self-hosted URL location

{
    "location": "string"
}

Example request body for presignedUrl

{
  "preSignedUrl": {
    "urlId": "string",
    "partETags": [
      {
        "eTag": "string",
        "partNumber": 1
      },
      {
        "eTag": "string",
        "partNumber": 2
      }
    ]
  }
}
FieldDescriptionParameter Type
location Unique identifier of the URL. Use if you are uploading the catalog to a self-hosted URL. Required if preSignedUrl is not used. Path
preSignedUrl Object that contains information for a multi-part upload. Use if you are uploading the catalog to an Alexa-hosted URL. Required if location is not used. Object
preSignedUrl.urlId Unique identifier of the URL. Required if preSignedUrl is present. Path
preSignedUrl.partETags A list of ETag (string) and part number (integer) pairs, one for each part of the catalog that was uploaded with a multi-part upload. For the structure, see the JSON example. Required when the catalog has been uploaded with a multi-part upload. Body

Response

A successful response returns a 202 code with a relative URL in the Location header to track the upload.

Response codes

CodeDescription
202Accepted
400 Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403 The operation being requested is not allowed.
404The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get information about a specified upload, v1

Gets detailed information about an upload which was created for a specific catalog.

Request

GET /v1/catalogs/{catalogId}/uploads/{uploadId}

No request body.

FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.PathYes
uploadId Unique identifier of the upload.PathYes

Response

A successful response returns a 200 code and an object that Includes the upload's ingestion steps and a url for downloading the file.

{
  "id": "string",
  "catalogId": "string",
  "status": "PENDING",
  "createdDate": "2019-10-04T00:37:13.593Z",
  "lastUpdatedDate": "2019-10-04T00:37:13.593Z",
  "file": {
    "downloadUrl": "string",
    "expiresAt": "string",
    "status": "PENDING"
  },
  "ingestionSteps": [
    {
      "name": "UPLOAD",
      "status": "PENDING",
      "logUrl": "string",
      "violations": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ]
}
ParameterDescription
id String identifier for upload.
catalogId String identifer for catalog.
status Status of the entire upload. One of: PENDING, IN_PROGRESS, FAILED, SUCCEEDED.
file Object that describes the catalog file.
file.downloadUrl URL from which to download the catalog file.
file.expiresAt Date-time at which file.downloadUrl expires.
file.status Status of the file. One of: PENDING, AVAILABLE, PURGED, UNAVAILABLE.
ingestionSteps Object that describes the ingestion steps.
ingestionSteps.name One of:UPLOAD, SCHEMA_VALIDATION.
ingestionSteps.status Status of the ingestion steps. One of: PENDING, IN_PROGRESS, FAILED, SUCCEEDED, CANCELLED.
ingestionSteps.logUrl URL that contains a log of the ingestion activity.
ingestionSteps.violations Object that contains any error messages related to the ingestion steps.
ingestionSteps.violations.code Numerical code of the error message.
ingestionSteps.violations.message Description of the error message.

Response codes

CodeDescription
200Successful operation
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Generate a URL to upload catalog content, v1

Generates an Alexa-hosted URL to which catalog content can be uploaded. You can use the generated URLs with accompanying part numbers to perform a multi-part upload, as described at Create and upload a catalog to a self-hosted or Alexa-hosted domain.

Request

POST /v1/catalogs/{catalogId}/urls

FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.PathYes

Example of request body

{
  "numberOfUploadParts": 2
}
FieldDescriptionParameter TypeRequired
numberOfUploadParts Number of upload parts in which the catalog is divided.IntegerYes

Response

A successful response returns a 201 code to indicate creation was successful, and URL information in the body.

Response body

{
  "urlId": "string",
  "preSignedUploadParts": [
    ...
    {
      "url": "string",
      "partNumber": integer,
      "expiresAt": "string"
    }, ...
  ]
}
FieldDescription
urlId Unique identifier of the URL.
preSignedUploadParts Object that contains information about the parts of the multi-part upload. Each part is represented by an item in the list.
preSignedUploadParts.url Unique identifier of the URL. Required.
preSignedUploadParts.expiresAt Date-time value by when the URL expires.
preSignedUploadParts.partNumber Indicates which part number of the upload. The part numbers begin with 1.

Response codes

CodeDescription
201Created
400 Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403 The operation being requested is not allowed.
404The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Last updated: Mar 30, 2022