Reference-based catalog management

The Reference-based catalog management API allows you to create custom slot types with a URL reference to an existing catalog. You can create a catalog, and reference it to a slot type for Alexa to pull values from the URL. Using this feature, developers can now create slot types to ingest values from an external data source with a URL reference to the catalog. For example, a recipe skill developer will now be able to pull a list of ingredients from their existing catalog instead of having to enter each individual ingredients and keep both data sources in sync.

For example, if you try to create a recipe skill you can use this capability to pull a list of chef names from the database, instead of having to enter each individual name using SMAPI and Skill Builder which requires you to manually keep both data sources in sync. For an example, see Catalog Entities Demo.

Use the Reference-based catalog management API

Get started

  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 below.
    Code Sample
    Code sample

  5. Use catalog management API’s to perform end to end management operations for your catalog.

    The table below gives an overview of list of actions that you can perform to manage your catalogs.

Action Success criteria API CLI
Create a catalog definition. A catalog is created with a catalog ID. Create Catalog Definition create-model -catalog-definition
Create a catalog version with a URL to your existing catalog. A catalog version is created with values ingested from the URL. Create Catalog Version create- catalog-version
Track the status of catalog creation. Developers can track the status of the catalog creation. Get Catalog Update Status get -catalog -update-status
View the definition of a catalog. Developers can view catalog name, description, date created, number of versions in a catalog. Get Catalog Definition get-model-catalog
View the definition of a catalog version. Developers can view catalogid, version and description. Get Catalog Version Definition get -catalog -version
Update the data (name and description) of a catalog. Developers can update name and description of a catalog. Update Catalog Definition update -catalog
Update the data (description) of a catalog version. Developers can update description of a catalog version. Update Catalog Version Definition update -catalog-version
Read the values of a catalog version. Developers can view the catalog version. Get Catalog Versions get -catalog-versions
List all of my catalogs. Developers can see a list of all existing catalogs. List Catalogs list -catalogs
List all of my catalog versions. Developers can see a list of catalog versions for a specific catalog ID. List Catalog Versions list -catalog-versions
Delete a specific catalog. Developers can delete a catalog with all versions deleted. Delete Catalog delete -catalog
Delete a specific catalog version. Developers can delete a specific version of a catalog. Delete Catalog Version delete -catalog-version

Create catalog

This creates the definition of a catalog. Use this API to create a catalog with a catalog ID.

Request

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

Errors

An unsuccessful request returns one of the following errors in the table below:

Response body structure

The example below is for validation error HTTP 400.

{
  "error":  [
     {
        "code": "string",
        "message":  "string"
     }
  ]
}
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 a internal server error.
HTTP 503 The service is unavailable.

Response parameters

Parameter Required Description Location Type
catalogId Yes A unique identifier to identify a catalog generated by the catalog service. Response body String

Create catalog version data

This creates a version of a catalog. Use this call to create a catalog version with values ingested from the URL.

Request

POST /skills/api/custom/interactionModel/catalogs/{catalogId}/versions

Request body structure

Example:

{
      "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 url reference to the catalog to be ingested. Request body String

Response

A successful request returns HTTP 202.

Errors

An unsuccessful request returns one of the following errors in the table below:

Response body structure

The example below is for validation error HTTP 400.

{
  "error":  [
     {
        "code": "string",
        "message":  "string"
     }
  ]
}
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 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 is a internal server error.
HTTP 503 The service is unavailable.

Response parameters

Parameter Required Description Location Type
location No The location of the catalog status to track. Response header String

Catalog update status

Use this call to update the status of a catalog. The values can be in progress, failed, or succeeded. You can track the status of the catalog creation - In progress, failed and succeeded with this command.

Request

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

Errors

An unsuccessful request returns one of the following errors in the table below:

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 is a internal server error.
HTTP 503 The service is unavailable.

Response parameters

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 In case of FAILURE, error provides an error code and message Response body String

List catalog versions

Use this call to list versions of a catalog. Use this command to see a list of catalog versions for a specific catalog ID.

Request

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 Allows 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 example below 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"
              }
          }
       }
   ]
}

Errors

An unsuccessful request returns one of the following errors in the table below:

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 is a internal server error.
HTTP 503 The service is unavailable.

Response parameters

Parameter Required Description Location Type
nextToken No Allows you to query the next page of results. Response body String
isTruncated Yes Will return 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

List catalogs

Use this call to get a list of catalog. You can see a list of all existing catalogs with this call.

Request

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 Allows 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 example below 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"
              }
          }
       }
   ]
}

Errors

An unsuccessful request returns one of the following errors in the table below:

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 is a internal server error.
HTTP 503 The service is unavailable.

Response parameters

Parameter Required Description Location Type
nextToken No Allows you to query the next page of results. Response body String
isTruncated Yes Will return 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

Get catalog version

Use this command to get the catalog version.

Request

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 example below shows the HTTP 200 response.

{
       "source": {
          "type": "string",
          "url": "string"
       },
       "version": "string",
       "description": "string",
}

Errors

An unsuccessful request returns one of the following errors in the table below:

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 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 is a internal server error.
HTTP 503 The service is unavailable.

Response parameters

Parameter Required Description Location Type
type No The type of the catalog. Response body String
url No The url reference to the catalog to be ingested. 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

Get catalog definition

Use this call to get the definition of a catalog. Use this command to view catalog name, description, date created, number of versions in a catalog.

Request

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 example below shows the HTTP 200 response.

{
       "catalog": {
          "name": "string",
          "description": "string"      
       },
       "createTime": "string",
       "totalVersions": "string"
}

Errors

An unsuccessful request returns one of the following errors in the table below:

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 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 is a internal server error.
HTTP 503 The service is unavailable.

Response parameters

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

Catalog values

Use this call to get catalog values.

Request

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 Allows you to query the next page of results. Request path (optional) String

Response

A successful request returns HTTP 200. The example below 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"
        }
   }
}

Errors

An unsuccessful request returns one of the following errors in the table below:

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 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 is a internal server error.
HTTP 503 The service is unavailable.

Response parameters

Parameter Required Description Location Type
nextToken No Allows you to query the next page of results. Response body String
isTruncated No This command will return 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

Update catalog definition

Use this call to update the definition of a catalog. Use this call to update name and description of a catalog.

Request

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 in the table below:

Code Description
HTTP 400 There is 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 is a internal server error.
HTTP 503 The service is unavailable.

Update version information

Use this call to update the definition of a catalog version.

Request

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 identifier to identify a catalog generated by the catalog service. 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.

Code Description
HTTP 400 There is 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 is a internal server error.
HTTP 503 The service is unavailable.

Delete catalog version

Use this call to delete a version of a catalog.

Request

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 in the table below: The example below shows a HTTP 400 validation error.

{
  "error":  [
     {
        "code": "string",
        "message":  "string"
     }
  ]
}
Code Description
HTTP 400 There is 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 is a internal server error.
HTTP 503 The service is unavailable.

Delete catalog

Use this call to delete a catalog.

Request

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 in the table below: The example below shows a HTTP 400 validation error.

{
  "error":  [
     {
        "code": "string",
        "message":  "string"
     }
  ]
}
Code Description
HTTP 400 There is 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 is a internal server error.
HTTP 503 The service is unavailable.
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment