Skill Simulation REST API Reference

Use the Skill Simulation REST API to see the intent that a simulated Alexa-enabled device returns from your interaction model. You can use this information add additional samples to train your model to resolve utterances to their intended intents and slots.

To use the Skill Simulation API, your skill must meet the following requirements:

  • The skill must be a custom skill.
  • The skill must belong to the developer account that you use to call this API.
  • The skill must be enabled.
  • The skill must be in the development or live stage.

To test specific utterances and use the responses to improve your interaction model, use the Utterance Profiler API.

API endpoint

The endpoint of the Skill Simulation 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 Skill Simulation API includes the following operations.

Operation HTTP method and URI

Simulate skill

POST /v2/skills/{skill-id}/stages/{stage}/simulations

Get simulation results

GET /v2/skills/{skill-id}/stages/{stage}/simulations/{simulationId}

Simulate skill

Simulate a dialog from an Alexa-enabled device and receive the skill response for the specified example utterance.

Request

To simulate an utterance, you make a POST request to the simulations resource.

Request path and header example

Copied to clipboard.

POST /v2/skills/{skill-id}/stages/{stage}/simulations
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

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "session": {
        "mode": "DEFAULT"
    },
    "input": {
        "content": "ask greeter to say hello"
    },
    "device": {
        "locale": "en-US"
    }
}

Request body properties

Property Description Type Required

session

Defines the behavior of the simulated dialog.

Object

No

session.mode

Set to influence the session behavior of the simulated dialog.
Valid values:

  • FORCE_NEW_SESSION: Ensures that a new dialog session is started before running the simulation.
  • DEFAULT: Keeps the default session behavior of the simulated dialog.

String

No

input

Input to the simulation.

Object

Yes

input.content

Utterance text from a user to Alexa.

String

Yes

device

Information about the simulated Alexa-enabled device.

Object

Yes

device.locale

Locale for the virtual device used in the simulation.
Valid values: en-US, en-GB, en-CA, en-AU, de-DE, fr-FR, en-IN, ja-JP.

String

Yes

Response

A successful response returns HTTP 200 OK, along with a Location in the header that contains a path to the simulation and an ID in the body to track the simulation request. 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 following example shows a response.

{
    "id": "simulation.id.1",
    "status": "IN_PROGRESS",
    "result": null
}

Response body properties

Property Description Type

id

Identifies the simulations.
Used the ID in the Get simulation result API.

String

status

Current status of the simulation.
Valid values: IN_PROGRESS, SUCCESSFUL, FAILED.

String

result

Result of the skill simulation request.
Set to null if the response code is 200 OK with a status of IN_PROGRESS.
If the response code is 200 OK with a status of FAILED, the result contains an error.message field with a description of the error.

Object

HTTP status codes

Status Description

200 OK

Response body contains the simulation ID and 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.

Get simulation results

Get the results of the specified simulation.

Request

To get the results, you make a GET request to the simulations resource.

Request path and header example

Copied to clipboard.

GET /v2/skills/{skill-id}/stages/{stage}/simulations/{simulationId}
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

simulationId

Path

Identifies the simulation.
Use the identifier returned from the Simulate skill API response.

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 results of the specified simulation. 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

{
    "id": "simulation.id.1",
    "status": "IN_PROGRESS",
    "result": {
        "skillExecutionInfo": {
            "invocations": [{
                "invocationRequest": {
                    "endpoint": "endpoint.1",
                    "body": "JSON payload that was sent to the skill's endpoint"
                },
                "invocationResponse": {
                    "body": "Payload that was returned by the skill's AWS Lambda or HTTPS endpoint."
                },
                "metrics": {
                    "skillExecutionTimeInMilliseconds": 5
                }
            }]
        },
        "alexaExecutionInfo": {
            "alexaResponses": [{
                "type": "Speech",
                "content": {
                    "caption": "Example speech."
                }
            }],
            "consideredIntents": [{
                "name": "Intent name",
                "confirmationStatus": "CONFIRMED",
                "slots": {
                    "SlotName": {
                        "name": "Example slot name",
                        "value": "Example value",
                        "confirmationStatus": "CONFIRMED",
                        "resolutions": {
                            "resolutionsPerAuthority": [{
                                "authority": "",
                                "status": {
                                    "code": "ER_SUCCESS_MATCH"
                                },
                                "values": [{
                                    "value": {
                                        "name": "Example name",
                                        "id": "Example ID"
                                    }
                                }]
                            }]
                        }
                    }
                }
            }]
        },
        "error": {
            "message": "Error message"
        }
    }
}

Response body properties

Property Description Type

id

ID of the simulation.

String

status

Current status of the simulation.
Valid values: IN_PROGRESS, SUCCESSFUL, FAILED.

String

result

Information about the simulation result.

Object

result.skillExecutionInfo

Skill execution information.

SkillExecutionInfo object

result.alexaExecutionInfo

Alexa execution information.

AlexaExecutionInfo object

HTTP status codes

Status Description

200 OK

Response body contains the results of the simulation.

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 Skill Simulation API defines the following objects.

SkillExecutionInfo object

Parameter Description Type

invocations

Information about the invocations in the simulation.

Array of objects

invocations[].invocationRequest

Request information.

Object

invocations[].invocationRequest.endpoint

AWS Lambda or HTTPS endpoint of the skill.

String

invocations[].invocationRequest.body

JSON payload sent in the request to your skill.
For details, see Request body syntax.

Object

invocations[].invocationResponse

Response information.

Object

invocations[].invocationResponse.body

(Optional) JSON payload returned by the skill.
For details, see Response body syntax.

Object

invocations[].metrics

Metrics recorded for the request and response.

Object

invocations[].metrics.skillExecutionTimeInMilliseconds

How long, in milliseconds, it took the AWS Lambda or HTTPS endpoint to process the request.

Integer

AlexaExecutionInfo object

Parameter Description Type

alexaResponses

Array of responses from Alexa.

Array of objects

alexaResponses[i].type

Type of response from Alexa.
Valid value: Speech.

String

alexaResponses[i].content

Object that contains the content of the Alexa response.

Object

alexaResponses[i].content.caption

Textual representation of Alexa's speech response.

String

consideredIntents

List of considered intents returned by natural language understanding (NLU).
Maximum: Up to 5 intents.

Array of ConsideredIntents objects

ConsideredIntents object

Parameter Description Type

name

Name of the intent.

String

confirmationStatus

Indicates whether the user explicitly confirmed or denied the entire intent.
Valid values: NONE, CONFIRMED, DENIED.

String

slots

Slot information.

Object

slotName

Slot name.

Object

slotName.name

Slot name.

String

slotName.value

Slot value.

String

slotName.confirmationStatus

Indicates whether the user explicitly confirmed or denied this slot.
Valid values: NONE, CONFIRMED, DENIED.

String

slotName.resolutions

Results of resolving the words captured from the user's utterance.

Object

slotName.resolutions.resolutionsPerAuthority

List of possible authorities for entity resolution. An authority represents the source for the data provided for the slot. For a custom slot type, the authority is the slot type you defined.

Array of objects

slotName.resolutions.resolutionsPerAuthority[].authority

Name of the authority for the slot values. For custom slot types, this authority label incorporates your skill ID and the slot type name.

String

slotName.resolutions.resolutionsPerAuthority[].status

Status of entity resolution for the slot.

Object

slotName.resolutions.resolutionsPerAuthority[].status.code

Code that indicates the results of attempting to resolve the user utterance against the defined slot types.
Valid values:

  • ER_SUCCESS_MATCH: Spoken value matched a value or synonym explicitly defined in your custom slot type.
  • ER_SUCCESS_NO_MATCH: Spoken value did not match any values or
  • synonyms explicitly defined in your custom slot type.
  • ER_ERROR_TIMEOUT: An error occurred due to a timeout.
  • ER_ERROR_EXCEPTION: An error occurred due to an exception during processing.

String

slotName.resolutions.resolutionsPerAuthority[].values

List of resolved values for the slot.

Array of objects

slotName.resolutions.resolutionsPerAuthority[].values[].value

Information about the resolved slot value.

Object

slotName.resolutions.resolutionsPerAuthority[].values[].value.name

Resolved slot value.

String

slotName.resolutions.resolutionsPerAuthority[].valuesi].value.id

Unique ID defined for the resolved slot value. This ID is based on the IDs defined in the slot type definition.

String

Last updated: Dec 27, 2022