Automation REST 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. For details, see Get Started with Alexa Smart Properties APIs.

Use the Automation REST API to specify operations for Alexa to automatically perform tasks for users in Alexa Smart Properties (ASP). An automation consists of a trigger, operations, and optional conditions.

About automations

An automation template describes the behavior of an automated task without any unit or endpoint specifics. The template represents an abstract automation experience with placeholders. After you create a template, you set up automations from the template with unit-specific customizations. For example, you can create a template that plays music at a placeholder time every day. And then create the automation for room 401 from the template, so that every morning at 8 AM, Alexa plays music on the Echo device in room 401. Automation templates won't invoke any operations. Instead, you must construct automations from the template 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 includes one trigger, at least one operation, and optional conditions.

A trigger is a change in state, an event, or a fact to invoke an automation. Automations in ASP supports the following triggers: Utterances, Time, Sunrise, Sunset.

An operation is an action or task that Alexa invokes when trigger conditions are met. Automations in ASP supports the following operations: Notifications, Brightness (only in Smart Home devices), Power On/Off, Set Volume, Stop Media, Set SetPoint 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 in total. If you have two 90 parallel nodes, then those 180 nodes exceed the 150 limit.

A condition is one or more rules that Alexa evaluates, and then if the rules are true, Alexa invokes the associated operations.

API endpoint

The endpoint of the Automation API is 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). For details, see Manage API Access.

Operations

The Automation API supports the following types of operations:

Template management – Create and manage automation templates to use in property units.
Automation management – Create and manage automations within a unit based on a template.

Template management

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?expand=all&maxResults={maxResults}&nextToken={nextToken}`

Automation management

Operation	HTTP Method and URI
Create automation	`POST /v2/automations`
Delete automation	`DELETE /v2/automations/{automationId}`
Get automation	`GET /v2/automations/{automationId}`
List automations	`GET /v2/automations?associatedEntity.type=UNIT&associatedEntity.id={id}&expand=all&maxResults={maxResults}&nextToken={nextToken}`
Update automation	`PUT /v2/automations/{automationId}`

Create automation template

Create an automation template that's owned by the user the LWA token represents. At this time, only the owner of the template can create automations from the template.

Note: Alexa checks whether the caller 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 path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	Access token for the customer. Set to an 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 properties

Parameter	Description	Type	Required
`template`	Automation template	Object	Yes
`template.trigger`	Trigger of the automation template.	Trigger object	Yes
`template.operations`	Operations of the automation template. Includes one of `serial`, `parallel`, or `operation` property. You can include up to 150 operations in total.	Object	Yes
`template.operations.serial`	List of operations that Alexa invokes serially.	Array of Operation objects	No
`template.operations.parallel`	List of operations that Alexa invokes in parallel. Maximum number of elements in the array: 90.	Array of Operation objects	No
`template.operations.operation`	A single operation.	Operation object	No
`dataDefinition`	Definition of data parameters inside of the automation template. Each of the keys in this object is a definition of a parameter. This data follows the specification in JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Example: `{data.customUtterance.text}`.	Object	No
`friendlyName`	Developer-facing name of the automation template.	Object	No
`friendlyName.value`	Friendly name text.	Object	No
`friendlyName.value.text`	Name of the automation template.	String	No

Response

A successful response returns HTTP 201 Created along with the template ID. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
  "templateId": "amzn1.alexa.automation.template.1"
}

Response body parameters

Parameter	Description	Type
`templateId`	Unique identifier of the automation template. Formatted as an Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String

HTTP status codes

Status	Description
`201 Created`	Automation template successfully created.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The request body is incorrectly formatted. The trigger or operation doesn't exist.
`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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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 automation template

Deletes the automation template associated with the specified template ID. Only the automation template owner can delete the template.

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.

Request path and 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 path and header parameters

Parameter	Located in	Description	Type	Required
`templateId`	Path	Identifier of the automation template to delete. Formatted as an Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String	Yes
`access token`	Header	Access token for the customer. 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 204 No Content. If there are automation instances based on this template, Alexa returns HTTP 400 Bad Request. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body parameters

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Template deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: There are automation instances based on this template. The template ID is malformed.
`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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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 automation template

Gets the automation template associated with the specified template ID.
The caller must be the owner of the automation template.

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 path and 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 path and header parameters

Parameter	Located in	Description	Type	Required
`templateId`	Path	Identifier of the automation template. Formatted as an Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String	Yes
`access token`	Header	Access token for the customer. 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 template. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The following example shows a response.

{
  "templateId":"amzn1.alexa.automation.template.1",
  "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`	Identifier of the automation template. Formatted as an Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String
`template.trigger`	Trigger of the automation template.	Trigger object
`template.operations`	Operations of the automation template. Includes one of `serial`, `parallel`, or `operation` property.	Object
`template.operations.serial`	List of operations that Alexa invokes serially.	Array of Operation objects
`template.operations.parallel`	List of operations that Alexa invokes in parallel. Maximum number of elements in the array: 90.	Array of Operation objects
`template.operations.operation`	A single operation.	Operation object
`dataDefinition`	Definition of data parameters inside of the automation template. Each of the keys in this object is a definition of a parameter. This data follows the specification in JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Example: `{data.customUtterance.text}`.	Object
`friendlyName`	Developer-facing name of the automation template.	Object
`friendlyName.value`	Friendly name text.	Object
`friendlyName.value.text`	Name of the automation template.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the requested template.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The template ID is malformed.
`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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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.

List automation templates

Lists the automation templates. Alexa returns all templates owned by the caller.

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.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`expand`	Query	Get expanded information about each template. If `expand` isn't included, Alexa returns a list of template IDs. Valid values: `all`.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–100. Default: 20.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No
`access token`	Header	Access token for the customer. 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 a list of templates. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body examples

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

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

Response body parameters

Parameter	Description	Type
`results`	List of automation templates returned in response to the query.	Array of objects
`results[].templateId`	Identifier of the automation template. Formatted as an Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String
`results[].template.trigger`	Trigger of the automation template.	Trigger object
`results[].template.operations`	Operations of the automation template. Includes one of `serial`, `parallel`, or `operation` property.	Object
`results[].template.operations.serial`	List of operations that Alexa invokes serially.	Array of Operation objects
`results[].template.operations.parallel`	List of operations that Alexa invokes in parallel. Maximum number of elements in the array: 90.	Array of Operation objects
`results[].template.operations.operation`	A single operation.	Operation object
`results[].dataDefinition`	Definition of the data parameters inside of the automation template. Each of the keys in this object is a definition of a parameter. This data follows the specification in JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Example: `{data.customUtterance.text}`.	Object
`results[].friendlyName`	Developer-facing name of the automation template.	Object
`results[].friendlyName.value`	Friendly name text.	Object
`results[].friendlyName.value.text`	Name of the automation template.	String
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request with the same filter parameters as this request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of templates.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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 automation

Creates an automation instance from the specified automation template for the specified unit.

Note: At automation creation time, Alexa checks whether the caller has access to the unit, whether the caller owns the template, and whether the caller 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 path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

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

Request body properties

Parameter	Description	Type	Required
`associatedEntity`	Associated entity, such as the unit, that Alexa runs this automation on.	Object	Yes
`associatedEntity.type`	Type of entity. Valid value: `UNIT`.	String	Yes
`associatedEntity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}` .	String	Yes
`automation.templateId`	ID of the automation template from which to create the automation instance. Format as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String	Yes
`automation.data`	Key-value map of custom variables and values. Alexa validates fields in the `data` field 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. Example: `{data.customUtterance.text}`.	Object	No
`friendlyName`	Requestor-defined name of the automation. You can also define this field to distinguish automation instances.	NameValue object	No

Response

A successful response returns HTTP 201 Created along with the automation ID. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
  "automationId": "amzn1.alexa.automation.123"
}  

Response body parameters

Parameter	Description	Type
`automationId`	Alexa-generated automation ID for the new automation, Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.{id}`.	String

HTTP status codes

Status	Description
`201 Created`	Automation created successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid 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`	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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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 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 path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`automationId`	Path	Identifies the automation to delete from the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.{id}`.	String	Yes
`access token`	Header	Access token for the customer. 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 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body parameters

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Automation deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The automation ID is malformed.
`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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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 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.

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

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 path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`automationId`	Path	Identifies the automation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.{id}`.	String	Yes
`access token`	Header	Access token for the customer. 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 details of the specified automation. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The following example shows a response.

{
  "automationId":"amzn1.alexa.automation.123",
  "friendlyName":{
    "value":{
      "text":"Good morning"
    }
  },
  "associatedEntity":{
    "type":"UNIT",
    "id":"amzn1.alexa.unit.did.101"
  },
  "automation":{
    "templateId":"amzn1.alexa.automation.template.1",
    "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`	Identifies the requested automation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.{id}`.	String
`associatedEntity`	Associated entity, such as the unit, in which Alexa runs this automation.	Object
`associatedEntity.type`	Type of entity. Valid value: `UNIT`.	String
`associatedEntity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String
`automation.templateId`	ID of the automation template from which you created the automation instance. Format as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String
`automation.trigger`	Trigger of the automation.	Trigger object
`automation.operations`	Operations invoked when the automation triggers. Includes one of `serial`, `parallel`, or `operation` property.	Object
`automation.operations.serial`	List of operations that Alexa invokes serially.	Array of Operation objects
`automation.operations.parallel`	List of operations that Alexa invokes in parallel. Maximum number of elements in the array: 90.	Array of Operation objects
`automation.operations.operation`	A single operation.	Operation object
`friendlyName`	(Optional) Name of the automation. You can also define this field to distinguish automation instances.	NameValue object

HTTP status codes

Status	Description
`200 OK`	Response body contains the requested automation.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The automation ID is malformed.
`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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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.

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. The caller doesn't have to be the creator of the automation.

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

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 path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`type`	Query	Type of entity. Valid value: `UNIT`.	String	Yes
`id`	Query	Unit ID. Filters the results to the automations associated with the specified unit. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String	Yes
`templateId`	Query	Filters the results to the ID of the automation template. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String	No
`expand`	Query	Get expanded information about each automation. If `expand` isn't included, Alexa returns a list of automation IDs. Valid values: `all`.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–100. Default: 20.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No
`access token`	Header	Access token for the customer. 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, along with a list of automations.

Response body examples

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

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

Response body parameters

Parameter	Description	Type
`results[]`	List of automations filtered by the query parameters.	Array of objects
`results[].automationId`	Identifies the automation.	String
`results[].associatedEntity`	(Optional) Associated entity, such as the unit, in which Alexa runs this automation. Returned when you include the `expand` parameter in the request.	String
`results[].associatedEntity.type`	Type of entity. Valid value: `UNIT`.	String
`results[].associatedEntity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}` .	String
`results[].automation.templateId`	(Optional) ID of the automation template from which you created the automation instance. Returned when you include the `expand` parameter in the request. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.template.{id}`.	String
`results[].automation.trigger`	(Optional) Trigger of the automation. Returned when you include the `expand` parameter in the request.	Trigger object
`results[].automation.operations`	(Optional) Operations of the automation template. Returned when you include the `expand` parameter in the request. Includes one of `serial`, `parallel`, or `operation` property.	Object
`results[].automation.operations.serial`	List of operations that Alexa invokes serially.	Array of Operation objects
`results[]..operations.parallel`	List of operations that Alexa invokes in parallel. Maximum number of elements in the array: 90.	Array of Operation objects
`results[].automation.operations.operation`	A single operation.	Operation object
`results[].friendlyName`	(Optional) Name of the automation. You can also define this field to distinguish automation instances.	NameValue object
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request with the same filter parameters as this request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains list of automations.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The automation ID is malformed.
`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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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 automation

Update the specified automation. At this time, you can update the data object only.

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 path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`automationId`	Path	Identifies the automation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.automation.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

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

Request body properties

Parameter	Description	Type	Required
`automation`	Defines the data to update.	Object	Yes
`automation.data`	Key/value mapping of the data used to resolve the variables defined in the template. For example, `${data.customUtterance}` refers to the `customerUtterance` field in `data`. Include a variable denoted by `${}`.	Object	No

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Automation updated successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The automation ID is malformed. A variable denoted by `${}` isn't found in data.
`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`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You 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.

Object definitions

The Automation API defines the following objects.

Error object

The Error object defines the error type and message included in the response when an error occurs.

The following example shows the response body.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

The Error object defines the following properties.

Property	Description	Type
`type`	Type of error that occurred. For specific error types, see the HTTP status code table for each operation.	String
`message`	Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String

NameValue object

The NameValue object is a container for names of objects.

The following table defines the properties of the object.

Property	Description	Type
`type`	Format of the value field. At this time, the only supported type is plain text. Valid values: `PLAIN`.	String
`value`	Name.	Object
`value.text`	Name given in plain text. Valid length: 1–100 characters. Valid values: UTF-8 encoding of letters, numbers, and the following special characters, with no spaces or periods: `_ - = # ; : ? @ &`	String

Notification object

The Notification object defines the announcements to play as part of the Alexa.Automation.Operation.Notification.Notify operation.

Parameter	Description	Type	Required
`type`	Notification delivery type. Valid value: `Announcement`.	String	Yes
`content`	Different variants of content for spoken and display purposes.	Object	Yes
`content.variants[]`	Notification content to deliver to the user.	Array of objects	Yes
`content.variants[].type`	Localized text input. Valid value: `SpokenText`.	String	Yes
`content.variants[].values[]`	Array of content values. Each element represents localized text input.	Array of objects	Yes
`content.variants[].values[].locale`	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
`content.variants[].values[].text`	Spoken text in plain text format. Maximum length: 1024 characters or 2048 bytes.	String	Yes

Operation object

The Operation object defines an action or task that Alexa invokes after trigger conditions are met. You choose the tasks from a set of defined operations.

Property	Description	Type
`type`	Type of operation. Valid values: `Alexa.Automation.Operation.Notification.Notify`, `Alexa.Automation.Operation.Brightness.SetBrightness`, `Alexa.Automation.Operation.Power.TurnOn`, `Alexa.Automation.Operation.Power.TurnOff`, `Alexa.Automation.Operation.Speaker.SetVolume`, `Alexa.Automation.Operation.Media.Stop`, `Alexa.Automation.Operation.Thermostat.SetTargetSetpoint`, `Alexa.Automation.Operation.Settings.SetDoNotDisturbState`.	String
`version`	Version of the operation.	String
`payload`	Based on the operation type, use the payload defined in the following sections.	Object

Alexa.Automation.Operation.Notification.Notify object

This operation sends 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.

The following example shows an example of a notification operation.

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!"
                        }]
                    }]
                }
            }]
        }
    }
}

The Alexa.Automation.Operation.Notification.Notify object defines the following properties.

Parameter	Description	Type	Required
`type`	Name of the announcement operation. Valid value: `Alexa.Automation.Operation.Notification.Notify`.	String	Yes
`version`	Version of the announcement operation payload.	String	Yes
`payload.notification`	Notification object.	Object	Yes
`payload.notification.variants`	List of announcements to play.	Array of Notification objects	Yes

Alexa.Automation.Operation.Brightness.SetBrightness object

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

The following example shows a set-brighness operation.

Copied to clipboard.

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

The Alexa.Automation.Operation.Brightness.SetBrightness object defines the following properties.

Parameter	Description	Type	Required
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1.	Array of strings	Yes
`endpoints[].id`	Identifies the target endpoint on which to perform the operation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`payload.brightness`	Identifies the percentage brightness to which to set the device. Valid value: 0–100 (inclusive).	Integer	Yes

Alexa.Automation.Operation.Power.TurnOn object

This object represents an operation that turns on an endpoint.

The following example shows a turn-on operation.

Copied to clipboard.

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

The Alexa.Automation.Operation.Power.TurnOn object defines the following properties.

Parameter	Description	Type	Required
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1.	Array of strings	Yes
`endpoints[].id`	Identifies the target endpoint on which to perform the operation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes

Alexa.Automation.Operation.Power.TurnOff object

This object represents an operation that turns off an endpoint.

The following example shows a turn-off operation.

Copied to clipboard.

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

The Alexa.Automation.Operation.Power.TurnOff object defines the following properties.

Parameter	Description	Type	Required
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1.	Array of strings	Yes
`endpoints[].id`	Identifies the target endpoint on which to perform the operation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes

Alexa.Automation.Operation.Speaker.SetVolume object

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

The following example shows a set-volume operation.

Copied to clipboard.

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

The Alexa.Automation.Operation.Speaker.SetVolume object defines the following properties.

Parameter	Description	Type	Required
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1.	Array of strings	Yes
`endpoints[].id`	Identifies the target endpoint on which to perform the operation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`volume`	Absolute volume to which to set the endpoint's speaker volume. Valid range: 0–100.	Integer	Yes

Alexa.Automation.Operation.Media.Stop object

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

The following example shows a media stop operation.

Copied to clipboard.

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

The Alexa.Automation.Operation.Media.Stop object defines the following properties.

Parameter	Description	Type	Required
`type`	Name of the operation. Valid value: `Alexa.DeviceControls.Stop`.	String	Yes
`version`	Version of the operation schema.	String	Yes
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1.	Array of strings	Yes
`endpoints[].id`	Identifies the target endpoint on which to perform the operation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes

Alexa.Automation.Operation.Thermostat.SetTargetSetpoint object

This object represents an operation that sets the target temperature on a single-set-point thermostat.

The following example shows an operation that sets a target temperature on a thermostat.

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"
        }
      }
    }
  }
}

The Alexa.Automation.Operation.Thermostat.SetTargetSetpoint object defines the following properties.

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

Alexa.Automation.Operation.Settings.SetDoNotDisturbState object

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

The following example shows a do-not-disturb operation.

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"
      }
    }
  }
}

The Alexa.Automation.Operation.Settings.SetDoNotDisturbState object defines the following properties.

Parameter	Description	Type	Required
`type`	Name of the operation. Valid value: `Alexa.DeviceControls.DoNotDisturb`.	String	Yes
`version`	Version of the operation schema.	String	Yes
`endpoints`	Set of endpoints on which to perform the operation. Maximum endpoints supported: 1.	Array of strings	Yes
`endpoints[].id`	Identifies the target endpoint on which to perform the operation. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`payload.value`	Whether to enable `DoNotDisturb` mode for target devices.	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.	String	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

Trigger object

The Trigger object defines the conditions that start the automation. You choose the tasks from a set of defined trigger types.

Property	Description	Type
`type`	Type of trigger. Valid values: .	String
`version`	Version of the trigger.	String
`payload`	Based on the trigger type, use the payload defined in the following subsections.	Object

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.

The following example shows a trigger based on a voice phrase.

Copied to clipboard.

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

The Alexa.Automation.Trigger.Voice.CustomUtterance object defines the following properties.

Parameter	Description	Type	Required
`type`	Name of the custom utterance trigger. Valid value: `Alexa.Trigger.CustomUtterance`.	String	Yes
`payload.utterances`	List of triggering utterances, in order of preference.	Array of strings	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.

The following example shows a trigger based on an absolute time.

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"
      }
   }
}

The Alexa.Automation.Trigger.Schedule.AbsoluteTime object defines the following properties.

Parameter	Description	Type	Required
`type`	Name of the absolute time schedule trigger. Valid value: `Alexa.Automation.Trigger.Schedule.AbsoluteTime`.	String	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 valid values, see List of TZ database time zones.	String	Yes
`payload.schedule.recurrence`	Specifies the recurrence schedule, in RRULE format.	String	Yes

Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation object

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

The following example shows a trigger based on sunrise.

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
    }
}

The Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation object defines the following properties.

Parameter	Description	Type	Required
`type`	Name of the absolute time schedule trigger. Valid value: `Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation`.	String	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.	Integer	Yes
`payload.longitude`	Longitude of the sunrise address.	Integer	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.

The following example shows a trigger based on sunset.

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
    }
}

The Alexa.Automation.Trigger.Schedule.SunsetInCustomLocation object defines the following properties.

Parameter	Description	Type	Required
`type`	Name of the absolute time schedule trigger. Valid value: `Alexa.Automation.Trigger.Schedule.SunsetInCustomLocation`.	String	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.	Integer	Yes
`payload.longitude`	Longitude of the sunset address.	Integer	Yes
`payload.timeOffset`	Time offset in minutes from the sunset time. The default is 0.	Long	No

Was this page helpful?

Provide feedback

Last updated: Dec 04, 2024