Interaction Model Management

This document describes all API operations related to the interaction model resource. 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.

Get Interaction Model

Get an ../smapi/interaction-model-schema.html for a specified skill.

Request

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

Parameters

Field Description Parameter Type Required?
skillId Unique identifier of skill. Path Yes
stage Stage of the skill. Accepted values are development and live (case sensitive). Path Yes
locale Locale of interaction model being retrieved, such as ar-SA, de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, it-IT, ja-JP, or pt-BR. Path Yes

Response

HTTP/1.1 200 OK

Headers

ETag: <etag_value>

Body

Field Description Type
version The version of the interaction model. String
description A description of the interaction model. String
interactionModel An interaction model object. Object

Exceptions

HTTP/1.1 400 Bad Request

HTTP/1.1 401 Unauthorized

HTTP/1.1 403 Forbidden

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Head Interaction Model

Checks whether an ../smapi/interaction-model-schema.html exists for a specified skill.

Request

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

Parameters

Field Description Parameter Type Required?
skillId Unique identifier of skill. Path Yes
stage Stage of the skill. Accepted values are development and live (case sensitive). Path Yes
locale Locale of interaction model being retrieved. Path Yes

Response

HTTP/1.1 204 NoContent

Headers

ETag: {eTag}

Exceptions

HTTP/1.1 400 Bad Request

HTTP/1.1 401 Unauthorized

HTTP/1.1 403 Forbidden

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Update Interaction Model

Use to update the interaction model for a specified skill.

Request

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

Creates an InteractionModel for the skill.

Parameters

Field Description Parameter Type Required?
skillId Unique identifier of skill. Path Yes
stage Stage of the skill. Accepted value is development (case sensitive). Path Yes
locale Locale of interaction model being updated. Path Yes
interactionModel The interaction model. For more information, see Interaction Model Schemas. Body (object) Yes
description A description of this version of the interaction model. Body (string) No

Headers

If-Match: <etag_value>

Response

HTTP/1.1 202 Accepted

Returns build status location link on success.

Headers

ETag: <etag>
Location: <Returns a relative URL to track the status>

Exceptions

HTTP/1.1 400 Bad Request

HTTP/1.1 401 Unauthorized

HTTP/1.1 403 Forbidden

HTTP/1.1 404 Not Found

HTTP/1.1 412 Precondition Failed

HTTP/1.1 429 Too Many Requests

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

List Interaction Model Versions

Get a list of the available versions of the interaction model for the specified skill. Interaction model versions are available only after they build successfully.

Request

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

Parameters

Field Description Parameter Type Required?
skillId Unique identifier of skill. Path Yes
stage Stage of the skill. The only accepted value is development (case sensitive). Path Yes
locale Locale of interaction model being retrieved, such as ar-SA, de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, it-IT, ja-JP, or pt-BR. Path Yes
nextToken Use this parameter to get more versions, after you receive a response with truncated results. Set it to the value of nextToken from the truncated response you just received. Query No
maxResults The maximum number of versions to return in the response. When you don't include this parameter, the default maximum is 10. When you include this parameter, the response might contain fewer items than the value you specify, but will never contain more. You cannot specify a value higher than 50. Query No
sortDirection Sets the sorting direction of the versions returned in the response. Valid values are asc and desc. When set to asc the versions are returned in ascending order, and when set to desc the versions are returned in descending order. Query No
sortField Sets the field that the sorting is applied to. The only valid value is version. Query No

Response

HTTP/1.1 200 OK

Body

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "skillModelVersions": [
    {
      "version": "string",
      "creationTime": "string",
      "description": "string",
      "_links": {
        "self": {
          "href": "string"
        }
      }
    }
  ],
  "isTruncated": true,
  "nextToken": "string"
}
Field Description Type
_links Links for API navigation. The structure of this field is defined in the JSON Hypertext Application Language specification. _links object (spec)
skillModelVersions Contains a list (array) of available interaction model versions. Each version contains the version identifier, the time of creation, a description, and _links object. Object
isTruncated A flag that indicates whether there are more available versions than those returned in the response. When this value is true, the list in this response is truncated. To get more items, pass the value of this response's nextToken field to the nextToken parameter in a subsequent request. Boolean
nextToken When isTruncated is true, this field contains the value to use for the nextToken parameter in a subsequent request. String

Exceptions

HTTP/1.1 400 Bad Request

HTTP/1.1 401 Unauthorized

HTTP/1.1 403 Forbidden

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Get Interaction Model Version

Get the specified version of the interaction model for the specified skill.

Request

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

Parameters

Field Description Parameter Type Required?
skillId Unique identifier of skill. Path Yes
stage Stage of the skill. Accepted values are development and live (case sensitive). Path Yes
locale Locale of interaction model being retrieved, such as ar-SA, de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, it-IT, ja-JP, or pt-BR. Path Yes
version The version of the interaction model to get. For example, 1, 2, 3, 4, and so on. Use ~current to get the current version. Path Yes

Response

HTTP/1.1 200 OK

Body

Field Description Type
version The version of the interaction model. String
description A description of the interaction model version. String
interactionModel An interaction model object. Object

Exceptions

HTTP/1.1 400 Bad Request

HTTP/1.1 401 Unauthorized

HTTP/1.1 403 Forbidden

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Get the Interaction Model Building Status

Use Get Skill Status to get the interaction model's building status.