Reference-Based Catalog Management
With the Reference-Based Catalog Management API, you can create a custom slot type that references an external data source to get the slot type values. This API allows you to create and maintain a catalog of slot type values independent of your Alexa skill.
As part of using the API, you provide the URL for your external data source, and the API returns a catalog identifier. In your custom slot type, you specify the catalog identifier so that the skill can get the slot type values from the external data source. For example, if you're building a recipe skill, instead of entering ingredients as slot type values in your Alexa skill, you specify the catalog identifier for your external data source that has the list of ingredients.
You can also create jobs to automatically update your reference-based catalogs. For information about creating and managing such automatic-update jobs, see Manage Update Jobs.
- Overview
- Create catalog
- Create catalog version
- Get catalog update status
- List catalogs
- List catalog versions
- Get catalog
- Get catalog version
- Get catalog values
- Update catalog
- Update version information
- Delete catalog
- Delete catalog version
Overview
The following table contains the SMAPI actions and corresponding ASK CLI commands that you can use to manage your catalogs.
Process to use the Reference-Based Catalog Management API
Use the following process to start using the Reference-Based Catalog Management API.
- Create a definition for your catalog.
- Create a catalog version using the catalog id from step 1.
Note: The URL should be present in an HTTPS location and the catalogs should be in the JSON format. You can even include synonyms in your catalog. For a sample format of a catalog, see Catalog Entities Demo.
- Track the status of the catalog version creation. The possible values are in progress, failed, or succeeded.
Tip: Use
catalogId
andversion
as a reference in a slot type while you create a skill. - Use the catalog ID and version in the interaction model as shown in the following example.
Before
{
"languageModel": {
"types": [
{
"name": "string",
"samples": [
"string"
],
"values": [
{
"id": "string",
"name": {
"value": "string",
"synonyms": [
"string"
]
}
}
]
}
]
}
}
After
{
"languageModel": {
"types": [
{
"name": "string",
"samples": [
"string"
],
"values": [
{
"id": "string",
"name": {
"value": "string",
"synonyms": [
"string"
]
}
}
]
},
{
"name": "string",
"valueSupplier": {
"type": "CatalogValueSupplier",
"valueCatalog": {
"id": "string",
"version": "string"
}
}
}
]
}
}
Create catalog
Creates the definition of a catalog.
Request
HTTP method and URL path
POST /v1/skills/api/custom/interactionModel/catalogs/
Request body structure
{
"vendorId": "string",
"catalog": {
"name": "string",
"description": "string"
}
}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
description |
No | The catalog description with a 255 character maximum. | Request body (optional) | String |
name |
Yes | The catalog name. | Request body | String |
vendorId |
Yes | The vendor ID of the requester. | Request body | String |
Response
A successful request returns HTTP 200
.
Response body structure
{
"catalogId":"string"
}
Response body fields
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Response body | String |
Errors
An unsuccessful request returns one of the following errors.
Response body structure
The following example is for validation error HTTP 400
.
{
"error": [
{
"code": "string",
"message": "string"
}
]
}
Status Code | Description |
---|---|
HTTP 400 |
There is a validation error. |
HTTP 401 |
The authorization token is invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There is an internal server error. |
HTTP 503 |
The service is unavailable. |
Create catalog version
Creates a version of a catalog.
Request
HTTP method and URL path
POST /skills/api/custom/interactionModel/catalogs/{catalogId}/versions
Request body structure
{
"source": {
"type": "URL",
"url": "string"
},
"description": "string"
}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
source |
Yes | The source of the input data to form the catalog. | Request body | String |
type |
Yes | The type of the catalog. | Request body | String |
url |
Yes | The catalog's URL. | Request body | String |
Response
A successful request returns HTTP 202
.
Response body fields
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
location |
No | The location of the catalog status to track. | Response header | String |
Errors
An unsuccessful request returns one of the following errors.
Response body structure
The following example is for validation error HTTP 400
.
{
"error": [
{
"code": "string",
"message": "string"
}
]
}
Status code | Description |
---|---|
HTTP 400 |
There's a validation error. |
HTTP 401 |
The authorization token is invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
Get catalog update status
Gets the status of a previous request to create or update a catalog. The status can be in progress, failed, or succeeded.
Request
HTTP method and URL path
GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/updateRequest/{updateRequestId}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
updateRequestId |
Yes | A unique identifier to identify a process to attempt to create a new version. | Request path | String |
Response
A successful request returns HTTP 200
.
Response body structure
{
"lastUpdateRequest": {
"status": "string",
"version": "string",
"error": [
{
"code": "string",
"message": "string"
}
]
}
}
Response body fields
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
status |
Yes | The status of the catalog. The values can be in progress, failed, or succeeded. | Response body | String |
version |
No | The version ID of the entity returned. | Response body | String |
error |
No | If this is a failure, error provides an error code and message. | Response body | String |
Errors
An unsuccessful request returns one of the following errors.
Status code | Description |
---|---|
HTTP 401 |
The authorization token is invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
List catalogs
Gets a list of catalogs.
Request
HTTP method and URL path
GET /v1/skills/api/custom/interactionModel/catalogs/?vendorid={vendorid}&maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
vendorId |
Yes | The vendor ID of the requester. | Request path | String |
maxResults |
No | The number of versions returned. | Request path (optional) | String |
nextToken |
No | Enables you to query the next page of results. | Request path (optional) | String |
sortDirection |
No | The sort order. The default sort order is descending. The accepted values are asc for ascending and desc for descending. Values are case-sensitive. |
Request path (optional) | String |
Response
A successful request returns HTTP 200
. The following example shows the HTTP 200
response.
{
"isTruncated": boolean,
"nextToken": "string",
"totalCount": integer,
"_links": {
"next": {
"href": "next_href"
},
"self": {
"href": "current_href"
}
},
"catalogs": [
{
"catalogId": "string",
"description": "string",
"name": "string",
"_links": {
"next": {
"href": "next_href"
},
"self": {
"href": "current_href"
}
}
}
]
}
Response body fields
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
nextToken |
No | Enables you to query the next page of results. | Response body | String |
isTruncated |
Yes | Returns false if there are no more results to return. | Response body | String |
description |
No | The version description with a maximum of 255 characters. | Response body | String |
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Response body | String |
totalCount |
Yes | The total number of catalog versions. | Response body | String |
_links |
No | Links for API navigation. | Response body | String |
Errors
An unsuccessful request returns one of the following errors.
Status code | Description |
---|---|
HTTP 401 |
The authorization token is invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
List catalog versions
Gets a list of versions of a catalog.
Request
HTTP method and URL path
GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions?maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}&sortField={sortField}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
maxResults |
No | The number of versions returned. | Request path (optional) | String |
nextToken |
No | Enables you to query the next page of results. | Request path (optional) | String |
sortDirection |
No | The sort order. The default sort order is descending. The accepted values are asc for ascending and desc for descending. Values are case-sensitive. |
Request path (optional) | String |
Response
A successful request returns HTTP 200
. The following example shows the HTTP 200
response.
{
"isTruncated": boolean,
"nextToken": "string",
"totalCount": integer,
"_links": {
"next": {
"href": "next_href"
},
"self": {
"href": "current_href"
}
},
"catalogVersions": [
{
"version": "string",
"description": "string",
"creationTime": "string",
"_links": {
"next": {
"href": "next_href"
},
"self": {
"href": "current_href"
}
}
}
]
}
Response body fields
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
nextToken |
No | Enables you to query the next page of results. | Response body | String |
isTruncated |
Yes | Returns false if there are no more results to return. | Response body | String |
description |
No | The version description with a maximum of 255 characters. | Response body | String |
totalCount |
Yes | The total number of catalog versions. | Response body | String |
_links |
No | Links for API navigation. | Response body | String |
Errors
An unsuccessful request returns one of the following errors.
Status code | Description |
---|---|
HTTP 401 |
The authorization token is either invalid, expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
Get catalog
Gets the definition of a catalog.
Request
HTTP method and URL path
GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
Response
A successful request returns HTTP 200
. The following example shows the HTTP 200
response.
{
"catalog": {
"name": "string",
"description": "string"
},
"createTime": "string",
"totalVersions": "string"
}
Response body fields
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
name |
No | The name of the catalog. | Response body | String |
description |
No | The catalog description with a maximum of 255 characters. | Response body | String |
Errors
An unsuccessful request returns one of the following errors.
Status code | Description |
---|---|
HTTP 400 |
There's a validation error. |
HTTP 401 |
The authorization token is invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
Get catalog version
Gets the catalog version.
Request
HTTP method and URL path
GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
version |
Yes | Specifies a version of the catalog identified by the catalogId . |
Request path | String |
Response
A successful request returns HTTP 200
. The following example shows the HTTP 200
response.
{
"source": {
"type": "string",
"url": "string"
},
"version": "string",
"description": "string",
}
Response body fields
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
type |
No | The type of the catalog. | Response body | String |
url |
No | The catalog's URL. | Response body | String |
description |
No | The version description with a maximum of 255 characters. | Response body | String |
version |
Yes | Specifies a version of the catalog identified by the catalogId . |
Response body | String |
Errors
An unsuccessful request returns one of the following errors.
Status code | Description |
---|---|
HTTP 400 |
There's a validation error. |
HTTP 401 |
The authorization token is invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
Get catalog values
Gets catalog values.
Request
HTTP method and URL path
GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}/values?nextToken={nextToken}&maxResults={maxResults}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
version |
Yes | Specifies a version of the catalog identified by the catalogId . |
Request path | String |
maxResults |
No | The number of versions returned. | Request path (optional) | String |
nextToken |
No | Enables you to query the next page of results. | Request path (optional) | String |
Response
A successful request returns HTTP 200
. The following example shows the HTTP 200
response.
{
"values":[
{
"id": "string",
"name": {
"value": "string",
"synonyms": [
"string"
]
}
}
],
"isTruncated": boolean,
"nextToken": "string",
"totalCount": integer,
"_links": {
"next": {
"href": "next_href"
},
"self": {
"href": "current_href"
}
}
}
Response body fields
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
nextToken |
No | Enables you to query the next page of results. | Response body | String |
isTruncated |
No | This command returns false if there are no more results to return. | Response body | String |
totalCount |
Yes | The total number of catalog versions. | Response body | String |
_links |
No | Links for API navigation. | Response body | String |
Errors
An unsuccessful request returns one of the following errors.
Status code | Description |
---|---|
HTTP 400 |
There's a validation error. |
HTTP 401 |
The authorization token is invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
Update catalog
Updates the definition of a catalog.
Request
HTTP method and URL path
POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/update
Request body structure
{
"name": "string",
"description": "string"
}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
name |
Yes (Include either name or description |
The catalog name. | Request body | String |
description |
Yes (Include either name or description ). |
The catalog definition description with a 255 character maximum. | Request body (optional) | String |
Response
A successful request returns HTTP 204
.
Errors
An unsuccessful request returns one of the following errors.
Status code | Description |
---|---|
HTTP 400 |
There's a validation error. |
HTTP 401 |
The authorization token is either invalid, expired, or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
Update version information
Updates the definition of a catalog version.
Request
HTTP method and URL path
POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}/update
Request body structure
{
"description": "string"
}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique id for a specific catalog. | Request body (optional) | String |
version |
Yes | Specifies a version of the catalog identified by the catalogId . |
Request path | String |
description |
No | The catalog description with a 255 character maximum. | Request body (optional) | String |
Response
A successful request returns HTTP 204
.
Errors
An unsuccessful request returns one of the following errors.
Status code | Description |
---|---|
HTTP 400 |
There's a validation error. |
HTTP 401 |
The authorization token is either invalid, expired, or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
Delete catalog
Deletes a catalog.
Request
HTTP method and URL path
DELETE /v1/skills/api/custom/interactionModel/catalogs/{catalogId}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
Response
A successful request returns HTTP 204
.
Errors
An unsuccessful request returns one of the following errors. The following example shows an HTTP 400
validation error.
{
"error": [
{
"code": "string",
"message": "string"
}
]
}
Status code | Description |
---|---|
HTTP 400 |
There's a validation error. |
HTTP 401 |
The authorization token is either invalid, expired, or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |
Delete catalog version
Deletes a version of a catalog.
Request
HTTP method and URL path
DELETE /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
catalogId |
Yes | A unique identifier to identify a catalog generated by the catalog service. | Request path | String |
version |
Yes | Specifies a version of the catalog identified by the catalogId . |
Request path | String |
Response
A successful request returns HTTP 204
.
Errors
An unsuccessful request returns one of the following errors. The following example shows an HTTP 400
validation error.
{
"error": [
{
"code": "string",
"message": "string"
}
]
}
Status code | Description |
---|---|
HTTP 400 |
There's a validation error. |
HTTP 401 |
The authorization token is either invalid, expired, or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
Not found. |
HTTP 429 |
You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId , and CustomerId . |
HTTP 500 |
There's an internal server error. |
HTTP 503 |
The service is unavailable. |