Automation API Reference


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.

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.

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.

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).

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.

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 IETF BCP 47 format.

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

Locale in which the spoken text is rendered, in IETF BCP 47 format.

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?

Last updated: Nov 28, 2023