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 reference-based catalog management 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

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 information about referring to values stored elsewhere, see Reference-Based Catalog Management. For information about the schema for slot type definition, see CreateSlotTypeVersion.

Use the Slot Type API

Do the following to start using the Slot Type API.

  1. Create a slot type.
  2. Create a slot type version, during which you also create the slot type definition.
  3. Track the slot type build status.
  4. Open the skill where you want to use the slot.
  5. In the interaction model for your skill, refer to the slot by slotTypeId and version.
  6. 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 information, see Reference-Based Catalog Management.

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