Catalog URL Reference

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

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 Catalog URL Reference 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.

Create catalog

This creates the definition of a catalog.

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.

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.

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.

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.

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.

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.

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