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
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
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
|
Path |
Locale of the skill. |
String |
Yes |
|
|
Header |
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 |
|---|---|
|
|
Interaction model exists for the specified skill, stage, and locale. |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
|
Path |
Locale of the skill. |
String |
Yes |
|
|
Header |
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 |
|---|---|---|
|
|
Identifies the version of the interaction model. |
String |
|
|
Describes this version of the interaction model. |
String |
|
|
Defines the properties of the interaction model, such as invocation name, intents, and slots. |
Interaction Model object |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the interaction model for the specified skill, stage, and locale. |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
|
Path |
Locale of the skill. |
String |
Yes |
|
|
Path |
Version of the interaction model. To get the current version, use |
String |
Yes |
|
|
Header |
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 |
|---|---|---|
|
|
Identifies the version of the interaction model. |
String |
|
|
Describes this version of the interaction model. |
String |
|
|
Defines the properties of the interaction model, such as invocation name, intents, and slots. |
Interaction Model object |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the interaction model of the requested version. |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
|
Path |
Locale of the skill. |
String |
Yes |
|
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
|
Query |
Token from the previous response. If not included, the Alexa service returns the first page of results. |
String |
No |
|
|
Query |
Order to sort the results. The default is descending order. |
String |
No |
|
|
Query |
Field on which to sort the results. |
String |
No |
|
|
Header |
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 |
|---|---|---|
|
|
List of versions for the specified interaction model in |
Array of objects |
|
|
Version number of the interaction model. |
String |
|
|
Describes the version of the interaction model. |
String |
|
|
Creation date and time of the interaction model. |
String |
|
|
Links for interaction model navigation. |
_links object |
|
|
Indicates whether there are more items to return. If set to |
Boolean |
|
|
(Optional) Included when there are more results to return. Use this value in a subsequent request. |
String |
|
|
Links for item navigation. |
_links object |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains a list of interaction model versions. |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
|
Path |
Locale of the skill. |
String |
Yes |
|
|
Header |
String |
Yes |
Request body example
{
"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 |
|---|---|---|---|
|
|
Describes this version of the interaction model. |
String |
Yes |
|
|
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 |
|---|---|
|
|
Successful creation of the interaction model version and a build is in progress. The response header contains a |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
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 |
|---|---|
|
|
Arabic (SA) |
|
|
German (DE) |
|
|
English (AU) |
|
|
English (CA) |
|
|
English (UK) |
|
|
English (IN) |
|
|
English (US) |
|
|
Spanish (ES) |
|
|
Spanish (MX) |
|
|
Spanish (US) |
|
|
French (CA) |
|
|
French (FR) |
|
|
Hindi (IN) |
|
|
Italian (IT) |
|
|
Japanese (JP) |
|
|
Portuguese (BR) |