Skill Invocation REST API Reference v2

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

Use the Skill Invocation REST API to test your custom skill. You can invoke skill at the Amazon Web Services (AWS) Lambda or HTTPS endpoint where the skill code resides and receive the response payload.

To use the Skill Invocation 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.

API endpoint

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

Operation	HTTP method and URI
Invoke skill	`POST /v2/skills/{skillId}/stages/{stage}/invocations`

Invoke skill

Invoke the specified skill for testing.

Note: Your skill must respond within 10 seconds. Otherwise, the request times out and returns an error.

Request

To invoke a skill, you make a POST request to the invocations resource.

Request path and header example

Copied to clipboard.

POST /v2/skills/{skillId}/stages/{stage}/invocations
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
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "endpointRegion": "NA",
    "skillRequest": {
        "body": {
            "version": "1.0",
            "session": {
                "new": true,
                "sessionId": "amzn1.echo-api.session.1",
                "application": {
                    "applicationId": "amzn1.ask.skill.1"
                },
                "attributes": {},
                "user": {
                    "userId": "amzn1.ask.account.1"
                }
            },
            "context": {
                "System": {
                    "application": {
                        "applicationId": "amzn1.ask.skill.1"
                    },
                    "user": {
                        "userId": "amzn1.ask.account.1"
                    }
                }
            },
            "request": {
                "type": "IntentRequest",
                "requestId": "amzn1.echo-api.request.1",
                "timestamp": "2017-08-14T04:20:20Z",
                "locale": "en-US",
                "intent": {
                    "name": "SayHello"
                }
            }
        }
    }
}

Request body properties

Property	Description	Type	Required
`endpointRegion`	AWS endpoint region or HTTPS endpoint where the skill resides. Valid values: `NA`, `EU`, `FE`, `default`.	String	Yes
`skillRequest`	Current state of the list. Valid value: `active`.	Object	Yes
`skillRequest.body`	Request body schema. For details, see Request body syntax.	Object	Yes

Response

A successful response returns HTTP 200 OK, along with the skill response. 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.

{
    "status": "SUCCESSFUL",
    "result": {
        "skillExecutionInfo": {
            "invocationRequest": {
                "endpoint": "arn:aws:lambda:us-east-1:1:function:HelloWorld",
                "body": {
                    "version": "1.0",
                    "session": {
                        "new": true,
                        "sessionId": "amzn1.echo-api.session.1",
                        "application": {
                            "applicationId": "amzn1.ask.skill.1"
                        },
                        "attributes": {},
                        "user": {
                            "userId": "amzn1.ask.account.1"
                        }
                    },
                    "context": {
                        "System": {
                            "application": {
                                "applicationId": "amzn1.ask.skill.1"
                            },
                            "user": {
                                "userId": "amzn1.ask.account.1"
                            }
                        }
                    },
                    "request": {
                        "type": "IntentRequest",
                        "requestId": "amzn1.echo-api.request.1",
                        "timestamp": "2017-08-14T04:20:20Z",
                        "locale": "en-US",
                        "intent": {
                            "name": "SayHello"
                        }
                    }
                }
            },
            "invocationResponse": {
                "body": {
                    "version": "1.0",
                    "sessionAttributes": {},
                    "response": {
                        "outputSpeech": {
                            "type": "PlainText",
                            "text": "hello, world"
                        },
                        "shouldEndSession": true
                    }
                }
            },
            "metrics": {
                "skillExecutionTimeInMilliseconds": 100
            }
        },
        "error": null
    }
}

Response body properties

Property	Description	Type
`status`	Indicates the success or failure of the skill invocation. Valid values: `SUCCESSFUL`, `FAILED`.	String
`result`	Describes the result of the invocation.	Object
`result.skillExecutionInfo`	Includes the payload sent in the request and the payload received from the endpoint.	Object
`result.skillExecutionInfo.invocationRequest`	Request parameters.	Object
`result.skillExecutionInfo.invocationRequest.endpoint`	AWS endpoint region or HTTPS endpoint of the skill.	String
`result.skillExecutionInfo.invocationRequest.body`	JSON payload sent in the request to your skill. For details, see Request body syntax.	Object
`result.skillExecutionInfo.invocationResponse`	(Optional) JSON payload returned by the skill. For details, see Response body syntax.	Object
`result.skillExecutionInfo.metrics`	Metrics recorded for the request and response.	Object
`result.skillExecutionInfo.metrics.skillExecutionTimeInMilliseconds`	How long, in milliseconds, it took the AWS Lambda or HTTPS endpoint to process the request.	Integer
`result.error`	Reports any errors that occurred.	Object
`result.error.message`	(Optional) Describes the problem.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the invocation results from your skill.
`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 code 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`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

Was this page helpful?

Provide feedback

Last updated: Aug 01, 2024