Skill Simulation REST API Reference

Note: Sign in to the developer console to build or publish your skill.

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.

Important: Use this API for testing purposes only.

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 aren't valid. 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 included token expired or isn't valid. Or, you don'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 aren't valid. 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 included token expired or isn't valid. Or, you don'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

Was this page helpful?

Provide feedback

Last updated: Sep 08, 2023

Skill Simulation REST API Reference

API endpoint

Authentication

Operations

Simulate skill

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Get simulation results

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Object definitions

SkillExecutionInfo object

AlexaExecutionInfo object

ConsideredIntents object

Related topics

Was this page helpful?