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.

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.

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.

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

Response header

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.

Was this page helpful?

Last updated: Feb 13, 2024