Discovery Session API
Use the Discovery Session API to find the endpoints associated with a unit. Creating a discovery session instructs Alexa to look for new or updated endpoints, such as those connected via a smart home skill.
Create discovery session
Call POST /v1/discoverySessions?unit={unitId} to create a discovery session.
POST /v1/discoverySessions?unit={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request query parameters
| Field |
Description |
Type |
Required |
unit |
The unit ID, in the format "amzn1.alexa.unit.did.{id}". |
String |
Yes |
Request body example
{
"endpointReporter": {
"type": "SKILL",
"value": {
"skillId": "amzn1.ask.skill.skillId",
"skillStage": "LIVE"
}
}
}
Request body parameters
| Field |
Description |
Type |
Required |
endpointReporter |
An entity that reports endpoints when invoked by Alexa. |
Object |
Yes |
endpointReporter.type |
The endpoint reporter type. Currently only SKILL is supported. |
Enum |
Yes |
endpointReporter.value |
Attribute values describing the endpoint reporter for which the discovery session is to be created. |
Object |
Yes |
skillId |
The skill ID, in the format "amzn1.alexa.skill.{id}". |
String |
Yes |
skillStage |
The skill stage: DEVELOPMENT or LIVE. The default value is LIVE. |
String |
No |
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v1/discoverySessions/amzn1.alexa.discoverySession.{id}"
| Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Location |
The location of the discovery session. Use this URI to get a discovery session.
The URI provided in the Location header is valid for 1 hour from the time the response is received. |
String |
Yes |
id |
The discovery session ID as part of the Location header URI. |
String |
Yes |
Response body example
{
"id": "amzn1.alexa.discoverySession.c777715e-0cf2-433e-89de-4f0f0892150"
}
Response body parameters
| Field |
Description |
Type |
Required |
id |
The session ID for the new discovery session. |
String |
Yes |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
| Field |
Description |
Type |
Required |
type |
The error type for the error. |
String |
No |
message |
The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. |
String |
No |
HTTP response codes
| Status Code |
Name |
Description |
| 201 |
Created |
The discovery session was successfully created. |
| 400 |
Bad Request |
The request is malformed or is missing one or more required parameters. |
| 401 |
Unauthorized |
The access token is missing, expired, or invalid. |
| 403 |
Forbidden |
The access token is valid, but the user doesn't have the needed LWA scope permissions. |
| 404 |
Not found |
The requested artifact wasn't found for the client. |
| 409 |
Discovery session conflict |
A discovery session is already in progress. |
| 429 |
Too many requests |
Request has been throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
| 500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received. |
| 503 |
Service Unavailable |
Service is temporarily unavailable. |
Get discovery session status
Call GET /v1/discoverySessions/{id} to determine the status of a discovery session.
GET /v1/discoverySessions/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request query parameters
| Field |
Description |
Type |
Required |
id |
The discovery session ID, in the format "amzn1.alexa.discoverySession.{id}". |
String |
Yes |
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
| Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body example
{
"status": {
"value": "IN_PROGRESS"
}
}
Response body parameters
| Field |
Description |
Type |
Required |
status |
Status of the discovery session. |
Object |
Yes |
status.value |
SUCCESS - The discovery operation completed successfully.
IN_PROGRESS - The discovery operation is in progress.
FAILURE - The discovery operation failed. Reasons for failure include:
- skill Lambda returning error upon discovery directive
- internal server errors |
Enum |
Yes |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
| Field |
Description |
Type |
Required |
type |
The error type for the error. |
String |
No |
message |
The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. |
String |
No |
HTTP response codes
| Status Code |
Name |
Description |
| 200 |
Created |
The discovery session status was successfully queried. |
| 400 |
Bad Request |
The request is malformed or is missing one or more required parameters. |
| 401 |
Unauthorized |
The access token is missing, expired, or invalid. |
| 403 |
Forbidden |
The access token is valid, but the user doesn't have the needed LWA scope permissions. |
| 404 |
No such discovery session |
The discovery session ID doesn't exist or the URI is expired. The URI expires after 1 hour of creation of the discovery session. |
| 429 |
Too many requests |
Request has been throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
| 500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received. |
| 503 |
Service Unavailable |
Service is temporarily unavailable. |
