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
  • Process to use the Reference-Based Catalog Management API
• Create catalog
  • Request
  • Response
• Create catalog version
  • Request
  • Response
• Get catalog update status
  • Request
  • Response
• List catalogs
  • Request
  • Response
• List catalog versions
  • Request
  • Response
• Get catalog
  • Request
  • Response
• Get catalog version
  • Request
  • Response
• Get catalog values
  • Request
  • Response
• Update catalog
  • Request
  • Response
• Update version information
  • Request
  • Response
• Delete catalog
  • Request
  • Response
• Delete catalog version
  • Request
  • Response

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.

1. Create a definition for your catalog.
2. 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.
3. Track the status of the catalog version creation. The possible values are in progress, failed, or succeeded.
   Tip: Use catalogId and version as a reference in a slot type while you create a skill.
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

Response

A successful request returns HTTP 200.

Response body structure

{
  "catalogId":"string"
}

Response body fields

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

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

Response

A successful request returns HTTP 202.

Response body fields

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

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

Response

A successful request returns HTTP 200.

Response body structure

{
  "lastUpdateRequest": {
       "status": "string",
       "version": "string",
       "error":  [
           {
              "code": "string",
              "message":  "string"
           }
       ]
   }
}

Response body fields

Errors

An unsuccessful request returns one of the following errors.

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

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

Errors

An unsuccessful request returns one of the following errors.

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

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

Errors

An unsuccessful request returns one of the following errors.

Get catalog

Gets the definition of a catalog.

Request

HTTP method and URL path

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}

Request parameters

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

Errors

An unsuccessful request returns one of the following errors.

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

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

Errors

An unsuccessful request returns one of the following errors.

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

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

Errors

An unsuccessful request returns one of the following errors.

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

Response

A successful request returns HTTP 204.

Errors

An unsuccessful request returns one of the following errors.

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

Response

A successful request returns HTTP 204.

Errors

An unsuccessful request returns one of the following errors.

Delete catalog

Deletes a catalog.

Request

HTTP method and URL path

DELETE /v1/skills/api/custom/interactionModel/catalogs/{catalogId}

Request parameters

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

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

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