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

The following table contains the SMAPI actions and corresponding ASK CLI commands that you can use to manage your catalogs.

SMAPI Action ASK CLI Command Description
Create catalog create-interaction-model-catalog Creates the definition of a catalog.
Create catalog version create-interaction-model-catalog-version Creates a version of a catalog.
Get catalog update status get-interaction-model-catalog-update-status Gets the status of a previous request to create or update a catalog.
List catalogs list-interaction-model-catalogs Gets a list of catalogs.
List catalog versions list-interaction-model-catalog-versions Gets a list of versions of a catalog.
Get catalog get-interaction-model-catalog-definition Gets the definition of a catalog.
Get catalog version get-interaction-model-catalog-version Gets a specific version of a catalog.
Get catalog values get-interaction-model-catalog-values Gets catalog values.
Update catalog update-interaction-model-catalog Updates the definition of a catalog.
Update version information update-interaction-model-catalog-version Updates the description of a catalog version.
Delete catalog delete-interaction-model-catalog Deletes a catalog.
Delete catalog version delete-interaction-model-catalog-version Deletes a version of a catalog.

Process to use the Reference-Based Catalog Management API

Use the following process to start using the Reference-Based Catalog Management API.

  1. Create a definition for your catalog.
  2. Create a catalog version using the catalog id from step 1.
  3. Track the status of the catalog version creation. The possible values are in progress, failed, or succeeded.
  4. 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.