Slot Type API
In the voice interaction model for your skill, you can use and extend built-in slot types. For a list of built-in slot types, see the Slot Type Reference. For more information about creating an interaction model, see Create the Interaction Model for Your Skill.
To create your own slot type for use in any skill on your developer account, use the Slot Type API. The slot type created using the Slot Type API supports interaction model catalogs and entity resolution synonyms and IDs. In the interaction model for your skill, you can extend the slot type in the same way as a built-in slot type.
For example, if you build the skills Southern Recipes and Northwest Foods, you can use the Slot Type API to create a slot type for ingredients, and use the ingredients slot type in both skills. If one of the skills requires additional ingredients, you can extend the ingredients slot type in the skill. For example, if Southern Recipes requires additional ingredients, extend the ingredients slot type in the Southern Recipes skill.
- API endpoint and header
- Understand slot types, slot type versions, and slot type definitions
- Use the Slot Type API
- CreateSlotType
- GetSlotType
- UpdateSlotType
- ListSlotTypes
- DeleteSlotType
- CreateSlotTypeVersion
- GetSlotTypeVersion
- GetSlotTypeBuildStatus
- UpdateSlotTypeVersion
- ListSlotTypeVersions
- DeleteSlotTypeVersion
API endpoint and header
The API's endpoint is https://api.amazonalexa.com
. Each API request must have an Authorization
header whose value should be the access token retrieved from Login with Amazon.
Understand slot types, slot type versions, and slot type definitions
A slot type is an object that represents words or phrases that are part of the utterance that the user speaks. When you use the Slot Type API to create a slot type, the API returns a slotTypeId
and version. You can create up to 100 slot types in your developer account, and a maximum of 100 versions for each slot type.
You cannot change the slot type values in a version. To specify different slot type values, you must create a new version. The Slot Type API defines each version independent of other versions, and you can delete versions that you are not using. To see the schema for a slot type, see CreateSlotType.
You do not need a skill to create a slot type. However, you need a skill to use the slot type. To use the slot type in the interaction model for your skill, refer to the slot type by using the slotTypeId
and version. In your interaction model, you can also extend the slot type in the same way that you can extend a built-in slot.
A slot type definition represents the values, synonyms, and IDs for a slot type version. When you add a new slot type version, you must create a slot type definition. To create the slot type definition, you can use values that you specify, or you can refer to a list of values stored elsewhere. For more details about referring to values stored elsewhere, see Interaction Model Catalog Management REST API Reference. For details about the schema for slot type definition, see CreateSlotTypeVersion.
Use the Slot Type API
Do the following to start using the Slot Type API.
- Create a slot type.
- Create a slot type version, during which you also create the slot type definition.
- Track the slot type build status.
- Open the skill where you want to use the slot.
- In the interaction model for your skill, refer to the slot by
slotTypeId
and version. - Optionally, in your interaction model, extend the slot by adding slot type values inline.
CreateSlotType
Create a slot type. A slot type is a container that holds the versions for a slot type.
Request
HTTP method and URI path
POST /v1/skills/api/custom/interactionModel/slotTypes/
Request body structure
{
"vendorId": "string",
"slotType": {
"name": "string",
"description": "string"
}
}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
vendorId |
Yes | The unique vendor ID. | Body | String |
name |
Yes | The name representation of the slot type, which has a maximum of 255 characters. | Body | String |
description |
No | The slot description, which has a maximum of 255 characters. | Body | String |
Response
A successful response returns HTTP 200
.
Response body structure
{
"slotType": {
"id": "string"
}
}
Response body fields
Field | Description | Location | Type |
---|---|---|---|
id |
The id used to identify a slot type. | Body | 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 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. |
GetSlotType
Return a slot type for the slotTypeId
that you provide.
Request
HTTP method and URI path
GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | String |
Response
A successful response returns HTTP 200
.
Response body structure
{
"slotType": {
"name": "string",
"description": "string"
}
}
Response body fields
Field | Description | Location | Type |
---|---|---|---|
name |
The name representation of the slot type, which has a maximum of 255 characters. | Body | String |
description |
The slot description which has a maximum of 255 characters. | Body | 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 |
The resource you requested is 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. |
UpdateSlotType
Update the slot type description. If you don't provide a description, the operation deletes the existing description.
Request
HTTP method and URI path
POST /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/update
Request body structure
{
"slotType": {
"description": "string"
}
}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | String |
description |
No | The slot description, which has a maximum of 255 characters. | Body | 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 invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
The resource you requested is 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. |
ListSlotTypes
Lists all of the slots types created by your developer account.
Request
HTTP method and URI path
GET /v1/skills/api/custom/interactionModel/slotTypes?vendorId={vendorId}&maxResults={num}&nextToken={nextToken}&sortDirection={sortDirection}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
vendorId |
Yes | The unique vendor ID. | Body | String |
maxResults |
No | The maximum number of versions returned. | Path | String |
nextToken |
No | Enables the user to query the next page of results. | Path | 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. |
Path | String |
Response
A successful response returns HTTP 200
.
Response body structure
{
"nextToken": "string",
"_links": {
"href": "next_href"
},
"self": {
"href": "current_href"
}
},
"slotTypes": [
{
"id": "string",
"name": "string",
"description": "string",
"_links": {
"self": {
"href": "current_href"
}
}
}
]
}
Response body fields
Field | Description | Location | Type |
---|---|---|---|
nextToken |
Enables the user to query the next page of results. | Body | String |
_links |
Hypertext Application Language links to navigate through resources. | Body | String |
id |
The unique slot type id. | Body | String |
name |
The name representation of the slot type, which has a maximum of 255 characters. | Body | String |
description |
The slot description, which has a maximum of 255 characters. | Body | 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 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. |
DeleteSlotType
Delete a slot type.
Request
HTTP method and URI path
DELETE /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | 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 invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
The resource you requested is 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. |
CreateSlotTypeVersion
Create a new version for the slot type. Each slot type version belongs to a slot type. The slot type version includes a definition that either specifies the slot type values, or refers to an external data source that has the slot type values.
Request
HTTP method and URI path
POST /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions
Request body structure
The following shows the request body structure where the definition
provides slot type values and associated synonyms.
{
"slotType": {
"definition":{
"valueSupplier": {
"type": "InlineValueSupplier",
"values": [
{
"id": "seattle",
"name": {
"value": "seattle",
"synonyms": [
"sea"
]
}
}
]
}
},
"description": "string"
}
}
The following shows the request body structure where the definition
refers to a catalogId
that references the slot type values. For more details, see Interaction Model Catalog Management REST API Reference.
{
"slotType": {
"definition":{
"valueSupplier": {
"type": "CatalogValueSupplier",
"valueCatalog": {
"catalogId": "amzn1.ask.interactionModel.catalog.123",
"version": "string"
}
}
},
"description": "string"
}
}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | String |
definition |
Yes | A JSON object containing the definition of the slot type values. | Body | String |
description |
No | The description of the slot type version, which has a maximum of 255 characters. | Body | String |
Response
A successful request returns HTTP 202
.
Response body fields
Field | Description | Location | Type |
---|---|---|---|
location |
Header that shows the updateRequestId to pass to GetSlotTypeBuildStatus. |
Header | 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 |
The resource you requested is 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. |
GetSlotTypeVersion
Return the slot type data for the slotTypeId
and version that you specify.
Request
HTTP method and URI path
GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/{version}
GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/~current
GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/~latest
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | String |
version |
Yes | The specific version of the type identified by the slotTypeId . |
Path | String |
Response
A successful request returns HTTP 200
.
Response body structure
{
"slotType": {
"id": "string",
"definition": {...},
"version": "string",
"description": "string"
}
}
Response body fields
Field | Description | Location | Type |
---|---|---|---|
id |
The slot type Id. | Body | String |
definition |
Returns a JSON object containing the slot type version definition including values. | Body | String |
description |
The version description. | Body | String |
version |
The version for a slot type. | Body | 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 |
The resource you requested is 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. |
GetSlotTypeBuildStatus
Return the build status of the slotTypeId
that you provide. The build status can be succeeded
, in progress
, or failed
.
Request
HTTP method and URI path
GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/updateRequest/{updateRequestId}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | String |
updateRequestId |
Yes | Identifier from the location header in the CreateSlotTypeVersion response. |
Path | String |
Response
A successful request returns HTTP 200
.
Response body structure
{
"updateRequest": {
"status": "string",
"version": "string",
}
}
Response body fields
Field | Description | Location | Type |
---|---|---|---|
status |
Status of the slot type. The potential values are succeeded, in progress, or failed. | Body | String |
version |
Version id of the entity returned. | Body | 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 |
The resource you requested is 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. |
UpdateSlotTypeVersion
Update the description of a slot type version. If you don't provide a description, the operation deletes the existing description.
Request
HTTP method and URI path
POST /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/{version}/update
Request body structure
{
"slotType": {
"description": "string"
}
}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | String |
version |
Yes | The version for a slot type. | Path | String |
description |
No | The slot description, which has a maximum of 255 characters. | Body | 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 invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
The resource you requested is 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. |
ListSlotTypeVersions
List all slot type versions for the slotTypeId
that you provide.
Request
HTTP method and URI path
GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions?maxResults={num}&nextToken={nextToken}&sortDirection={sortDirection}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | String |
maxResults |
No | The maximum number of versions returned. | Path | String |
nextToken |
No | Enables the user to query next page of results. | Path | 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. |
Path | String |
Response
A successful request returns HTTP 200
.
Response body structure
{
"nextToken": "string",
"_links": {
"href": "next_href"
},
"self": {
"href": "current_href"
}
},
"slotTypeVersions": [
{
"version": "string",
"description": "string",
"_links": {
"self": {
"href": "current_href"
}
}
}
]
}
Response body fields
Field | Description | Location | Type |
---|---|---|---|
nextToken |
Enables the user to query next page of results. | Body | String |
totalCount |
Total number of versions with the requested type. | Body | String |
_links |
Hypertext Application Language links to navigate through resources. | Body | String |
version |
The version for a slot type. | Body | String |
description |
Description for a specific version, which has a maximum of 255 characters. | Body | 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 |
The resource you requested is 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. |
DeleteSlotTypeVersion
Deletes a specific slot type version. If a skill is using the slot type version, the request fails.
Request
HTTP method and URI path
DELETE /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/{version}
Request parameters
Parameter | Required | Description | Location | Type |
---|---|---|---|---|
slotTypeId |
Yes | The unique slot type id. | Path | String |
version |
Yes | The version for a slot type. | Path | 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 invalid or expired or doesn't have access to the resource. |
HTTP 403 |
The operation being requested isn't allowed. |
HTTP 404 |
The resource you requested is 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. |
Last updated: Jan 03, 2023