Interaction Model Management REST API Reference v1

Use the Interaction Model Management REST API to manage the custom voice interaction model for your skill. For details about the custom voice interaction model, About Voice Interaction Models. For requirements, see Interaction model limits.

To create the interaction model in the developer console, see Create the Interaction Model for Your Skill. For details about the schema, see Interaction Model Schemas.

API endpoint

The endpoint of the Interaction Model Management API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.

Operations

The Interaction Model Management API includes the following operations.

Operation HTTP method and URI

Check interaction model existence

HEAD /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

Get interaction model

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

Get interaction model version

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/versions/{version}

List interaction model versions

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/versions?maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}&sortField={sortField}

Update interaction model

PUT /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

Check interaction model existence

Check whether the interaction model exists for the specified skill, stage, and locale.

Request

To check the existence of the interaction model, you make a HEAD request to the interactionModel resource.

Request path and header example

Copied to clipboard.

HEAD /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

locale

Path

Locale of the skill.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content to indicate that the interaction model exists. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Interaction model exists for the specified skill, stage, and locale.
The response header contains an ETag parameter that identifies the version of the resource.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get interaction model

Get the interaction model for the specified skill.

Request

To get the interaction model, you make a GET request to the interactionModel resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

locale

Path

Locale of the skill.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the interaction model. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "version": "2",
    "description": "Created version 2 of interaction model.",
    "interactionModel": {
        "languageModel": {
            "invocationName": "my space facts",
            "modelConfiguration": {
                "fallbackIntentSensitivity": {
                    "level": "LOW"
                }
            },
            "intents": [{
                    "name": "AMAZON.CancelIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.HelpIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StopIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.FallbackIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StartOverIntent",
                    "samples": []
                },
                {
                    "name": "GetNewFactIntent",
                    "slots": [],
                    "samples": [
                        "Give me a fact",
                        "tell me a fact"
                    ]
                }
            ],
            "types": [{
                "name": "Planet_facts",
                "values": [{
                        "name": {
                            "value": "Mercury"
                        }
                    },
                    {
                        "name": {
                            "value": "Venus"
                        }
                    },
                    {
                        "name": {
                            "value": "Earth"
                        }
                    },
                    {
                        "name": {
                            "value": "Mars"
                        }
                    }
                ]
            }]
        },
        "dialog": {
            "intents": [{
                "name": "GetNewFactIntent",
                "confirmationRequired": false,
                "prompts": {},
                "slots": [{
                    "name": "Answer",
                    "type": "Planet",
                    "confirmationRequired": false,
                    "elicitationRequired": true,
                    "prompts": {
                        "elicitation": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer"
                    }
                }]
            }],
            "delegationStrategy": "ALWAYS"
        },
        "prompts": [{
            "id": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer",
            "variations": [{
                "type": "PlainText",
                "value": "What planet?"
            }]
        }]

    }
}

Response body properties

Property Description Type

version

Identifies the version of the interaction model.

String

description

Describes this version of the interaction model.

String

interactionModel

Defines the properties of the interaction model, such as invocation name, intents, and slots.

Interaction Model object

HTTP status codes

Status Description

200 OK

Response body contains the interaction model for the specified skill, stage, and locale.
The response header contains an ETag parameter that identifies the version of the resource.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get interaction model version

Get the specified version of the interaction model.

Request

To get the interaction model version, you make a GET request to the interactionModel resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

locale

Path

Locale of the skill.

String

Yes

version

Path

Version of the interaction model. To get the current version, use ~current.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the requested version of the interaction model. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "version": "1",
    "description": "Created version 1 of interaction model.",
    "interactionModel": {
        "languageModel": {
            "invocationName": "my space facts",
            "modelConfiguration": {
                "fallbackIntentSensitivity": {
                    "level": "LOW"
                }
            },
            "intents": [{
                    "name": "AMAZON.CancelIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.HelpIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StopIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.FallbackIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StartOverIntent",
                    "samples": []
                },
                {
                    "name": "GetNewFactIntent",
                    "slots": [],
                    "samples": [
                        "Give me a fact",
                        "tell me a fact"
                    ]
                }
            ],
            "types": [{
                "name": "Planet_facts",
                "values": [{
                        "name": {
                            "value": "Mercury"
                        }
                    },
                    {
                        "name": {
                            "value": "Venus"
                        }
                    },
                    {
                        "name": {
                            "value": "Earth"
                        }
                    },
                    {
                        "name": {
                            "value": "Mars"
                        }
                    }
                ]
            }]
        },
        "dialog": {
            "intents": [{
                "name": "GetNewFactIntent",
                "confirmationRequired": false,
                "prompts": {},
                "slots": [{
                    "name": "Answer",
                    "type": "Planet",
                    "confirmationRequired": false,
                    "elicitationRequired": true,
                    "prompts": {
                        "elicitation": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer"
                    }
                }]
            }],
            "delegationStrategy": "ALWAYS"
        },
        "prompts": [{
            "id": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer",
            "variations": [{
                "type": "PlainText",
                "value": "What planet?"
            }]
        }]

    }
}

Response body properties

Property Description Type

version

Identifies the version of the interaction model.

String

description

Describes this version of the interaction model.

String

interactionModel

Defines the properties of the interaction model, such as invocation name, intents, and slots.

Interaction Model object

HTTP status codes

Status Description

200 OK

Response body contains the interaction model of the requested version.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List interaction model versions

Get a list of versions of the interaction model for the specified skill, stage, and locale.

Request

To get the interaction model versions, you make a GET request to the interactionModel resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/versions?maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}&sortField={sortField}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

locale

Path

Locale of the skill.

String

Yes

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–50. Default: 10.

Integer

No

nextToken

Query

Token from the previous response. If not included, the Alexa service returns the first page of results.
Include if iterating over a paginated response.

String

No

sortDirection

Query

Order to sort the results. The default is descending order.
Valid values: asc, desc.

String

No

sortField

Query

Field on which to sort the results.
Valid values: version, description, creationTime.

String

No

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the list of version numbers for the specified interaction model. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "skillModelVersions": [{
            "version": "model.version.1",
            "description": "Created initial version of the interaction model",
            "creationTime": "2019-01-06T05:26:02.430Z",
            "_links": {
                "next": {
                    "href": "next_href"
                },
                "self": {
                    "href": "current_href"
                }
            }
        },
        {
            "version": "model.version.2",
            "description": "Version 2 adds cookie recipe ingredients",
            "creationTime": "2019-02-16T05:26:02.430Z",
            "_links": {
                "next": {
                    "href": "next_href"
                },
                "self": {
                    "href": "current_href"
                }
            }
        }
    ],
    "isTruncated": false,
    "_links": {
        "next": {
            "href": "next_href"
        },
        "self": {
            "href": "current_href"
        }
    }
}

Response body properties

Property Description Type

skillModelVersions

List of versions for the specified interaction model in sortDirection order.

Array of objects

skillModelVersions[].version

Version number of the interaction model.

String

skillModelVersions[].description

Describes the version of the interaction model.

String

skillModelVersions[].creationTime

Creation date and time of the interaction model.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

skillModelVersions[]._links

Links for interaction model navigation.
Defined in JSON Hypertext Application Language specification.

_links object

isTruncated

Indicates whether there are more items to return. If set to true, include nextToken a subsequent request. Or, you can get the remaining items by using the next link in the _links object.

Boolean

nextToken

(Optional) Included when there are more results to return. Use this value in a subsequent request.

String

_links

Links for item navigation.
Defined in JSON Hypertext Application Language specification.

_links object

HTTP status codes

Status Description

200 OK

Response body contains a list of interaction model versions.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update interaction model

Create or update the interaction model for the specified skill. On success, a build starts on the interaction model. To get the build status, use Get skill status.

Request

To create an interaction model, you make a PUT request to the interactionModel resource.

Request path and header example

Copied to clipboard.

PUT /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

locale

Path

Locale of the skill.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "description": "Created version 1 of interaction model.",
    "interactionModel": {
        "languageModel": {
            "invocationName": "my space facts",
            "modelConfiguration": {
                "fallbackIntentSensitivity": {
                    "level": "LOW"
                }
            },
            "intents": [{
                    "name": "AMAZON.CancelIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.HelpIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StopIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.FallbackIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StartOverIntent",
                    "samples": []
                },
                {
                    "name": "GetNewFactIntent",
                    "slots": [],
                    "samples": [
                        "Give me a fact",
                        "tell me a fact"
                    ]
                }
            ],
            "types": [{
                "name": "Planet_facts",
                "values": [{
                        "name": {
                            "value": "Mercury"
                        }
                    },
                    {
                        "name": {
                            "value": "Venus"
                        }
                    },
                    {
                        "name": {
                            "value": "Earth"
                        }
                    },
                    {
                        "name": {
                            "value": "Mars"
                        }
                    }
                ]
            }]
        },
        "dialog": {
            "intents": [{
                "name": "GetNewFactIntent",
                "confirmationRequired": false,
                "prompts": {},
                "slots": [{
                    "name": "Answer",
                    "type": "Planet",
                    "confirmationRequired": false,
                    "elicitationRequired": true,
                    "prompts": {
                        "elicitation": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer"
                    }
                }]
            }],
            "delegationStrategy": "ALWAYS"
        },
        "prompts": [{
            "id": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer",
            "variations": [{
                "type": "PlainText",
                "value": "What's your answer?"
            }]
        }]

    }
}

Request body properties

Property Description Type Required

description

Describes this version of the interaction model.

String

Yes

version

Defines the interaction model, such as invocation name, intents, and slots.

Interaction Model object

Yes

Response

A successful response returns HTTP 202 Accepted, that indicates that the interaction model version was created. The response header contains a Location parameter with a URL to the build status. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

HTTP status codes

Status Description

202 Accepted

Successful creation of the interaction model version and a build is in progress. The response header contains a Location parameter that includes a URL to the build status.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

The Interaction Model Management API defines the following objects.

Locale values

The following table shows valid values for the locale property.

Locale code Language

ar-SA

Arabic (SA)

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

pt-BR

Portuguese (BR)