Interaction Model Catalog Management REST API Reference

Note: Sign in to the developer console to build or publish your skill.

Use the Interaction Model Catalog Management REST API to create and manage external data sources for slot type values. In your custom voice interaction model, you can create a slot type that references an external data source by catalog ID and version number. For example, instead of entering ingredients as slot type values in your recipe skill, you specify the catalog identifier for your external data source that contains the list of ingredients.

To create a reference-based interaction model catalog, use the following APIs to create the catalog, and then add data to a new catalog version: Create catalog and Create catalog version. Use the catalogId and version as a reference in a slot type in your custom interaction model.

Note: The catalog must be in JSON format.

As an option, you can create and manage the catalog by using the Alexa Skills Kit (ASK) Command Line Interface.

API endpoint

The endpoint of the Interaction Model 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 Interaction Model Catalog API includes the following operations.

Operation	HTTP method and URI
Create catalog	`POST /v1/skills/api/custom/interactionModel/catalogs/`
Create catalog version	`POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions`
Delete catalog	`DELETE /v1/skills/api/custom/interactionModel/catalogs/{catalogId}`
Delete catalog version	`DELETE /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}`
Get catalog	`GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}`
Get catalog data	`GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}/values?maxResults={maxResults}&nextToken={nextToken}`
Get catalog metadata	`GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}`
Get catalog status	`GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/updateRequest/{updateRequestId}`
List catalogs	`GET /v1/skills/api/custom/interactionModel/catalogs/?vendorId={vendorId}&maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}`
List catalog versions	`GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions?maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}&sortField={sortField}`
Update catalog definition	`POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/update`
Update catalog version	`POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}/update`

Create catalog

Create an interaction model catalog to hold slot type values. To add data to the catalog, see Create catalog version.

Request

To create a catalog, you make a POST request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/api/custom/interactionModel/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.

{
    "vendorId": "your.vendor.id.1",
    "catalog": {
        "name": "Cookie ingredients",
        "description": "Contains recipe ingredients."
    }
}

Request body properties

Property	Description	Type	Required
`vendorId`	Identifies the vendor to which the catalog belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	Yes
`catalog`	Information about the catalog.	Object	Yes
`catalog.name`	Name of the catalog.	String	Yes
`catalog.description`	Describes the catalog. Valid value: Up to 255 characters.	String	No

Response

A successful response returns HTTP 200 OK, along with the generated catalog ID. 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 following example shows a response.

{
    "catalogId": "catalog.id.1"
}

Response body properties

Property	Description	Type
`catalogId`	Unique identifier for the new catalog.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the generated catalog ID.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 version

Create a new version of an interaction model catalog for the specified catalog ID. After you create a catalog, you use this API to add data to a new catalog version.

The catalog must be in JSON format. The following recipe-skill example shows the catalog format.

{
  "values":
  [
    {
        "id": "id1",
        "name": {
            "value": "coconut milk"
        }
    },
    {
        "id": "id2",
        "name": {
            "value": "shallots"
        }
    },
    {
        "id": "id3",
        "name": {
            "value": "bell peppers"
        }
    }
 ]
}

Request

To create a new catalog version, you make a POST request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions
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	Identifies the catalog.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
   "source": {
      "type": "URL",
      "url": "https://example.com/catalog/v2"
   },
   "description": "Version 2 contains additional recipe ingredients."
}

Request body properties

Property	Description	Type	Required
`source`	Location of the catalog.	Object	Yes
`source.type`	Catalog type. Must be `"URL"`.	String	Yes
`source.url`	HTTPS URL to the catalog location. For the format of the catalog file, see the top of Create catalog version.	String	Yes
`description`	Describes this version of the catalog. Valid value: Up to 255 characters.	String	No

Response

A successful response returns HTTP 202 Accepted, that indicates that the Alexa service created the specified catalog version. The response header contains a Location parameter with a URL to the 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

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`202 Accepted`	Request to create the catalog version succeeded.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

Delete catalog

Delete the specified interaction model catalog.

Request

To delete a catalog, you make a DELETE request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

DELETE /v1/skills/api/custom/interactionModel/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
`catalogId`	Path	Identifies the catalog.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The response has no body.

Response

A successful response returns HTTP 204 No Content to indicate that the catalog was deleted. 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
`204 No Content`	Successful deletion of 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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

Delete catalog version

Delete the specified version of the interaction model catalog.

Request

To delete a catalog version, you make a DELETE request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

DELETE /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}
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	Identifies the catalog.	String	Yes
`version`	Path	Identifies the catalog version to delete.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The response has no body.

Response

A successful response returns HTTP 204 No Content to indicate that the Alexa service deleted the specified catalog version. 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
`204 No Content`	Successful deletion of the specified catalog version.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 definition of the interaction model catalog specified by the catalog ID.

Request

To get the catalog, you make a GET request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/api/custom/interactionModel/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	Identifies 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 definition of 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

{
    "catalog": {
        "name": "Cookie ingredients",
        "description": "Contains recipe ingredients"
    },
    "createTime": "2019-01-06T05:26:02.430Z",
    "totalVersions": "2"
}

Response body properties

Property	Description	Type
`catalog`	Information about the catalog.	Object
`catalog.name`	Name of the catalog.	String
`catalog.description`	Describes the catalog. Valid value: Up to 255 characters.	String
`creationTime`	Creation date and time of the catalog. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`totalVersions`	Number of defined versions.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains details about 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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 data

Get the data defined in the interaction model catalog specified by the catalog ID and version.

Request

To get the catalog data, you make a GET request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}/values?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	Identifies the catalog.	String	Yes
`version`	Path	Identifies the catalog version.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–250. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. 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 the catalog data. 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

{
    "values": [{
            "id": "ingredient.1",
            "name": {
                "value": "butter",
                "synonyms": ["margarine", "oil"]
            }
        },
        {
            "id": "ingredient.2",
            "name": {
                "value": "sugar"
            }
        }
    ],
    "isTruncated": false,
    "totalCount": 2,
    "_links": {
        "next": {
            "href": "next_href"
        },
        "self": {
            "href": "current_href"
        }
    }
}

Response body properties

Property	Description	Type
`values`	List of slot type values defined in the catalog.	Array of objects
`values[].id`	Unique identifier for the data item.	String
`values[].name`	Values for the data item.	Object
`values[].name.type`	Slot type value.	String
`values[].name.synonyms`	(Optional) List of synonyms for the type.	Array of 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
`totalCount`	Total number of values in the catalog.	Integer
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object

HTTP status codes

Status	Description
`200 OK`	Response body contains the data defined in 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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 metadata

Get the metadata for the interaction model catalog specified by the catalog ID and version.

Request

To get the catalog metadata, you make a GET request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}
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	Identifies the catalog.	String	Yes
`version`	Path	Identifies the catalog version.	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 metadata of the specified catalog version. 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

{
    "source": {
        "type": "URL",
        "url": "https://example.com/catalog/v2"
    },
    "version": "catalog.version.2",
    "description": "Version 2 modifies the cookie recipe ingredients"
}

Response body properties

Property	Description	Type
`source`	Location of the catalog.	Object
`source.type`	Catalog type. Must be `"URL"`.	String
`source.url`	HTTPS URL to the catalog location.	String
`version`	Version number of the catalog.	String
`description`	Describes the version of the catalog.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains metadata of the specified catalog version.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 status

Get the status of a previous request to create or update the interaction model catalog specified by the catalog ID.

Request

To get the creation status, you make a GET request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/updateRequest/{updateRequestId}
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	Identifies the catalog.	String	Yes
`updateRequestId`	Path	Identifies the previous request to create or update the catalog. Valid value: `~current`.	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 status of the specified catalog modification. 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

{
    "lastUpdateRequest": {
        "status": "SUCCEEDED",
        "version": "2"
    }
}

Response body properties

Property	Description	Type
`lastUpdateRequest`	Information related to the last request to create or update the catalog specified by the catalog ID.	Object
`lastUpdateRequest.status`	Status of the create or update request. Valid values: `FAILED`, `IN_PROGRESS`, `SUCCEEDED`.	String
`lastUpdateRequest.version`	Version of the interaction model catalog.	String
`lastUpdateRequest.errors`	(Optional) List of errors that occurred for the request.	Array of objects
`lastUpdateRequest.errors[].code`	HTTP status code that reflects the error.	String
`lastUpdateRequest.errors[].message`	Human readable error message.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains status of the catalog creation.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 all catalogs associated with the specified vendor.

Request

To get the list of catalogs, you make a GET request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/api/custom/interactionModel/catalogs/?vendorId={vendorId}&maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}
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`	Path	Identifies the vendor.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–250. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response.	String	No
`sortDirection`	Query	Set the sorting direction of the results as ascending or descending order. Valid values: `asc`, `desc`. Default: `desc`.	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

{
    "catalogs": [{
            "catalogId": "catalog.id.1",
            "description": "Contains recipe ingredients",
            "name": "Cookie ingredients",
            "_links": {
                "next": {
                    "href": "next_href"
                },
                "self": {
                    "href": "current_href"
                }
            }
        },
        {
            "catalogId": "catalog.id.2",
            "description": "Contains recipe ingredients",
            "name": "Taco ingredients",
            "_links": {
                "next": {
                    "href": "next_href"
                },
                "self": {
                    "href": "current_href"
                }
            }
        }
    ],
    "isTruncated": false,
    "totalCount": 2,
    "_links": {
        "next": {
            "href": "next_href"
        },
        "self": {
            "href": "current_href"
        }
    }
}

Response body properties

Property	Description	Type
`catalogs`	List of catalogs owned by the specified vendor.	Array of objects
`catalogs[].catalogId`	Identifies the catalog.	String
`catalogs[].name`	Name of the catalog.	String
`catalogs[].description`	Describes the catalog.	String
`catalogs[]._links`	Links for catalog navigation. Defined in JSON Hypertext Application Language specification.	_links object
`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
`totalCount`	Total number of catalog versions.	Integer
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of catalogs owned by the specified vendor ID.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 catalog versions

Get all versions of the specified catalog.

Request

To get the list of catalogs, you make a GET request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions?maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}&sortField={sortField}
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	Identifies the catalog.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–50. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response.	String	No
`sortDirection`	Query	Set the sorting direction of the results as ascending or descending order. Valid values: `asc`, `desc`. Default: `desc`.	String	No
`sortField`	Query	Sort the result on the specified field in alphabetical order. Valid values: `version`, `description`, `creationTime`.	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 versions of 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

{
    "catalogVersions": [{
            "version": "catalog.version.1",
            "description": "Version 1 contains cookie recipe ingredients",
            "creationTime": "2019-01-06T05:26:02.430Z",
            "_links": {
                "next": {
                    "href": "next_href"
                },
                "self": {
                    "href": "current_href"
                }
            }
        },
        {
            "version": "catalog.version.2",
            "description": "Version 2 modifies the cookie recipe ingredients",
            "creationTime": "2019-02-16T05:26:02.430Z",
            "_links": {
                "next": {
                    "href": "next_href"
                },
                "self": {
                    "href": "current_href"
                }
            }
        }
    ],
    "isTruncated": false,
    "totalCount": 2,
    "_links": {
        "next": {
            "href": "next_href"
        },
        "self": {
            "href": "current_href"
        }
    }
}

Response body properties

Property	Description	Type
`catalogVersions`	List of versions for the specified catalog in `sortDirection` order.	Array of objects
`catalogVersions[].version`	Version number of the catalog.	String
`catalogVersions[].description`	Describes the version of the catalog.	String
`catalogVersions[].creationTime`	Creation date and time of the catalog version. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`catalogs[]._links`	Links for catalog navigation. Defined in JSON Hypertext Application Language specification.	_links object
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object
`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
`totalCount`	Total number of catalog versions.	Integer

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of versions owned of 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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

Update catalog definition

Update the interaction model catalog definition for the specified catalog.

Request

To update a catalog, you make a POST request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/update
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	Identifies the catalog.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "catalog": {
        "name": "Butter cookie ingredients",
        "description": "Updated description."
    }
}

Request body properties

Property	Description	Type	Required
`catalog`	Information about the catalog.	Object	Yes
`catalog.name`	Name of the catalog.	String	Yes
`catalog.description`	Describes the catalog. Valid value: Up to 255 characters.	String	No

Response

A successful response returns HTTP 204 No Content to indicate that the Alexa service updated the catalog definition. 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
`204 No Content`	Successful update of the specified catalog definition.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

Update catalog version definition

Update the interaction model catalog version definition for the specified catalog and version.

Request

To update the version definition, you make a POST request to the interactionModel/catalogs resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}/update
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	Identifies the catalog.	String	Yes
`version`	Path	Identifies the catalog version to update.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "description": "Version 2 modifies the butter cookie recipe ingredients"
}

Request body properties

Property	Description	Type	Required
`description`	Describes this version of the catalog. Valid value: Up to 255 characters.	String	No

Response

A successful response returns HTTP 204 No Content to indicate that the catalog version definition was updated. 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
`204 No Content`	Successful update of the specified catalog version definition.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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?

Provide feedback

Last updated: Aug 01, 2024