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 |
|
|
DE, ES, FR, IT, UK |
|
|
JP |
|
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
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
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 |
|---|---|---|---|---|
|
|
Query |
Unique ID for the unit. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"endpointReporter": {
"type": "SKILL",
"value": {
"skillId": "amzn1.ask.skill.skillId",
"skillStage": "live"
}
}
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
An entity that reports endpoint information to Alexa. |
Object |
Yes |
|
|
Type of reporter. |
String |
Yes |
|
|
Describes the endpoint reporter for the new discovery session. |
Object |
Yes |
|
|
Skill ID. |
String |
Yes |
|
|
(Optional) Stage of the skill. |
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 code and human readable message.
Response body example
The following example shows a response.
{
"id": "amzn1.alexa.discoverySession.1"
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Identifies the discovery session. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Discovery session created successfully. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Query |
Unique ID for the session. |
String |
Yes |
|
|
Header |
Access token for the customer. |
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 code and human readable message.
Response body example
{
"status": {
"value": "IN_PROGRESS"
}
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Current status of the discovery session. |
Object |
|
|
Status value. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the status of the specified discovery session. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
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. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
- Endpoints REST API Reference
- Get Started with Alexa Smart Properties APIs
- Alexa Smart Properties REST API Reference
- About Alexa Smart Properties
Last updated: Sep 09, 2024