List Management REST API Reference
Use the List Management REST API to view, update, and traverse lists, including custom lists and default lists, such as the Alexa shopping and to-do lists. You can view and update lists and list items. Also, the API supports archived lists as read-only lists. You can read, but not modify or delete, an item on an archived list. For details about default lists, see Access the Alexa Shopping and To-Do Lists.
API endpoint
The endpoint of the List Management API is https://api.amazonalexa.com
.
Authentication
For API requests from a skill session, include an authorization header whose value is the context.System.apiAccessToken
retrieved from a request from Alexa, such as the LaunchRequest
or IntentRequest
. For more details, see Get access to Alexa lists.
For out-of-session API requests from a website or app, include a Login with Amazon (LWA) access token in the authorization header. For more details about how to obtain the access token, see Get a User-Specific Access Token for Out-of-Session Calls to Alexa.
Operations
The List Management API includes the following operations.
Operation | HTTP method and URI |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
|
Create list
Create a custom list in the active state. You can create up to 100 active lists, including default lists.
Request
To create a list, you make a POST
request to the householdlists
resource.
Request path and header example
POST /v2/householdlists/
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"name": "name of the new custom list",
"state": "active"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Name of the new custom list. Make sure that an active list with this name doesn't already exist. You can create a new list with the same name as an archived list. The name is case-sensitive. |
String |
Yes |
|
Current state of the list. |
String |
Yes |
Response
A successful response returns HTTP 200 OK
, along with the list metadata.
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
{
"listId": "09d9d7df-05be-438c-9d32968c5608",
"name": "name of custom list",
"state": "active",
"version": 1,
"statusMap": [{
"href": "URL",
"status": "active"
},
{
"href": "URL",
"status": "completed"
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List identifier. |
String |
|
Name of the new custom list. |
String |
|
Current state of the list. |
String |
|
Version of the list. |
Integer |
|
Refers to the items on this list. Items might be active or completed. |
Array of objects |
|
URL to get the items on this list. |
String |
|
Status of the list items. |
String |
HTTP status codes
Status | Description |
---|---|
|
List created successfully. The response body contains metadata for the new custom list. |
|
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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Create list item
Create an item and add it to a default list or active custom list.
Request
To create a list item, you make a POST
request to the householdlists
resource.
Request path and header example
POST /v2/householdlists/{listId}/items
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 list. Use the identifier returned in Create list or Get list metadata. You can't add an item to an archived list. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"value": "new item",
"status": "active"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Description of the item. The description is case-sensitive and can't contain spaces only or be empty. |
String |
Yes |
|
Current status of the item. |
String |
Yes |
Response
A successful response returns HTTP 200 OK
, along with the new list item.
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
{
"id": "item identifier",
"version": 1,
"value": "new item",
"status": "active",
"createdTime": "Wed Jul 19 23:24:10 UTC 2022",
"updatedTime": "Wed Jul 19 23:24:10 UTC 2022",
"href": "URL to retrieve the item"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the item. |
String |
|
Version of the item. |
Integer |
|
Description of the item. The description is case-sensitive. |
String |
|
Status of the item. |
String |
|
Time the item was added to the list. |
String |
|
Time the item was last updated. |
String |
|
URL to retrieve this item. |
String |
HTTP status codes
Status | Description |
---|---|
|
List item created successfully. The response body contains the new item. |
|
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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete list
Delete a custom list. You can delete active and archived custom lists, but you can't delete default lists.
Request
To delete a list, you make a DELETE
request to the householdlists
resource.
Request path and header example
DELETE /v2/householdlists/{listId}
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 custom list to be deleted. Use the identifier returned in Create list or Get list metadata. You can't delete a default list. |
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 |
---|---|
|
List deleted 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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete list item
Delete an item from the specified list. You can delete items from active custom and default lists. You can't delete items from archived lists.
Request
To delete a list item, you make a DELETE
request to the householdlists
resource.
Request path and header example
DELETE /v2/householdlists/{listId}/items/{itemId}
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 list. Use the identifier returned in Create list or Get list metadata. You can't delete an item from an archived list. |
String |
Yes |
|
Path |
Identifies the item to be deleted. Use the identifier returned in Create list item or Get list. |
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 |
---|---|
|
List item deleted 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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get list
Get a list by listID
with the specified list status.
Request
To get the list, you make a GET
request to the householdlists
resource.
Request path and header example
GET /v2/householdlists/{listId}/{status}
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 list. Use the identifier returned in Get list metadata. |
String |
Yes |
|
Path |
Get the list with the specified status. |
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 list. If the list contains more than 100 items, the response contains a URL with the next token. Use the URL to get the next set of items.
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
{
"listId": "MTIzLXRvLWRvLVRBU0s=",
"name": "Alexa to-do list",
"state": "active",
"version": 1,
"items":
[
{
"id": "item identifier",
"version": 1,
"value": "take out the garbage",
"status": "active",
"createdTime": "Wed Jul 19 23:24:10 UTC 2022",
"updatedTime": "Wed Jul 19 23:24:10 UTC 2022",
"href": "URL to retrieve the item"
}],
"links": {
"next": "/v2/householdlists/{listId}/{status}?nextToken={nextToken}"
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
List identifier. |
String |
|
Name of the list. |
String |
|
Current state of the list. Default lists are always |
String |
|
Version of the list. |
Integer |
|
Array of items on the list. |
Object |
|
Identifies the item. |
String |
|
Version of the item. |
Integer |
|
Description of the item. The description is case-sensitive. Valid value: Up to 256 characters. |
String |
|
Status of the item. |
String |
|
Time the item was added to the list. |
String |
|
Time the item was last updated. |
String |
|
URL to retrieve this item. |
String |
|
(Optional) If included, indicates that there are more items on the list. |
Object |
|
URL to retrieve the next set of items. Use this path in your next |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the list metadata and an array of the items on the list. |
|
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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get list item
Get a single item from the specified list.
Request
To get an item, you make a GET
request to the householdlists
resource.
Request path and header example
GET /v2/householdlists/{listId}/items/{itemId}
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 list. Use the identifier returned in Create list or Get list metadata. |
String |
Yes |
|
Path |
Identifies the requested item. Use the identifier returned in Create list item or Get list. |
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 item.
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
{
"id": "item identifier",
"version": 1,
"value": "item",
"status": "active",
"createdTime": "Wed Jul 19 23:24:10 UTC 2022",
"updatedTime": "Wed Jul 19 23:24:10 UTC 2022",
"href": "URL to retrieve the item"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the item. |
String |
|
Version of the item. |
Integer |
|
Description of the item. The description is case-sensitive. |
String |
|
Status of the item. |
String |
|
Time the item was added to the list. |
String |
|
Time the item was last updated. |
String |
|
URL to retrieve this item. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains an array of the customer lists. Default lists appear first in the array. |
|
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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get lists metadata
Get all default and custom lists for the customer.
Request
To get all lists for the customer, you make a GET
request to the householdlists
resource.
Request path and header example
GET /v2/householdlists/
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 an array of the customer's default and custom lists.
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 with the following lists: default Alexa to-do list and one custom list.
{
"lists": [{
"listId": "MTIzLXRvLWRvLVRBU0s=",
"name": "Alexa to-do list",
"state": "active",
"version": 1,
"statusMap": [{
"href": "URL",
"status": "active"
},
{
"href": "URL",
"status": "completed"
}
]
},
{
"listId": "ff097d45-c098-44af-a2e9-7dae032b270b",
"name": "Test list",
"state": "active",
"version": 7,
"statusMap": [{
"href": "URL",
"status": "active"
},
{
"href": "URL",
"status": "completed"
}
]
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
Customer lists. Default lists are included before custom lists. |
Array of objects |
|
List identifier. |
String |
|
Name of the list. |
String |
|
Current state of the list. Default lists are always |
String |
|
Version of the list. |
Integer |
|
Refers to the items on this list. Items might be active or completed. |
Array of objects |
|
URL to get the items on this list. |
String |
|
Status of the list items. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains an array of the customer lists. Default lists appear first in the array. |
|
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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update list
Update a custom list. You can update the name and status of the list. Update the list status to archive an active list or restore an archived list. You can't update a default list.
Request
To update a list, you make a PUT
request to the householdlists
resource.
Request path and header example
PUT /v2/householdlists/{listId}
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 custom list. Use the identifier returned in Create list or Get list metadata. You can't update a default list. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The following example changes the name and status of the list.
{
"name": "new custom list name",
"state": "active"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
New name of an active or archived custom list. The name is case-sensitive. |
String |
No |
|
New state of the list. |
String |
No |
|
New version of the list. |
Integer |
No |
Response
A successful response returns HTTP 200 OK
, along with the updated list metadata.
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
{
"listId": "09d9d7df-05be-438c-9d32968c5608",
"name": "new custom list name",
"state": "active",
"version": 2,
"statusMap": [{
"href": "URL",
"status": "active"
},
{
"href": "URL",
"status": "completed"
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List identifier. |
String |
|
New name of the custom list. |
String |
|
Current state of the list. |
String |
|
Version of the list. |
Integer |
|
Refers to the items on this list. Items might be active or completed. |
Array of objects |
|
URL to get the items on this list. |
String |
|
Status of the list items. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains metadata for the updated custom list. |
|
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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update list item
Update the value or status of the specified list item. You can't update an item on an archived list.
Request
To update a list item, you make a PUT
request to the householdlists
resource.
Request path and header example
PUT /v2/householdlists/{listId}/items/{itemId}
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 list. Use the identifier returned in Create list or Get list metadata. |
String |
Yes |
|
Path |
Identifies the item. Use the identifier returned in Create list item or Get list. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"value": "item",
"status": "completed",
"version": 3
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Updated description of the item. The description is case-sensitive and can't contain spaces only or be empty. |
String |
Yes |
|
New status of the item. |
String |
Yes |
|
New version of the item. |
Integer |
Yes |
Response
A successful response returns HTTP 200 OK
, along with the updated list item.
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
{
"id": "item identifier",
"version": 1,
"value": "item",
"status": "active",
"createdTime": "Wed Jul 19 23:24:10 UTC 2022",
"updatedTime": "Wed Jul 19 23:24:10 UTC 2022",
"href": "URL to retrieve the item"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the item. |
String |
|
Version of the item. |
Integer |
|
Description of the item. The description is case-sensitive. |
String |
|
Status of the item. |
String |
|
Time the item was added to the list. |
String |
|
Time the item was last updated. |
String |
|
URL to retrieve this item. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the updated list item. |
|
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. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
Last updated: Dec 09, 2022