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
- Create catalog
- Create catalog version data
- Catalog update status
- List catalog versions
- List catalogs
- Get catalog version
- Get catalog definition
- Catalog values
- Update catalog definition
- Update version information
- Delete catalog version
- Delete catalog
Use Catalog URL Reference API
Get started
- Create a definition for your catalog.
- Create a catalog version using the catalog id from step 1.
- Track the status of the catalog version creation. The possible values are in progress, failed, or succeeded.
catalogId
and version
as a reference in a slot type while creating a skill.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. |