Discovery Session REST API Reference

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 endpoints

Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.

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). For details, see Manage API Access.

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

Create a discovery session to find the endpoints assigned to a unit.

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

To create a discovery session, you make a POST request to the /v1/discoverySessions resource.

Request path and header example

Copied to clipboard.

POST /v1/discoverySessions?unit={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

unitId

Query

Unique ID for the unit.
Formatted as an Amazon Common Identifier (ACI), unit.did.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

{
   "endpointReporter": {
      "type": "SKILL",
      "value": {
         "skillId": "amzn1.ask.skill.skillId",
         "skillStage": "live"
      }
   }
}

Request body properties

Property Description Type Required

endpointReporter

An entity that reports endpoint information to Alexa.

Object

Yes

endpointReporter.type

Type of reporter.
Valid values: SKILL.

String

Yes

endpointReporter.value

Describes the endpoint reporter for the new discovery session.

Object

Yes

endpointReporter.value.id

Skill ID.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.skill.{id}.

String

Yes

endpointReporter.value.skillStage

(Optional) Stage of the skill.
Valid values: development, live.
Default: live.

String

No

Response

A successful response returns HTTP 201 Created, along with the identifier for the discovery session. The response header includes the Location parameter set to the URL location of the session, such as /v1/discoverySessions/amzn1.alexa.discoverySession.1. You can use the URL to check the status of the session. The URL is valid for one hour.

On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The following example shows a response.

{
   "id": "amzn1.alexa.discoverySession.1"
}

Response body properties

Property Description Type

id

Identifies the discovery session.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.discoverySession.{id}.

String

HTTP status codes

Status Description

201 Created

Discovery session created successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don'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

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You 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.

Get discovery session status

Get the status of the specified 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

To get status, you make a GET request to the /v1/discoverySessions/ resource.

Request path and header example

Copied to clipboard.

GET /v1/discoverySessions/{id} HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

id

Query

Unique ID for the session.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.discoverySession.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the status of the session. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
   "status": {
        "value": "IN_PROGRESS"
    }
}

Response body properties

Property Description Type

status

Current status of the discovery session.

Object

status.value

Status value.
Failures might be due to the skill returning an Alexa.ErrorResponse to the Discovery directive or internal server errors.
Valid values: SUCCESS, IN_PROGRESS, FAILURE.

String

HTTP status codes

Status Description

200 OK

Response body contains the status of the specified discovery session.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don'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

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You 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 Discovery Session API defines the following object definitions.

Error object

The Error object defines the error type and message included in the response when an error occurs.

The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
Property Description Type

type

Type of error that occurred.
For specific error types, see the HTTP status code table for each operation.

String

message

The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message..

String

Was this page helpful?

Last updated: Oct 30, 2024