Utterance Profiler REST API Reference

Use the Utterance Profiler REST API to test user utterances and improve your skill's interaction model. The utterance profiler doesn't call an endpoint or invoke a skill. To test your skill's interaction model, you don't need the backend code for your skill.

With the Utterance Profiler API, you can see how utterances resolve to intents and slots in your interaction model. When an utterance doesn't resolve to the right intent or slot, you can update the interaction model and try again, all before writing any code for your skill. In the API response, you can see what intents were considered and discarded. Then, you can determine how to use additional samples to train your model to resolve utterances to their intended intents and slots.

You can also use the utterance profiler in the Alexa Skills Kit developer console. For details, see Test Your Utterances and Improve Your Interaction Model. To test the utterance with your skill, you can use the Alexa Simulator in the developer console or the Skill Simulation REST API.

API endpoint

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

Operation HTTP method and URI

Profile utterance

POST /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/profileNlu

Profile utterance

Profile an utterance against the most recent interaction model for your skill.

Request

To profile an utterance, you make a POST request to the profileNlu resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/profileNlu
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

locale

Path

Locale of the interaction model to test.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
  "utterance": "i want to travel from seattle",
  "multiTurnToken": null
}

Request body properties

Property Description Type Required

utterance

Utterance text to test.
Valid value: active.

String

Yes

multiTurnToken

Opaque string that contains multi-turn related context. Include this field for multi-turn conversations only. Set the value to the token you received in the previous response.

String

No

Response

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

{
    "sessionEnded": "false",
    "selectedIntent": {
        "name": "GetTravelTimeIntent",
        "confirmationStatus": "CONFIRMED",
        "slots": {
            "DepartingCity": {
                "name": "DepartingCity",
                "value": "Seattle",
                "confirmationStatus": "CONFIRMED",
                "resolutions": {
                    "resolutionsPerAuthority": [{
                        "authority": "1234.City",
                        "status": {
                            "code": "ER_SUCCESS_MATCH"
                        },
                        "values": [{
                            "name": "Seattle",
                            "id": "1234"
                        }]
                    }]
                }
            },
            "ArrivingCity": {
                "name": "ArrivingCity",
                "value": null,
                "confirmationStatus": "NONE",
                "resolutions": null
            }
        }
    },
    "consideredIntents": [{
        "name": "GetTravelTimeIntent",
        "confirmationStatus": "NONE",
        "slots": {
            "DepartingCity": {
                "name": "DepartingCity",
                "value": null,
                "confirmationStatus": "NONE",
                "resolutions": null
            },
            "ArrivingCity": {
                "name": "ArrivingCity",
                "value": null,
                "confirmationStatus": "NONE",
                "resolutions": null
            }
        }
    }],
    "multiTurn": {
        "dialogAct": {
            "type": "SlotValueConfirmation",
            "targetSlot": "DepartureCity"
        },
        "token": "abcd1234...",
        "prompt": "You want to start from Seattle, right?"
    }
}

Response body properties

Property Description Type

sessionEnded

Indicates whether the utterance caused Alexa to exit the skill.

Boolean

selectedIntent

Intent that Alexa selected for the utterance.

Intent object

consideredIntents

List of intents that Alexa considered, but didn't select.

Array of Intent objects

multiTurn

Included when the selected intent has dialog defined and the dialog is not completed. To continue the dialog, provide the value of the token in the multiTurnToken field in the next request.

Object

multiTurn.dialogAct

Prompts to the user.

Object

multiTurn.dialogAct.type

Dialog action for the next response from the user in this multi-turn dialog. For more details, see Dialog directives.
Valid values: Dialog.ElicitSlot, Dialog.ConfirmSlot, Dialog.ConfirmIntent.

String

multiTurn.dialogAct.targetSlot

Target slot that needs to be filled or confirmed in a multi-turn dialog.

String

multiTurn.token

Specifies multiturn dialog context. To continue the dialog, provide this value in the multiTurnToken field in the next request.

Object

multiTurn.prompt

Text that Alexa speaks to the user in the multi-turn dialog.

Object

HTTP status codes

Status Description

200 OK

Response body contains the utterance results.

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 following objects are used by the Utterance Profiler API.

Locale values

The following table shows valid values for the locale property.

Locale code Language

ar-SA

Arabic (SA)

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

pt-BR

Portuguese (BR)