Automation API Reference

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

Note: This API is only available to registered Alexa Smart Properties partners. See Get Started with Alexa Smart Properties APIs.

The Automation API enables you to specify operations for Alexa to automatically perform for users. An automation consists of a trigger, operations, and optional conditions.

About Automations

An automation template represents an abstract automation experience with placeholders, so that later you can create automations from the template with unit specific customizations. For instance, you can create a template that plays music at a placeholder time every day. And then create the automation for room 401 from that template, so that every morning at 8am, Alexa will play music on the echo device in room 401. Automation templates will not execute any operations, you need to create automations from the template in order to have a working automation.

An automation enables an Alexa-connected device (like an Echo device) to automatically perform tasks for users. For example at sunset, turn on the kitchen light. An automation is comprised of one trigger, at least one operation, and optional conditions.

A trigger is a change in state, an event, or a fact that can be used to execute an automation. Automations in Alexa Smart Properties supports the following triggers: Utterances, Time, Sunrise, Sunset.

An operation is an action or task that can be executed when a trigger is invoked. The following operations are supported: Notifications, Brightness (only in Smart Home devices), Power On/Off, Set Volume, Stop Media, Set SetPoint (e.g.,temperature on a thermostat), Do Not Disturb On/Off. The operation property is constructed as a tree, therefore each serial, parallel, and operation object is considered as a tree node. Each parallel node should have less than 90 nodes (including all parallel, serial, and operation nodes). Regardless of whether the operations property has parallel or serial nodes or not, there should be less than 150 nodes. If you have two 90 parallel nodes, then that 180 nodes will exceed the 150 limit.

A condition is one or more rules that Alexa will evaluate and only execute operations if the rule(s) are true.

API endpoint

In the request header, set Host to the following, depending on the region of your organization: https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Automation API includes the following operations.

Operation	HTTP Method and URI
Create automation template	`POST /v2/automations/templates`
Delete automation template	`DELETE /v2/automations/templates/{templateId}`
Get automation template	`GET /v2/automations/templates/{templateId}`
List automation templates	`GET /v2/automations/templates`
Create automation	`POST /v2/automations`
Update automation	`PUT /v2/automations/{automationId}`
Delete automation	`DELETE /v2/automations/{automationId}`
Get automation	`GET /v2/automations/{automationId}`
List automations	`GET /v2/automations`

Create automation template

Creates an automation template that's owned by the user the LWA token represents. Currently, all the automation templates are considered private, which means that only the owner of the template can create automations from the template.

Note: Alexa checks whether the requestor has access to all primitives in the template payload.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To create an automation template, you make a POST request to the /v2/automations/templates resource.

Request header example

Copied to clipboard.

POST /v2/automations/templates HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "template":{
    "trigger":{
       "type": "Alexa.Automation.Trigger.Voice.CustomUtterance",
       "version": "1.0",
       "payload": {
          "utterances": ["${data.customUtterance.text}", "utterance B", "utterance C"],
          "locale": "en-US"
       }
    },
    "operations":{
      "serial":[
        {
          "operation":{
    		"type": "Alexa.Automation.Operation.Notification.Notify",
    		"version": "1.0",
    	    "payload": {
        	"notification": {
            	"variants": [{
                "type": "Announcement",
                "content": {
                    "variants": [{
                        "type": "SpokenText",
                        "values": [{
                            "locale": "en-US",
                            "text": "Happy hour is starting now in the pool area!"
                        }]
                    }]
                }
             }]
           }
          }
         }
        }
      ]
    }
  },
  "dataDefinition":{
    "customUtterance":{
      "type":"object",
      "required":[
        "text"
      ],
      "properties":{
        "text":{
          "type":"string",
          "minLength":1
        }
      }
    }
  },
  "friendlyName":{
    "value":{
      "text":"Test template"
    }
  }
}

Request body parameters

Parameter	Description	Type	Required
`template`	Automation template	Object	Yes
`template.trigger`	Trigger of the automation template. The trigger object can be one of the Alexa-defined trigger schemas. Allowable trigger types are `Alexa.Automation.Trigger.Voice.CustomUtterance`, `Alexa.Automation.Trigger.Schedule.AbsoluteTime`, `Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation`, and `Alexa.Automation.Trigger.Schedule.SunsetInCustomLocation`.	Object	Yes
`template.operations`	Operations of the automation template. This field accepts `serial`, `parallel`, and `operation` nodes. There can be up to 90 parallel nodes and a total of 150 nodes.	Object	Yes
`dataDefinition`	Definition of data parameters inside of the automation template. Each of the keys in this object is a definition of a data parameter. This data follows the specification in JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Example: `{data.customUtterance.text}`.	Object	No
`friendlyName`	Object that contains the user-facing name of the automation template.	Object	No
`friendlyName.value`	Object that contains the friendly name text.	Object	No
`friendlyName.value.text`	Name for the automation template.	String	No

Response

A successful response returns HTTP 201 with the template ID in the Location header.

Response body example

{
  "templateId": "amzn1.alexa.automation.template.{example-template-id}"
}

Response body parameters

Parameter	Description	Type
`templateId`	Alexa-generated template ID for the created automation template, in the format `amzn1.alexa.automation.template.{id}`.	String

HTTP status codes

Status	Description
`201 Created`	Automation template was successfully created.
`400 Bad Request`	The request was malformed for one of the following reasons: • The request body is incorrectly formatted. • The trigger or operation doesn't exist.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	A server-side error occurred.

Delete automation template

Deletes the automation template associated with the specified template ID.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To delete an automation template, you make a DELETE request to the /v2/automations/templates/{templateId} resource.

Only the automation template owner can delete the automation template.

Request header example

Copied to clipboard.

DELETE /v2/automations/templates/{templateId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes
`templateId`	Identifier of the automation template to delete. The format of the template ID must be `amzn1.alexa.automation.template.{id}`.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 204. If there are automation instances based on this template, Alexa returns HTTP 400.

Response body example

The response has no body.

Response body parameters

The response has no body.

HTTP status codes

Status	Description
`204 Success`	The request succeeded.
`400 Bad Request`	There are automation instances based on this template, or the request was malformed. For example, the `templateId` must have the `amzn1.alexa.automation.template` prefix.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`404 Not Found`	The specified `templateId` doesn't exist.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	A server-side error occurred.

Get automation template

Gets the automation template associated with the specified template ID.

The caller must be the owner of the automation template. Otherwise, Alexa returns a 404 response.

Note: If a device is disassociated from the unit, the automations created for the device will also be deleted.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To get an automation template, you make a GET request to the /v2/automations/templates/{templateId} resource.

Request header example

Copied to clipboard.

GET /v2/automations/templates/{templateId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes
`templateId`	The ID of the automation template to retrieve. The format of the template ID must be `amzn1.alexa.automation.template.{id}`.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200, along with the details of the specified automation template.

Response body example

The following example shows a response.

{
  "templateId":"amzn1.alexa.automation.template.{id}",
  "template":{
    "trigger":{
      "type":"CustomUtterance",
      "version":"1.0",
      "payload":{
        "utterance":"${data.customUtterance.text}",
        "locale":"en-US"
      }
    },
    "operations":{
      "serial":[
        {
          "operation":{
            "type":"AlexaAnnouncement",
            "version":1.0,
            "payload":{
              "content":[
                {
                  "locale":"en-US",
                  "speak":{
                    "type":"text",
                    "value":"Hello"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  },
  "dataDefinition":{
    "customUtterance":{
      "type":"object",
      "required":[
        "text"
      ],
      "properties":{
        "text":{
          "type":"string",
          "minLength":1
        }
      }
    }
  },
  "friendlyName":{
    "value":{
      "text":"Test template"
    }
  }
}

Response body parameters

Parameter	Description	Type
`templateId`	The ID of the retrieved automation template. The format of the template ID is `amzn1.alexa.automation.template.{id}`.	String
`template.trigger`	Trigger of the automation template. The trigger object is one of the Alexa-defined trigger schemas.	Object
`template.operations`	Operations of the automation template. This field can be `serial`, `parallel`, and `operation` nodes. There can be up to 90 parallel nodes and a total of 150 nodes.	Object
`dataDefinition`	Definition of data parameters inside of the automation template. Each of the keys in this object is a definition of a data parameter. This data follows the specification in JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Example: `{data.customUtterance.text}`.	Object
`friendlyName`	Object that contains the user-facing name of the automation template.	Object
`friendlyName.value`	Object that contains the friendly name text.	Object
`friendlyName.value.text`	Name for the automation template.	String

HTTP status codes

Status	Description
`200 Success`	The request succeeded.
`400 Bad Request`	The request was malformed or missing required parameters. For example, the `templateId` doesn't have the `amzn1.alexa.automation.template` prefix.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`404 Not Found`	The specified `templateId` doesn't exist.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	Server has encountered an error.

List automation templates

Lists the automation templates.

Note: If a device is disassociated from the unit, the automations created for the device will also be deleted.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To list automation templates, you make a GET request to the /v2/automations/templates resource. Alexa returns all templates created by the customerId associated with the LWA token.

Request header example

Copied to clipboard.

GET /v2/automations/templates?maxResults={maxResults}&nextToken={nextToken}&expand=all HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes
`nextToken`	Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No
`maxResults`	Maximum number of results to return in the response body. This value must be greater than zero and less than or equal to 100. The default value is 20. For details, see Handling Pagination in Query Results.	Number	No
`expand`	Attribute (or set of attributes) to include in the response. Valid values: `all`. If `expand` isn't set, Alexa returns a list of `templateId`.	String	No

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200, along with a list of automation templates.

Response body example without expand set to all

The following example shows a response without expand set to all.

{
  "results":[
    {
      "templateId":"amzn1.alexa.automation.template.{id}"
    }
  ],
  "paginationContext":{
    "nextToken":""
  }
}

Response body example with expand set to all

The following example shows a response with expand set to all.

{
  "results":[
    {
      "templateId":"amzn1.alexa.automation.template.{id}",
      "template":{
        "trigger":{
          "type":"CustomUtterance",
          "version":"1.0",
          "payload":{
            "utterance":"${data.customUtterance.text}",
            "locale":"en-US"
          }
        },
        "operations":{
          "serial":[
            {
              "operation":{
                "type":"AlexaAnnouncement",
                "version":1.0,
                "payload":{
                  "content":[
                    {
                      "locale":"en-US",
                      "speak":{
                        "type":"text",
                        "value":"Hello"
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      },
      "dataDefinition":{
        "customUtterance":{
          "type":"object",
          "required":[
            "text"
          ],
          "properties":{
            "text":{
              "type":"string",
              "minLength":1
            }
          }
        }
      },
      "friendlyName":{
        "value":{
          "text":"Test template"
        }
      }
    }
  ],
  "paginationContext":{
    "nextToken":""
  }
}

Response body parameters

Parameter	Description	Type
`results[]`	List of automation templates returned in response to the query.	Array
`results[].templateId`	The ID of the retrieved automation template. The format of the template ID is `amzn1.alexa.automation.template.{id}`.	String
`results[].template.trigger`	Trigger of the automation template. The trigger object is one of the Alexa-defined trigger schemas.	Object
`results[].template.operations`	Operations of the automation template. This field can be `serial`, `parallel`, and `operation` nodes. There can be up to 90 parallel nodes and a total of 150 nodes.	Object
`results[].dataDefinition`	Definition of data parameters inside of the automation template. Each of the keys in this object is a definition of a data parameter. This data follows the specification in JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Example: `{data.customUtterance.text}`.	Object
`results[].friendlyName`	Object that contains the user-facing name of the automation template.	Object
`results[].friendlyName.value`	Object that contains the friendly name text.	Object
`results[].friendlyName.value.text`	Name for the automation template.	String
`paginationContext.nextToken`	Token to retrieve additional results if the results are paginated and there are more results.	String

HTTP status codes

Status	Description
`200 Success`	The request succeeded.
`400 Bad Request`	The request was malformed (such as the format of the `templateId` or `unitId`) or missing required parameters.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`404 Not Found`	The templates don't exist.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	Server has encountered an error.

Create automation

Creates an automation instance from the automation template for the associated entity (unit).

Note: At automation creation time, Alexa checks whether the requestor has access to the unit, whether the requestor owns the template, and whether the requestor has access to all the primitives in the template.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To create an automation, you make a POST request to the /v2/automations resource.

Request header example

Copied to clipboard.

POST /v2/automations HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "associatedEntity":{
    "type":"UNIT",
    "id":"amzn1.alexa.unit.did.{id}"
  },
  "automation":{
    "templateId":"amzn1.alexa.automation.template.{id}",
    "data":{
      "customUtterance":{
        "text":"Good morning"
      }
    }
  },
  "friendlyName":{
    "value":{
      "text":"Test automation"
    }
  }
}

Request body parameters

Parameter	Description	Type	Required
`associatedEntity`	Associated entity (such as the unit) that Alexa runs this automation on.	String	Yes
`associatedEntity.type`	Type of entity. Valid value: `UNIT`.	String	Yes
`associatedEntity.id`	ID of the associated entity. When the type is `UNIT`, the ID must follow the `unitId` pattern `amzn1.alexa.unit.did.{id}`.	String	Yes
`automation.templateId`	ID of the automation template from which to create the automation instance. The `templateId` must follow the `amzn1.alexa.automation.template.{id}` pattern. The `unitId` should follow the `amzn1.alexa.unit.did.{id}` pattern.	String	Yes
`automation.data`	Key-value map of custom variables and values. The fields in the `data` field are validated against the `dataDefinition` JSON schemas provided in the template. Validations are purely schema validations. This data follows the specification in JSON Schema Validation: A Vocabulary for Structural Validation of JSON.	Object	No
`friendlyName`	Requestor-defined name of the automation. The user can also define this field to distinguish automation instances.	Object	No
`friendlyName.value.text`	String that contains the friendly name of the automation.	String	Yes

Response

A successful response returns HTTP 201 with the automation ID in the Location header.

Response body example

{
  "automationId": "example-automation-id"
}  

Response body parameters

Parameter	Description	Type
`automationId`	Alexa-generated automation ID for the created automation, in the format `amzn1.alexa.automation.{id}`.	String

HTTP status codes

Status	Description
`201 Created`	Automation was successfully created.
`400 Bad Request`	The request was malformed for one of the following reasons: • The request body is incorrectly formatted. • The trigger or operation doesn't exist. • The `templateId` or `unitId` is incorrectly formatted. • There are unresolved unbound variables from the template.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`404 Not Found`	The template or unit doesn't exist.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	A server-side error occurred.

Update automation

Updates the specified automation. Currently, you can only update the data object.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To update an automation, you make a PUT request to the /v2/automations/{automationId} resource.

Request header example

Copied to clipboard.

PUT /v2/automations/{automationId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes
`automationId`	Automation ID of the automation to update.	String	Yes

Request body example

Copied to clipboard.

{
  "automation":{
    "data":{
      "customUtterance":{
        "text":"Good night"
      }
    }
  }
}

Request body parameters

Parameter	Description	Type	Required
`automation.data`	Key/value mapping of the data used to resolve the variables mentioned in the templates. For example, `${data.customUtterance}` refers to the `customerUtterance` field in `data`. If a variable denoted by `${}` isn't found in data, a 400 error occurs.	Object	No

Response

A successful response returns HTTP 204. The request fails if the requestor doesn't have access to the automationId.

Response body example

The response has no body.

HTTP status codes

Status	Description
`204 Succeeded`	The request succeeded.
`400 Bad Request`	The request was malformed for one of the following reasons: • Request body is incorrectly formatted. • The `automationId` doesn't have the `amzn1.alexa.automation.` prefix.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`404 Not Found`	The automation doesn't exist or the requestor doesn't have permission to manage the automation.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	A server-side error occurred.

Delete automation

Deletes the automation associated with the specified automation ID.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To delete an automation, you make a DELETE request to the /v2/automations/{automationId} resource.

Request header example

Copied to clipboard.

DELETE /v2/automations/{automationId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes
`automationId`	Identifier of the automation to delete.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 204.

Response body example

The response has no body.

Response body parameters

The response has no body.

HTTP status codes

Status	Description
`204 Success`	The request succeeded.
`400 Bad Request`	The request was malformed. For example, the `automationId` doesn't have the `amzn1.alexa.automation` prefix.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`404 Not Found`	The automation associated with the provided `automationId` doesn't exist or the requestor doesn't have permission to manage the automation.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	A server-side error occurred.

Get automation

Gets the attributes of the automation associated with the specified automation ID. Alexa returns the automation with all resolved parameters.

The caller must be the owner of the automation. Otherwise, Alexa returns a 404 response.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To get an automation, you make a GET request to the /v2/automations/{automationId} resource.

Request header example

Copied to clipboard.

GET /v2/automations/{automationId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes
`automationId`	The ID of the automation to retrieve.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200, along with the details of the specified automation.

Response body example

The following example shows a response.

{
  "automationId":"amzn1.alexa.automation.{id}",
  "friendlyName":{
    "value":{
      "text":"Good morning"
    }
  },
  "associatedEntity":{
    "type":"UNIT",
    "id":"amzn1.alexa.unit.did.{id}"
  },
  "automation":{
    "templateId":"amzn1.alexa.automation.template.{id}",
    "trigger":{
      "type":"CustomUtterance",
      "version":"1.0",
      "payload":{
        "utterance":"I'm home",
        "locale":"en-US"
      }
    },
    "operations":{
      "serial":[
        {
          "operation":{
            "type":"AlexaAnnouncement",
            "version":1.0,
            "payload":{
              "content":[
                {
                  "locale":"en-US",
                  "speak":{
                    "type":"text",
                    "value":"Hello"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Response body parameters

Parameter	Description	Type
`automationId`	Automation ID in the `amzn1.alexa.automation.{id}` pattern.	String
`associatedEntity`	The target user (such as the unit) that Alexa runs this automation on.	String
`associatedEntity.type`	Type of entity. Valid value: `UNIT`.	String
`associatedEntity.id`	ID of the target user. When the type is `UNIT`, the ID must follow the `unitId` pattern `amzn1.alexa.unit.did.{id}`.	String
`automation.templateId`	The `templateId` that you used to create this automation, if you created the automation from a template.	String
`automation.trigger`	Trigger of the automation.	Object
`automation.operations`	Operations of the automation	Object
`friendlyName`	Requestor-defined name of the automation. The user can also define this field to distinguish automation instances.	Object

HTTP status codes

Status	Description
`200 Success`	The request succeeded.
`400 Bad Request`	The request was malformed or missing required parameters. For example, the `automationId` doesn't have the `amzn1.alexa.automation` prefix.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`404 Not Found`	The specified `automationId` doesn't exist.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	Server has encountered an error.

List automations

Lists the automations associated with the given unitId. You must have permission to view the automations in the given unit. Otherwise, Alexa returns an empty list.

Note: The requestor doesn't have to be the creator of the automation.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To list automations, you make a GET request to the /v2/automations resource.

Request header example for listing the automations of a unit

Copied to clipboard.

GET
/v2/automations?associatedEntity.type=UNIT&associatedEntity.id={id}&maxResults={maxResults}&nextToken={nextToken}&expand=all

Request header example for listing the automations of a unit and a template ID

Copied to clipboard.

GET
/v2/automations?associatedEntity.type=UNIT&associatedEntity.id={id}&templateId={templateId}&maxResults={maxResults}&nextToken={nextToken}&expand=all

Request header parameters

Parameter	Description	Type	Required
`access token`	LWA token.	String	Yes
`associatedEntity.id`	ID that filters the results to only the automations that are associated with a `UNIT`.	String	Yes
`associatedEntity.type`	Type of entity. Valid value: `UNIT`.	String	Yes
`templateId`	Template ID that filters the results to only the automations created from a specific automation template.	String	Yes
`nextToken`	Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No
`maxResults`	Maximum number of results to return in the response body. This value must be greater than zero and less than or equal to 100. The default value is 20. For details, see Handling Pagination in Query Results.	Number	No
`expand`	Attribute (or set of attributes) to include in the response. Valid values: `all`. If `expand` isn't set, Alexa returns a list of `automationId`.	String	No

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200, along with a list of automations.

Response body example without expand set to all

The following example shows a response without expand set to all.

{
  "results":[
    {
      "automationId":"amzn1.alexa.automation.{id}"
    }
  ],
  "paginationContext":{
    "nextToken":""
  }
}

Response body example with expand set to all

The following example shows a response with expand set to all.

{
  "results":[
    {
      "automationId":"amzn1.alexa.automation.{id}",
      "friendlyName":{
        "value":{
          "text":"Good morning"
        }
      },
      "associatedEntity":{
        "type":"UNIT",
        "id":"amzn1.alexa.unit.did.{id}"
      },
      "automation":{
        "templateId":"amzn1.alexa.automation.template.{id}",
        "trigger":{
          "type":"CustomUtterance",
          "version":"1.0",
          "payload":{
            "utterance":"I'm home",
            "locale":"en-US"
          }
        },
        "operations":{
          "serial":[
            {
              "operation":{
                "type":"AlexaAnnouncement",
                "version":1.0,
                "payload":{
                  "content":[
                    {
                      "locale":"en-US",
                      "speak":{
                        "type":"text",
                        "value":"Hello"
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  ],
  "paginationContext":{
    "nextToken":""
  }
}

Response body parameters

Parameter	Description	Type
`results[]`	List of automations returned in response to the query.	Array
`results[].associatedEntity`	The associated entity (unit) for which the automation runs.	String
`results[].associatedEntity.type`	Type of entity. Valid value: `UNIT`.	String
`results[].associatedEntity.id`	ID of the target user. When the type is `UNIT`, the ID follows the `unitId` pattern `amzn1.alexa.unit.did.{id}` .	String
`results[].automationId`	Identifier of the automation.	String
`results[].automation.templateId`	The `templateId` that you used to create this automation, if you created the automation from a template. The `templateId` follows the pattern `amzn1.alexa.automation.template.{id}`.	String
`results[].automation.trigger`	Trigger of the automation.	Object
`results[].automation.operations`	Operations of the automation.	Object
`results[].friendlyName`	Requestor-defined name of the automation. The user can also define this field to distinguish automation instances.	Object
`paginationContext.nextToken`	Token to retrieve additional results if the results are paginated and there are more results.	String

HTTP status codes

Status	Description
`200 Success`	The request succeeded.
`400 Bad Request`	The request was malformed (such as the format of the `templateId`) or missing required parameters.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't be completed because of the client doesn't have permission to perform the operation.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	Server has encountered an error.

Object schemas

The Automation API uses the following objects.

Alexa.Automation.Trigger.Voice.CustomUtterance object

This object represents a voice phrase that triggers an automation to occur. This trigger is only available when the scope is alexa::enterprise:management. If the unit has an automation with the same utterance as the trigger, Alexa returns HTTP 400.

Object example

Copied to clipboard.

{
   "type": "Alexa.Automation.Trigger.Voice.CustomUtterance",
   "version": "1.0",
   "payload": {
      "utterances": ["utterance A", "utterance B", "utterance C"],
      "locale": "en-US"
   }
}

Object parameters

Parameter	Description	Type	Required
`type`	Name of the custom utterance trigger. Valid value: `Alexa.Trigger.CustomUtterance`.	String enum	Yes
`payload.utterances`	List of triggering utterances, in order of preference.	String array	Yes
`payload.locale`	The locale in which the spoken text is rendered, in BCP-47 format. The locale must include both the language and country or region, for example: `en-US`.	String	Yes

Alexa.Automation.Trigger.Schedule.AbsoluteTime object

This object represents a time that triggers an automation to occur.

Object example

Copied to clipboard.

{
   "type": "Alexa.Automation.Trigger.Schedule.AbsoluteTime",
   "version": "1.0",
   "payload": {
      "schedule": {
         "triggerTime": "193209",
         "timeZoneId": "UTC",
         "recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO"
      }
   }
}

Object parameters

Parameter	Description	Type	Required
`type`	Name of the absolute time schedule trigger. Valid value: `Alexa.Automation.Trigger.Schedule.AbsoluteTime`.	String enum	Yes
`version`	Version of the absolute time schedule trigger payload.	String	Yes
`payload.schedule.triggerTime`	Time to run the actions. Formatted as RFC 5545 TIME, without the "Z" notation.	String	Yes
`payload.schedule.timeZoneId`	Time zone for the automation. Required for automatically adjusting daylight saving time when it applies. For details, see List of tz database time zones.	String	Yes
`payload.schedule.recurrence`	Specifies recurrence schedule, in `RRULE` format.	String	Yes

Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation object

This object represents the sunrise that triggers an automation to occur.

Object example

Copied to clipboard.

{
    "type": "Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation",
    "version": "1.0",
    "payload": {
        "recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA",
        "timeZoneId": "test-timezone-id",    
      "latitude": 100,    
      "longitude": 100,    
      "timeOffset": 100
    }
}

Object parameters

Parameter	Description	Type	Required
`type`	Name of the absolute time schedule trigger. Valid value: `Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation`.	String enum	Yes
`version`	Version of the sunrise trigger.	String	Yes
`payload.recurrence`	Recurring expression, which conforms to the RFC 5545 pattern. This trigger is required to recur.	String	Yes
`payload.latitude`	Latitude of the sunrise address.	Number	Yes
`payload.longitude`	Longitude of the sunrise address.	Number	Yes
`payload.timeOffset`	Time offset in minutes from the sunrise time. The default is 0.	Long	No

Alexa.Automation.Trigger.Schedule.SunsetInCustomLocation object

This object represents the sunset that triggers an automation to occur.

Object example

Copied to clipboard.

{
    "type": "Alexa.Automation.Trigger.Schedule.SunsetInCustomLocation",
    "version": "1.0",
    "payload": {
        "recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA",
        "timeZoneId": "test-timezone-id",    
      "latitude": 100,    
      "longitude": 100,    
      "timeOffset": 100
    }
}

Object parameters

Parameter	Description	Type	Required
`type`	Name of the absolute time schedule trigger. Valid value: `Alexa.Automation.Trigger.Schedule.SunsetInCustomLocation`.	String enum	Yes
`version`	Version of the sunset trigger.	String	Yes
`payload.recurrence`	Recurring expression, which conforms to the RFC 5545 pattern. This trigger must recur.	String	Yes
`payload.latitude`	Latitude of the sunset address.	Number	Yes
`payload.longitude`	Longitude of the sunset address.	Number	Yes
`payload.timeOffset`	Time offset in minutes from the sunset time. The default is 0.	Long	No

Alexa.Automation.Operation.Notification.Notify object

This operation represents sending an announcement to the unit when the associated trigger is invoked. The default recipient is the provided unit when associating the automation. This operation is currently only available when the scope is alexa::enterprise:management.

Object example

Copied to clipboard.

{
    "type": "Alexa.Automation.Operation.Notification.Notify",
    "version": "1.0",
    "payload": {
        "notification": {
            "variants": [{
                "type": "Announcement",
                "content": {
                    "variants": [{
                        "type": "SpokenText",
                        "values": [{
                            "locale": "en-US",
                            "text": "Happy hour is starting now in the pool area!"
                        }]
                    }]
                }
            }]
        }
    }
}

Object parameters

Parameter	Description	Type	Required
`type`	Name of the announcement operation. Valid value: `Alexa.Automation.Operation.Notification.Notify`.	String enum	Yes
`version`	Version of the announcement operation payload.	String	Yes
`payload.notification`	Notification object.	Object	Yes
`payload.notification.variants[].type`	Notification delivery type. Valid value: `Announcement`.	String enum	Yes
`payload.notification.variants[].content`	Different variants of content for spoken and display purposes.	Object	Yes
`payload.notification.variants[].content.variants[]`	Notification content to deliver to the user.	Array	Yes
`payload.notification.variants[].content.variants[].type`	Localized text input. Valid value: `SpokenText`.	String enum	Yes
`payload.notification.variants[].content.variants[].values[]`	Array of content values. Each element represents localized text input.	Array	Yes
`payload.notification.variants[].content.variants[].values[].locale`	The locale in which the spoken text is rendered, in BCP-47 format. The locale must include both the language and country or region, for example: `en-US`.	String	Yes
`payload.notification.variants[].content.variants[].values[].text`	Spoken text in plain text format. Maximum length is 1024 characters or 2048 bytes.	String	Yes

Alexa.Automation.Operation.Brightness.SetBrightness object

This object represents an operation that sets the brightness of an endpoint.

Object example

Copied to clipboard.

{  
"operation": {
    "type": "Alexa.Automation.Operation.Brightness.SetBrightness",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ],
      "payload": {
        "brightness": 10
      }
    }
  }
}

Object parameters

Parameter	Description	Type	Required
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1. The `id` must be in the form `amzn1.alexa.endpoint.*`.	Array	Yes
`payload.brightness`	Value from 0-100 (inclusive).	Integer	Yes

Alexa.Automation.Operation.Power.TurnOn object

This object represents an operation that turns on an endpoint.

Object example

Copied to clipboard.

{
  "operation": {
    "type": "Alexa.Automation.Operation.Power.TurnOn",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ]
    }
  }
}

Object parameters

Parameter	Description	Type	Required
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1. The `id` must be in the form `amzn1.alexa.endpoint.*`.	Array	Yes

Alexa.Automation.Operation.Power.TurnOff object

This object represents an operation that turns off an endpoint.

Object example

Copied to clipboard.

{
  "operation": {
    "type": "Alexa.Automation.Operation.Power.TurnOff",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ]
    }
  }
}

Object parameters

Parameter	Description	Type	Required
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1. The `id` must be in the form `amzn1.alexa.endpoint.*`.	Array	Yes

Alexa.Automation.Operation.Speaker.SetVolume object

This object represents an operation that sets the volume of an endpoint.

Object example

Copied to clipboard.

{
  "operation": {
    "type": "Alexa.Automation.Operation.Speaker.SetVolume",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ],
      "payload": {
        "volume": 10
      }
    }
  }
}

Object parameters

Parameter	Description	Type	Required
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1. The `id` must be in the form `amzn1.alexa.endpoint.*`.	Array	Yes
`volume`	Absolute volume to which to set the endpoint's speaker volume. Valid range is 0 to 100.	Integer	Yes

Alexa.Automation.Operation.Media.Stop object

This object represents an operation that stops the media playing on an endpoint.

Object example

Copied to clipboard.

{
  "operation": {
    "type": "Alexa.Automation.Operation.Media.Stop",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ]
    }
  }
}

Object parameters

Parameter	Description	Type	Required
`type`	Name of the operation. Valid value: `Alexa.DeviceControls.Stop`.	String enum	Yes
`version`	Version of the operation schema.	String	Yes
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1. The `id` must be in the form `amzn1.alexa.endpoint.*`.	Array	Yes
`payload.endpoints.id`	The ID of the endpoint to perform the operation. This ID specifies a target device. The endpoint ID should follow the form of `amzn1.alexa.endpoint.*`.	String	Yes

Alexa.Automation.Operation.Thermostat.SetTargetSetpoint object

This object represents an operation that sets the target temperature of a thermostat.

Object example

Copied to clipboard.

{
  "operation": {
    "type": "Alexa.Automation.Operation.Thermostat.SetTargetSetpoint",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ],
      "payload": {
        "targetSetpoint": {
          "value": 20,
          "scale": "CELSIUS"
        }
      }
    }
  }
}

Object parameters

Parameter	Description	Type	Required
`payload.targetSetpoint`	Target set point for a single-set-point thermostat.	Temperature	Yes (for a single-set-point thermostat)

Alexa.Automation.Operation.Settings.SetDoNotDisturbState object

This object represents an operation that puts the object in a do-not-disturb state.

Object example

Copied to clipboard.

{
  "operation": {
    "type": "Alexa.Automation.Operation.Settings.SetDoNotDisturbState",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ],
      "value": true,
      "schedule": {
        "type": "DURATION",
        "value": "PT2H5M"
      }
    }
  }
}

Object parameters

Parameter	Description	Type	Required
`type`	Name of the operation. Valid value: `Alexa.DeviceControls.DoNotDisturb`.	String enum	Yes
`version`	Version of the operation schema.	String	Yes
`payload.endpoints`	Set of endpoints on which to perform the operation. Maximum supported: 1.	Array	Yes
`payload.endpoints.id`	The ID of the endpoint to perform the operation. This ID specifies a target device. The endpoint ID should follow the form of `amzn1.alexa.endpoint.*`.	String	Yes
`payload.value`	Whether to enable `DoNotDisturb` mode for target devices. Valid values: `true` or `false`.	Boolean	Yes
`payload.schedule`	Schedule that enables and disables `DoNotDisturb` mode in a specified time range. If this schedule isn't set, the `DoNotDisturb` mode is permanently changed.	Object	No
`payload.schedule.type`	The `DoNotDisturb` operation supports the following two types of time: • `DURATION`: keeps the updated `DoNotDisturb` status for a specified time. • `TIME`: keeps the updated `DoNotDisturb` status until a specified time.	Enum	Yes
`payload.schedule.value`	Time value for the duration or time, in ISO 8601 format. Examples: • duration: PT2H5M - 2 hours and 5 minutes • time: T18:00 - until 6 PM	String	Yes
`payload.schedule.timeZone`	Time zone, which follows the ISO 8601 standard. Example: `America/New_York`. If not provided, the `timeZone` is set to the default value of the device during operation creation. For the `DURATION` schedule type, the `timeZone` is ignored.	String	No

Was this page helpful?

Provide feedback

Last updated: Jul 09, 2024