Discovery Session API

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

Note: This API is only available to registered Alexa Smart Properties for residential partners. See Get Started with Alexa Smart Properties for Residential APIs.

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

The endpoint of the Discovery Session 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).

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.

Request format

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

Response header

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.