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.

API endpoint

In the request header, set Host to one of the following, depending on the region of your organization:

Country	Endpoint
CA, US	https://api.amazonalexa.com
DE, ES, FR, IT, UK	https://api.eu.amazonalexa.com
JP	https://api.fe.amazonalexa.com

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Discovery Session API includes the following operations.

Operation	HTTP Method and URI
Create discovery session	POST /v1/discoverySessions?unit={unitId}
Get discovery session status	GET /v1/discoverySessions/{id}

Create discovery session

Call POST /v1/discoverySessions?unit={unitId} to create a discovery session.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

Request query parameters

Field	Description	Type	Required
unit	The unit ID, in the format "amzn1.alexa.unit.did.{id}".	String	Yes

Request body example

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

Response header

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

Request query parameters

Field	Description	Type	Required
id	The discovery session ID, in the format "amzn1.alexa.discoverySession.{id}".	String	Yes

Response header

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

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.

Related topics

• Get Started with Alexa Smart Properties APIs
• REST API Reference
• About Alexa Smart Properties

---

---

Last updated: Feb 13, 2024