Your Alexa Consoles

Your Alexa Consoles
- Skills
- Devices

Alexa Catalog Management

Note: The APIs described in this Alexa Catalog API document are /v0. The current supported version for other SMAPI skill APIs is /v1. Thus, your skill service code may use /v0 for the catalog APIs, and /v1 for the skill APIs.

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
Process to create a catalog
Create a catalog
- Request
- Response
  - Response codes
Associate a skill with a catalog
- Request
- Response
  - Response codes
Get the list of catalogs
- Request
- Response
  - Response codes
Get a particular catalog
- Request
- Response
  - Response codes
Create an upload for a specified catalog
- Request
- Response
  - Response codes
Get the uploads for a particular catalog
- Request
- Response
  - Response codes
Get a particular upload
- Request
- Response
  - Response codes
Create a new upload
- Request
- Response
  - Response codes
Complete an upload
- Request
- Response
  - Response codes

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:

Create a catalog.
Create an upload obtain the uploadId and the presigned upload request URLs for the various upload parts.
Upload the catalog file, in parts, to Amazon S3 using the presigned upload request URLs.
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"
}

Parameter	Description	Required
title	Title of the catalog.	Yes
type	Type of catalog.	Yes
usage	How the catalog will be used.	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

Code	Description
201	Created
400	Server cannot process the request due to a client error.
401	The auth token is invalid/expired or doesn’t have access to the resource.
403	The operation being requested is not allowed.
404	The resource being requested is not found.
429	Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500	Internal Server Error
503	Service 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}

Field	Description	Parameter Type	Required
skillId	Unique identifier of the skill.	Path	Yes
catalogId	Unique identifier of the catalog.	Path	Yes

Request body

None.

Response

A successful response returns a 201 code.

Response codes

Code	Description
201	Successfully associated
400	Server cannot process the request due to a client error.
401	The auth token is invalid/expired or doesn’t have access to the resource.
403	The operation being requested is not allowed.
404	The resource being requested is not found.
429	Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500	Internal Server Error
503	Service 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}

Field	Description	Parameter Type	Required
vendorId	Unique identifier of the vendor.	Query parameter	Yes
maxResults	Maximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.	Query parameter	No
`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 parameter	No

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"
      ]
    }
  ]
}

Parameter	Description
_links	Hypertext Application Language links to navigate through resources.
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.

Parameters of links object

Parameter	Description
self	Object containing the URL for the upload.
self.href	String of the URL for the upload.

Parameters of catalog object

The catalogs object is an array of catalog objects.

Parameter	Description
id	Unique identifier for the `uploads` object.
title	Title of the catalog.
catalogId	Unique identifier for the catalog.
status	Status of the entire upload. One of: `PENDING`, `PROCESSING`, `FAILED`, `SUCCEEDED`.
createdDate	Date upload part was created.
lastUpdatedDate	Date that the upload part was last updated.
associatedSkillIds	Array of skillIds associated with this catalog.

Response codes

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

Get a particular catalog

Returns the catalog specified by the catalogId.

Request

HTTP/1.1

GET /v0/catalogs/{catalogId}

Field	Description	Parameter Type	Required
catalogId	Unique identifier of the catalog. If not included, the entire set of catalogs is returned.	Path	Yes

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

Parameter	Description
id	Unique identifier for the uploads object.
title	Title of the catalog.
catalogId	Unique identifier for the catalog.
status	Status of the entire upload. One of: `PENDING`, `PROCESSING`, `FAILED`, `SUCCEEDED`.
createdDate	Date upload part was created.
lastUpdatedDate	Date that the upload part was last updated.
associatedSkillIds	Array of `skillIds` associated with this catalog.

Response codes

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

Parameter	Description
id	Unique identifier for the upload object.
catalogId	Unique identifier for the catalog.
status	Status of the entire upload. One of: `PENDING`, `PROCESSING`, `FAILED`, `SUCCEEDED`.
createdDate	Date upload part was created.
lastUpdatedDate	Date that the upload part was last updated.
ingestionSteps	Object that represents a single step in the ingestion process of a new upload.

Parameters of ingestionSteps object

Parameter	Description
name	Indicates which ingestion step. One of: UPLOAD, SCHEMA_VALIDATION.
status	Represents the status of the given step in the ingestion process of the upload. One of: `PENDING`, `SUCCEEDED`, `FAILED`, `CANCELLED`.
logUrl	Represents the url for the file containing logs of ingestion step.
errors	Contains the errors occurred during the execution of step. If execution succeeded, this array is empty.

Response codes

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

Field	Description	Parameter Type	Required
catalogId	Unique identifier of the catalog.	Path	Yes
maxResults	Maximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.	Query parameter	No
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 parameter	No

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"
    }
  ]
}

Parameter	Description
_links	Hypertext Application Language links to navigate through resources.
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.

Parameters of links object

Parameter	Description
self	Object containing the URL for the upload.
self.href	String for the URL for the upload.

Parameters of uploads object

Parameter	Description
id	Unique identifier for the uploads object.
catalogId	Unique identifier for the catalog.
status	Status of the entire upload. One of: `PENDING`, `PROCESSING`, `FAILED`, `SUCCEEDED`.
createdDate	Date upload part was created.
lastUpdatedDate	Date that the upload part was last updated.

Response codes

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

Field	Description	Parameter Type	Required
catalogId	Unique identifier of the catalog.	Path parameter	Yes

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

Parameter	Description
id	Unique identifier for the upload object.
catalogId	Unique identifier for the catalog.
status	Status of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDate	Date upload part was created.
lastUpdatedDate	Date that the upload part was last updated.
presignedDownloadUrl	Presigned URL from which to download the part.
ingestionSteps	An ingestion step represents a single step in the ingestion process of a new upload.

Parameters for ingestionSteps object

Parameter	Description
name	Indicates which ingestion step. One of: `UPLOAD`, `SCHEMA_VALIDATION`.
status	Represents the status of the given step in the ingestion process of the upload. One of: `PENDING`, `SUCCEEDED`, `FAILED`, `CANCELLED`.
logUrl	Represents the url for the file containing logs of ingestion step.
errors	Contains the errors occurred during the execution of step. If execution succeeded, this array is empty.

Response codes

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

Code	Description
201	Created
400	Server cannot process the request due to a client error.
401	The auth token is invalid/expired or doesn’t have access to the resource.
403	The operation being requested is not allowed.
404	The resource being requested is not found.
429	Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500	Internal Server Error
503	Service 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}

Field	Description	Parameter Type	Required
catalogId	Unique identifier of the catalog.	Path	Yes
uploadId	Unique identifier of the upload.	Path	Yes

Response

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

Response codes

Code	Description
202	Accepted
400	Server cannot process the request due to a client error.
401	The auth token is invalid/expired or doesn’t have access to the resource.
403	The operation being requested is not allowed.
404	The resource being requested is not found.
409	The 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.
500	Internal Server Error
503	Service Unavailable