List Management REST API Reference

Note: Sign in to the developer console to build or publish your skill.

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	`POST /v2/householdlists/`
Create list item	`POST /v2/householdlists/{listId}/items`
Delete list	`DELETE /v2/householdlists/{listId}`
Delete list item	`DELETE /v2/householdlists/{listId}/items/{itemId}`
Get list	`GET /v2/householdlists/{listId}/{status}`
Get list item	`GET /v2/householdlists/{listId}/items/{itemId}`
Get lists metadata	`GET /v2/householdlists/`
Update list	`PUT /v2/householdlists/{listId}`
Update list item	`PUT /v2/householdlists/{listId}/items/{itemId}`

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

Copied to clipboard.

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
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "name": "name of the new custom list",
    "state": "active"
}

Request body properties

Property	Description	Type	Required
`name`	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. Valid value: up to 256 characters.	String	Yes
`state`	Current state of the list. Valid value: `active`.	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
`listId`	List identifier. Valid value: Base64 up to 256 characters.	String
`name`	Name of the new custom list.	String
`state`	Current state of the list. Valid values: `active`, `archived`.	String
`version`	Version of the list.	Integer
`statusMap`	Refers to the items on this list. Items might be active or completed.	Array of objects
`lists[].statusMap[].URL`	URL to get the items on this list.	String
`lists[].statusMap[].status`	Status of the list items. Valid values: `active`, `completed`.	String

HTTP status codes

Status	Description
`200 OK`	List created successfully. The response body contains metadata for the new custom list.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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.

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

Copied to clipboard.

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
`listId`	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. Valid values: Up to 256 characters.	String	Yes
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "value": "new item",
    "status": "active"
}

Request body properties

Property	Description	Type	Required
`value`	Description of the item. The description is case-sensitive and can't contain spaces only or be empty. Valid value: up to 256 characters.	String	Yes
`status`	Current status of the item. Valid values: `active`, `completed`.	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
`id`	Identifies the item. Valid value: Base64 value up to 256 characters.	String
`version`	Version of the item.	Integer
`value`	Description of the item. The description is case-sensitive. Valid value: Up to 256 characters.	String
`status`	Status of the item. Valid values: `active`, `completed`.	String
`createdTime`	Time the item was added to the list. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`updatedTime`	Time the item was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`href`	URL to retrieve this item.	String

HTTP status codes

Status	Description
`200 OK`	List item created successfully. The response body contains the new item.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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.

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

Copied to clipboard.

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
`listId`	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. Valid values: Up to 256 characters.	String	Yes
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, 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. 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
`200 OK`	List deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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.

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

Copied to clipboard.

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
`listId`	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. Valid values: Up to 256 characters.	String	Yes
`itemId`	Path	Identifies the item to be deleted. Use the identifier returned in Create list item or Get list. Valid value: Base64 value up to 256 characters.	String	Yes
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, 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. 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
`200 OK`	List item deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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 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

Copied to clipboard.

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
`listId`	Path	Identifies the list. Use the identifier returned in Get list metadata. Valid values: 1 – 255 characters.	String	Yes
`status`	Path	Get the list with the specified status. Valid values: `active`, `archived`.	String	Yes
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, 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 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.

Note: The response exposes the list item order. An external app can choose to present Alexa list items in another order.

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
`listId`	List identifier. Default Alexa To Do list item identifier: -TASK Default Alexa Shopping list item identifier: -SHOPPING_ITEM Valid value: Base64 up to 256 characters.	String
`name`	Name of the list.	String
`state`	Current state of the list. Default lists are always `active`. Valid values: `active`, `archived`.	String
`version`	Version of the list.	Integer
`items`	Array of items on the list.	Object
`items[].id`	Identifies the item. Valid value: Base64 value up to 256 characters.	String
`items[].version`	Version of the item.	Integer
`items[].value`	Description of the item. The description is case-sensitive. Valid value: Up to 256 characters.	String
`items[].status`	Status of the item. Valid values: `active`, `completed`.	String
`items[].createdTime`	Time the item was added to the list. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`items[].updatedTime`	Time the item was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`items[].href`	URL to retrieve this item.	String
`links`	(Optional) If included, indicates that there are more items on the list.	Object
`links.next`	URL to retrieve the next set of items. Use this path in your next `Get list` request header.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the list metadata and an array of the items on the list.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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 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

Copied to clipboard.

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
`listId`	Path	Identifies the list. Use the identifier returned in Create list or Get list metadata. Valid values: Up to 256 characters.	String	Yes
`itemId`	Path	Identifies the requested item. Use the identifier returned in Create list item or Get list. Valid value: Base64 value up to 256 characters.	String	Yes
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, 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 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
`id`	Identifies the item. Valid value: Base64 value up to 256 characters.	String
`version`	Version of the item.	Integer
`value`	Description of the item. The description is case-sensitive. Valid value: Up to 256 characters.	String
`status`	Status of the item. Valid values: `active`, `completed`.	String
`createdTime`	Time the item was added to the list. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`updatedTime`	Time the item was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`href`	URL to retrieve this item.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains an array of the customer lists. Default lists appear first in the array.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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 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

Copied to clipboard.

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
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, 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 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
`lists`	Customer lists. Default lists are included before custom lists.	Array of objects
`lists[].listId`	List identifier. Default Alexa To Do list item identifier: -TASK Default Alexa Shopping list item identifier: -SHOPPING_ITEM Valid value: Base64 up to 256 characters.	String
`lists[].name`	Name of the list.	String
`lists[].state`	Current state of the list. Default lists are always `active`. Valid values: `active`, `archived`.	String
`lists[].version`	Version of the list.	Integer
`lists[].statusMap`	Refers to the items on this list. Items might be active or completed.	Array of objects
`lists[].statusMap[].URL`	URL to get the items on this list.	String
`lists[].statusMap[].status`	Status of the list items. Valid values: `active`, `completed`.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains an array of the customer lists. Default lists appear first in the array.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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.

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

Copied to clipboard.

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
`listId`	Path	Identifies the custom list. Use the identifier returned in Create list or Get list metadata. You can't update a default list. Valid values: Up to 256 characters.	String	Yes
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, set to an LWA token.	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
`name`	New name of an active or archived custom list. The name is case-sensitive. Valid value: up to 256 characters.	String	No
`state`	New state of the list. Valid value: `active`.	String	No
`version`	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
`listId`	List identifier. Valid value: Base64 up to 256 characters.	String
`name`	New name of the custom list.	String
`state`	Current state of the list. Valid values: `active`, `archived`.	String
`version`	Version of the list.	Integer
`statusMap`	Refers to the items on this list. Items might be active or completed.	Array of objects
`lists[].statusMap[].URL`	URL to get the items on this list.	String
`lists[].statusMap[].status`	Status of the list items. Valid values: `active`, `completed`.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains metadata for the updated custom list.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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.

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

Copied to clipboard.

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
`listId`	Path	Identifies the list. Use the identifier returned in Create list or Get list metadata. Valid values: Up to 256 characters.	String	Yes
`itemId`	Path	Identifies the item. Use the identifier returned in Create list item or Get list. Valid value: Base64 value up to 256 characters.	String	Yes
`access token`	Header	Access token for the customer. For in-session requests, set to `apiAccessToken`. For out-of-session requests, set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "value": "item",
    "status": "completed",
    "version": 3
}

Request body properties

Property	Description	Type	Required
`value`	Updated description of the item. The description is case-sensitive and can't contain spaces only or be empty. Valid value: up to 256 characters.	String	Yes
`status`	New status of the item. Valid values: `active`, `completed`.	String	Yes
`version`	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
`id`	Identifies the item. Valid value: Base64 value up to 256 characters.	String
`version`	Version of the item.	Integer
`value`	Description of the item. The description is case-sensitive. Valid value: Up to 256 characters.	String
`status`	Status of the item. Valid values: `active`, `completed`.	String
`createdTime`	Time the item was added to the list. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`updatedTime`	Time the item was last updated. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`href`	URL to retrieve this item.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the updated list item.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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`	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.
`500 Server Error`	Error occurred on the server. The skill 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.

Was this page helpful?

Provide feedback

Last updated: Dec 09, 2022