Alexa Catalog Management

Certain voice model APIs support uploading your catalog content to Alexa. This allows the Alexa voice model to dynamically resolve customer utterances according to the catalog data as part of your Alexa skill. Therefore, you can improve the customer experience for your skill by using the Alexa Catalog API to upload your content catalog to Alexa.

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.

Process to create a catalog

The process to create a catalog, add content to it, and associate it with a skill, is as follows:

  1. Create a catalog.
  2. Create an upload obtain the uploadId and the presigned upload request URLs for the various upload parts.
  3. Upload the catalog file, in parts, to Amazon S3 using the presigned upload request URLs.
  4. Complete the upload by providing information from the Amazon S3 upload, in conjunction with any additional relevant metadata.

A catalog may be associated with zero, one, or multiple skills. A catalog to skill association is treated as resource that must be created before beginning uploads to the catalog.

Create a catalog

This creates a new catalog based on the basic information provided in the request. When a catalog is created, it does not have any records. The records are uploaded in a separate operation. The catalog is associated with the vendorId that calls the API.

Request

HTTP/1.1

POST /v0/catalogs 

Request body

{
  "title": "string",
  "type": "string",
  "usage": "string",
  "vendorId": "string"
}
ParameterDescriptionRequired
titleTitle of the catalog. Yes
typeType of catalog.Yes
usageHow the catalog will be used. Yes
vendorIdUnique 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 skill with a catalog

This API associates the specified catalog with the specified skill.

Request

HTTP 1.1

PUT /v0/skills/{skillId}/catalogs/{catalogId} 
FieldDescriptionParameter TypeRequired
skillIdUnique identifier of the skill.PathYes
catalogIdUnique identifier of the catalog.PathYes

Request body

None.

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

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

Request

HTTP/1.1

Get catalogs by vendorId

GET /v0/catalogs?vendorId={vendorId}&maxResults={num}&nextToken={token} 
FieldDescriptionParameter TypeRequired
vendorIdUnique identifier of the vendor.Query parameterYes
maxResultsMaximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.Query parameterNo
nextTokenContinuation 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

Request body

None.

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
_linksHypertext Application Language links to navigate through resources.
isTruncatedValue 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.
catalogsArray that contains catalog objects.

Parameters of links object

ParameterDescription
selfObject containing the URL for the upload.
self.hrefString of the URL for the upload.

Parameters of catalog object

The catalogs object is an array of catalog objects.

ParameterDescription
idUnique identifier for the uploads object.
titleTitle of the catalog.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDateDate upload part was created.
lastUpdatedDateDate that the upload part 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

Get a particular catalog

Returns the catalog specified by the catalogId.

Request

HTTP/1.1

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

Request body

No body.

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
idUnique identifier for the uploads object.
titleTitle of the catalog.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDateDate upload part was created.
lastUpdatedDateDate that the upload part 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 for a specified catalog

This API creates a new upload for a specified catalog and returns presigned upload parts that will be used to subsequently upload the file to Amazon S3.

Request

HTTP/1.1

POST /v0/catalogs/{catalogId}/uploads 

Request body

The numberOfParts value is an integer that that indicates the number of parts that the catalog will be split into. The response provides an equal number of presigned URLs, one for each part, in order to facilitate the upload.

{
  "numberOfParts": <integer>,
}

Response

A successful response returns a 201 code and an upload object.

{
  "id": "string",
  "catalogId": "string",
  "status": "PENDING",
  "createdDate": "2018-10-25T08:18:50.297Z",
  "lastUpdatedDate": "2018-10-25T08:18:50.297Z",
  "ingestionSteps": [
    {
      "name": "UPLOAD",
      "status": "PENDING",
      "logUrl": "string",
      "errors": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ],
  "presignedUploadParts": [
    {
      "url": "string",
      "partNumber": <integer>
    }
  ]
}
ParameterDescription
idUnique identifier for the upload object.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDateDate upload part was created.
lastUpdatedDateDate that the upload part was last updated.
ingestionStepsObject that represents a single step in the ingestion process of a new upload.

Parameters of ingestionSteps object

ParameterDescription
nameIndicates which ingestion step. One of: UPLOAD, SCHEMA_VALIDATION.
statusRepresents the status of the given step in the ingestion process of the upload. One of: PENDING, SUCCEEDED, FAILED, CANCELLED.
logUrlRepresents the url for the file containing logs of ingestion step.
errorsContains the errors occurred during the execution of step. If execution succeeded, this array is empty.

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

Get the uploads for a particular catalog

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

HTTP/1.1

GET /v0/catalogs/{catalogId}/uploads?maxResults={num}&nextToken={token}  
FieldDescriptionParameter TypeRequired
catalogIdUnique identifier of the catalog.PathYes
maxResultsMaximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.Query parameterNo
nextTokenContinuation 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

Request body

None.

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": "PENDING",
      "createdDate": "2018-10-27T05:26:15.811Z",
      "lastUpdatedDate": "2018-10-27T05:26:15.811Z"
    }
  ]
}
ParameterDescription
_linksHypertext Application Language links to navigate through resources.
isTruncatedValue 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.
uploadsObject array that lists the details for each upload.

Parameters of links object

ParameterDescription
selfObject containing the URL for the upload.
self.hrefString for the URL for the upload.

Parameters of uploads object

ParameterDescription
idUnique identifier for the uploads object.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDateDate upload part was created.
lastUpdatedDateDate 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 a particular upload

Gets detailed information about an upload which was created for a specific catalog. Includes the upload's ingestion steps and a presigned url for downloading the file.

The catalogId is the unique identifier of the catalog, and the uploadId is the unique identifier of the upload.

Request

HTTP/1.1

GET /v0/catalogs/{catalogId}/uploads/{uploadId}
FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.Path parameterYes

Request body

None.

Response

Returns a 200 code and an upload object.

{
  "id": "string",
  "catalogId": "string",
  "status": "PENDING",
  "createdDate": "2018-10-25T08:25:04.679Z",
  "lastUpdatedDate": "2018-10-25T08:25:04.679Z",
  "presignedDownloadUrl": "string",
  "ingestionSteps": [
    {
      "name": "UPLOAD",
      "status": "PENDING",
      "logUrl": "string",
      "errors": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ]
}

Parameters for upload object

ParameterDescription
idUnique identifier for the upload object.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDateDate upload part was created.
lastUpdatedDateDate that the upload part was last updated.
presignedDownloadUrlPresigned URL from which to download the part.
ingestionStepsAn ingestion step represents a single step in the ingestion process of a new upload.

Parameters for ingestionSteps object

ParameterDescription
nameIndicates which ingestion step. One of: UPLOAD, SCHEMA_VALIDATION.
statusRepresents the status of the given step in the ingestion process of the upload. One of: PENDING, SUCCEEDED, FAILED, CANCELLED.
logUrlRepresents the url for the file containing logs of ingestion step.
errorsContains the errors occurred during the execution of step. If execution succeeded, 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 a new upload

Creates a new upload for a catalog and returns presigned upload parts for uploading the file.

HTTP/1.1

POST /catalogs/{catalogId}/uploads

Request

Request body

{
  "numberOfUploadParts": 0,
  "locales": [
    "string"
  ]
}

Response

A successful response returns a 201 code to indicate creation was successful.

Response body

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

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

Completes an upload. To be called after the file is uploaded to the backend data store using presigned url(s), as described for Create a new upload.

Request

HTTP/1.1

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

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