Reference-Based Catalog Management

With the Catalog URL Reference API, you can create custom slot types with a URL reference to an existing content catalog. You can create a catalog, using the Catalog Content Upload API, and reference the catalog to a slot type. Alexa can then pull catalog values from the URL.

For example, if you build a recipe skill, you can use this API to pull a list of chef names from a catalog database, instead of having to enter each individual name by using SMAPI and Skill Builder. When you use SMAPI and Skill Builder, you must manually keep both data sources in sync, which requires extra time and effort. For an example, see Catalog Entities Demo.

Process to use the Reference-Based Catalog Management API

The following steps describe the high-level process of 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.

Create catalog

Creates the definition of a catalog.

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

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.

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

Creates a versions of a catalog.

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 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.

Response body structure

The following example shows the 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 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 an 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

Updates the status of the catalog. The values can be, in progress, failed, or succeeded.

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

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 is an 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 If this is a failure, error provides an error code and message Response body String

List catalog versions

List versions of a catalog.

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

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

Response parameters

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

List catalogs

Gets a list of a catalog.

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

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

Response parameters

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

Get catalog version

Gets the catalog version.

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

Errors

An unsuccessful request returns one of the following errors.

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 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 an 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

Gets the definition of a catalog.

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

Errors

An unsuccessful request returns one of the following errors.

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 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 an 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

Gets catalog values.

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

Errors

An unsuccessful request returns one of the following errors.

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

Response parameters

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

Update catalog definition

Updates the definition of a catalog.

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

Update version information

Updates the definition of a catalog version.

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 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.

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

Delete catalog version

Deletes a version of a catalog.

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 a HTTP 400 validation error.

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

Delete catalog

Delete a catalog.

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

The following example shows an HTTP 400 validation error.

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