Reminders REST API Reference
Use the Alexa Reminders API to create and manage reminders from your skill.
For more details about reminders, see Alexa Reminders Overview.
API endpoint
Use one of the following API hosts, based on the region where the customer is located:
- North America:
https://api.amazonalexa.com - Europe:
https://api.eu.amazonalexa.com - Far East:
https://api.fe.amazon.com
You can find the API endpoint in the context.System.apiEndpoint retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.
Authentication
Each API request must have an authorization header whose value is the context.System.apiAccessToken retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.
You can access the API from your app or service outside of a skill session with a Login with Amazon (LWA) access token. You can use an out-of-session access token to edit or delete a reminder, but you can only create and update a reminder from your skill. For more details about out-of-session access tokens, see Out of session interaction.
Access to reminders is based on the permission scopes enabled for your skill and granted by the customer.
| Permission scope | Description |
|---|---|
|
|
Allows your skill to create and update reminders. |
Operations
The Reminders API includes the following operations.
| Operation | HTTP method and URI |
|---|---|
|
| |
|
| |
|
| |
|
| |
|
|
Create reminder
Create a new reminder.
apiAccessToken. Don't use an out-of-session token.Request
To create a reminder, you make a POST request to the /v1/alerts/reminders resource.
Request path and header example
POST /v1/alerts/reminders
Host: api.amazonalexa.com
Content-Type: application/json
Content-length: {length}
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Header |
Length of the content in bytes. |
Integer |
Yes |
|
|
Header |
Set to |
String |
Yes |
Request body example
The following example shows a request to create a reminder at the specified offset from the current time.
The following example shows a request to create a reminder at the specified absolute time.
timezoneId field, otherwise your reminder might ring at the incorrect time. For more details about time zones, see How time zones work.The following example shows a request to create a recurring reminder at the specified absolute time.
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Creation time of this reminder. |
String |
Yes |
|
|
Describes the time to set the reminder. |
Object |
Yes |
|
|
Type of trigger. |
String |
Yes |
|
|
Specifies the time in seconds after which the reminder rings. |
Integer |
No |
|
|
Specifies the absolute time to set the reminder. |
String |
No |
|
|
Specifies the time zone, such as Note: Make sure you set the correct value for the
timezoneId field, otherwise your reminder might ring at the incorrect time. For more details about time zones, see How time zones work. |
String |
No |
|
|
Describes the rules for the recurring reminder. |
Object |
No |
|
|
Start of the recurrence pattern. Default is current time. |
String |
No |
|
|
End of the recurrence pattern. Default is no end time. |
String |
No |
|
|
Recurrence pattern for repeating reminders.
|
Array of RRULEs |
No |
|
|
Defines the reminder. |
Object |
Yes |
|
|
Defines the information to say for the reminder. |
Object |
Yes |
|
|
Spoken content in the alert. |
Array of objects |
Yes |
|
|
Defines the locale and language for the text. |
String |
Yes |
|
|
Default text used for display and spoken content. |
String |
Yes |
|
|
Text used for spoken content, generated with SSML. |
String |
No |
|
|
Indicates whether to send a push notification to the Alexa app. |
Object |
Yes |
|
|
Enable or disable push notifications to the Alexa app. |
String |
Yes |
Response
A successful response returns HTTP 200 OK, along with the unique reminder ID, called alertToken.
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.
{
"alertToken": "alert.token.1",
"createdTime": "2019-08-14T15:40:55.002Z",
"updatedTime": "2019-08-14T15:40:55.002Z",
"status": "ON",
"version": "1",
"href": "www.-example-new-alert.com"
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Unique id of this reminder. |
String |
|
|
Creation time of the reminder. |
String |
|
|
Time of last update to the reminder. |
String |
|
|
Status of the reminder. |
String |
|
|
Version of the reminder. |
String |
|
|
URI to retrieve the created reminder. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Reminder created successfully. |
|
|
Indicates that one or more properties in the request body aren't valid. For more details, see Error code values. |
|
|
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. |
Delete reminder
Use the alertToken generated on reminder creation to delete a specific reminder. You can use List reminders API to retrieve the reminders and their alertToken.
This operation deletes active reminders, not completed reminders. You can view recently completed reminders in the Alexa app.
Request
To delete a reminder, you make a DELETE request to the /v1/alerts/reminders/ resource.
Request path and header example
DELETE /v1/alerts/reminders/{alertToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the reminder. |
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.
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 response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Reminder deleted successfully. |
|
|
Indicates that one or more properties in the request body aren't valid. For more details, see Error code values. |
|
|
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 reminder
Use the alertToken generated on reminder creation to get a specific reminder. You can use List reminders API to retrieve the reminders and their alertToken.
Request
To get a reminder, you make a GET request to the /v1/alerts/reminders resource.
Request path and header example
GET /v1/alerts/reminders/{alertToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the reminder. |
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 requested reminder.
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
{
"alertToken": "alert.token.1",
"createdTime": "2019-08-14T15:40:55.002Z",
"updatedTime": "2019-08-14T15:40:55.002Z",
"status": "ON",
"trigger": {
"type": "SCHEDULED_ABSOLUTE",
"timeZoneId": "America/Los_Angeles",
"recurrence": {
"startDateTime": "2019-05-10T6:00:00.000",
"endDateTime": "2019-08-10T10:00:00.000",
"recurrenceRules": [
"FREQ=DAILY;BYDAY=SU;BYHOUR=17;BYMINUTE=15;BYSECOND=0;INTERVAL=1;",
"FREQ=MONTHLY;BYMONTHDAY=5;BYHOUR=10;INTERVAL=1;"
]
}
},
"alertInfo": {
"spokenInfo": {
"content": [{
"locale": "en-US",
"text": "walk the dog.",
"ssml": "<speak> walk the dog</speak>"
}]
}
},
"pushNotification": {
"status": "ENABLED"
},
"version": "1"
}
Response body properties
The response includes the Reminder object for the requested reminder ID.
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the reminder. |
|
|
Indicates that one or more properties in the request body aren't valid. For more details, see Error code values. |
|
|
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. |
List reminders
Get a list of all reminders for the customer specified in the access token. This operation returns active and completed reminders.
Request
To list reminders, you make a GET request to the /v1/alerts/reminders resource.
Request path and header example
GET /v1/alerts/reminders
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
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 a list of reminders.
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
{
"totalCount": "string",
"alerts": [{
"alertToken": "alert.token.1",
"createdTime": "2019-08-14T15:40:55.002Z",
"updatedTime": "2019-08-14T15:40:55.002Z",
"status": "ON",
"trigger": {
"type": "SCHEDULED_ABSOLUTE",
"timeZoneId": "America/Los_Angeles",
"recurrence": {
"startDateTime": "2019-05-10T6:00:00.000",
"endDateTime": "2019-08-10T10:00:00.000",
"recurrenceRules": [
"FREQ=DAILY;BYDAY=SU;BYHOUR=17;BYMINUTE=15;BYSECOND=0;INTERVAL=1;",
"FREQ=MONTHLY;BYMONTHDAY=5;BYHOUR=10;INTERVAL=1;"
]
}
},
"alertInfo": {
"spokenInfo": {
"content": [{
"locale": "en-US",
"text": "walk the dog.",
"ssml": "<speak> walk the dog</speak>"
}]
}
},
"pushNotification": {
"status": "ENABLED"
},
"version": "1"
},
{
"alertToken": "alert.token.2",
"createdTime": "2019-08-13T15:40:55.002Z",
"updatedTime": "2019-08-13T15:40:55.002Z",
"status": "COMPLETED",
"trigger": {
"type": "SCHEDULED_RELATIVE",
"offsetInSeconds": "7200"
},
"alertInfo": {
"spokenInfo": {
"content": [{
"locale": "en-US",
"text": "call the dentist",
"ssml": "<speak>call the dentist</speak>"
}]
}
},
"pushNotification": {
"status": "ENABLED"
}
}
],
"links": "link.to.next.reminder"
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Number of reminders returned. |
String |
|
|
List of reminders. |
Array of Reminder objects |
|
|
URL to retrieve the next set of reminders if there are more reminders. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains a list of reminders. |
|
|
Indicates that one or more properties in the request body aren't valid. For more details, see Error code values. |
|
|
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. |
Update reminder
Use the alertToken generated on reminder creation to update an existing reminder. You can use List reminders API to retrieve the reminders and their alertToken.
apiAccessToken. Don't use an out-of-session token.Request
To update the specified reminder, you make a PUT request to the /v1/alerts/reminders resource.
Request path and header example
PUT /v1/alerts/reminders/{alertToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the reminder. |
String |
Yes |
|
|
Header |
Access token used for the customer. Set to |
String |
Yes |
Request body example{#update-a-reminder-request-body-example}
The following example shows a request to update a reminder at the specified offset from the current time.
The following example shows a request to update a reminder at the specified absolute time.
timezoneId field, otherwise your reminder might ring at the incorrect time. For more details about time zones, see How time zones work.The following example shows a request to update a recurring reminder at the specified absolute time.
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Creation time of this reminder. |
String |
Yes |
|
|
Describes the time to set the reminder. |
Object |
Yes |
|
|
Type of trigger. |
String |
Yes |
|
|
Specifies the time in seconds after which the reminder rings. |
Integer |
No |
|
|
Specifies the absolute time to set the reminder. |
String |
No |
|
|
Specifies the time zone, such as Note: Make sure you set the correct value for the
timezoneId field, otherwise your reminder might ring at the incorrect time. For more details about time zones, see How time zones work. |
String |
No |
|
|
Describes the rules for the recurring reminder. |
Object |
No |
|
|
Start of the recurrence pattern. Default is current time. |
String |
No |
|
|
End of the recurrence pattern. Default is no end time. |
String |
No |
|
|
Recurrence pattern for repeating reminders.
|
Array of RRULEs |
No |
|
|
Defines the reminder. |
Object |
Yes |
|
|
Defines the information to say for the reminder. |
Object |
Yes |
|
|
Spoken content in the alert. |
Array of objects |
Yes |
|
|
Defines the locale and language for the text. |
String |
Yes |
|
|
Default text used for display and spoken content. |
String |
Yes |
|
|
Text used for spoken content, generated with SSML. |
String |
No |
|
|
Indicates whether to send a push notification to the Alexa app. |
Object |
Yes |
|
|
Enable or disable push notifications to the Alexa app. |
String |
Yes |
Response
A successful response returns HTTP 200 OK, along with the unique reminder ID, called alertToken and update time.
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 successful response.
{
"alertToken": "alert.token.1",
"createdTime": "2019-08-14T15:40:55.002Z",
"updatedTime": "2019-08-15T11:20:25.000Z",
"status": "ON",
"version": "1",
"href": "www.-example-updated-alert.com"
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Unique id of this reminder. |
String |
|
|
Creation time of the reminder. |
String |
|
|
Time of last update to the reminder. |
String |
|
|
Status of the reminder. |
String |
|
|
Version of the reminder. |
String |
|
|
URI to retrieve the updated reminder. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Reminder updated successfully. |
|
|
Indicates that one or more properties in the request body aren't valid. For more details, see Error code values. |
|
|
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. |
Reminder events
If your skill integrates with an external app or services, subscribe to reminder events to receive notifications. Your skill can use account linking to integrate with an external app, and use notifications of these events to make changes, such as by deleting or modifying the reminders in the app.
Any action that a skill takes as the result of a reminder event should consider the timestamp of the event, as notifications of events might arrive out of order. For example, if a reminder is updated twice, and the earlier update event arrives after the second update event, your skill should disregard the earlier update.
Alexa attempts to redeliver events if the skill service doesn't send an acknowledgment in response. The skill service can't retrieve past events from Alexa, but must rely on the event delivery.
For more details about subscribing to reminder events, see Events in Alexa skills.
API endpoint for events
The endpoint used in events is https://api.amazonalexa.com.
Reminder events
Your skill can subscribe to reminder events by configuring your skill.json manifest file. For more details on this process, see Use Events in Your Skill Service.
You can subscribe to the following reminder events.
Object definitions
The Reminders API defines the following object definitions.
AlertInfo object
The AlertInfo object defines spoken and display alert information for the reminder.
| Property | Description | Type |
|---|---|---|
|
|
Defines the information to say for the reminder. |
Object |
|
|
Spoken content in the alert. |
Array of objects |
|
|
Defines the locale and language for the text. |
String |
|
|
Default text used for display and spoken content. |
String |
|
|
(Optional) Text used for spoken content, generated with SSML. |
String |
Reminder object
The Reminder object defines the reminder trigger, spoken text, and optional recurrence rules.
| Property | Description | Type |
|---|---|---|
|
|
Unique id of this reminder. |
String |
|
|
Creation time of the reminder. |
String |
|
|
Time of last update to the reminder. |
String |
|
|
Status of the reminder. |
String |
|
|
Describes when the reminder triggers. |
Trigger object |
|
|
Defines the reminder. |
AlertInfo object |
|
|
Indicates whether to send a push notification to the Alexa app. |
Object |
|
|
Enable or disable push notifications to the Alexa app. |
String |
|
|
Version of the reminder. |
String |
Trigger object
The Trigger object defines when the reminder triggers.
trigger.recurrence.byDay and trigger.recurrence.freq are deprecated in favor of the following more specific recurrence parameters: startDateTime, endDateTime, recurrenceRules[]. This change is backwards compatible. If your payload contains the new parameters, the old recurrence rules freq, byDay, and scheduledTime are ignored.| Property | Description | Type |
|---|---|---|
|
|
Type of trigger. |
String |
|
|
(Optional) Specifies the time in seconds after which the reminder rings. |
Integer |
|
|
(Optional) Specifies the absolute time to trigger the reminder. |
String |
|
|
(Optional) Specifies the time zone of the trigger, such as |
String |
|
|
(Optional) Describes the rules for recurring reminders. |
Object |
|
|
(Optional) Start of the recurrence pattern. Default is current time. |
String |
|
|
(Optional) End of the recurrence pattern. Default is no end time. |
String |
|
|
(Optional) Recurrence pattern for repeating reminders.
|
Array of RRULEs |
|
|
Deprecated: Frequency type of the recurrence. |
String |
|
|
Deprecated: Specifies a day or list of days within a week. Use the first two letters of the weekday name. For example, a full week is [ "SU", "MO", "TU", "WE", "TH", "FR", "SA" ]. To trigger a reminder on multiple days of the week, every week, you must create one individual reminder for each day. |
String |
Error code values{#error-codes}
When errors occur, the Reminders API returns detailed error codes for each HTTP status code.
The following example shows the response body with the error code and message.
{
"message": "The property is outside the allowed range.",
"code": "INVALID_STRING_LENGTH"
}
The following table shows possible error codes returned with HTTP 400 Bad Request.
| Error code | Message |
|---|---|
|
|
Request time date format incorrect. |
|
|
Type and field do not match => SCHEDULED_ABSOLUTE has offsetInSeconds or SCHEDULED_RELATIVE has scheduledTime. |
|
|
Scheduled time is in the past. |
|
|
Date format is not supported. |
|
|
Time zone is not valid. |
|
|
Recurrence pattern is invalid. |
|
|
Recurrence pattern is valid but not currently supported. |
|
|
Recurrence pattern is valid but minimum interval between two occurrences is not supported. |
|
|
Alert info is missing locale / invalid locale format. |
|
|
Invalid relative time offset. |
|
|
Unsupported trigger scheduled time format. |
The following table shows possible error codes returned with HTTP 401 Unauthorized.
| Error code | Message |
|---|---|
|
|
Token is valid but does not have appropriate permissions. |
|
|
Missing access token. |
|
|
Invalid / wrong access token. |
|
|
Access token expired. |
|
|
Reminders can only be created in session. |
The following table shows possible error codes returned with HTTP 403 Forbidden.
| Error code | Message |
|---|---|
|
|
Max limit of reminders on the device reached (for example, 500). |
|
|
Reminders are not supported on this device. |
Related topics
Last updated: May 22, 2024