Capabilities API

As Alexa evolves and interfaces are added and updated to enable new features, the Capabilities API allows individual products to specify the interfaces and interface versions they support. This provides flexibility to target specific products with over-the-air (OTA) updates.

Use Cases

These are the primary use cases for the Capabilities API:

  1. To inform Alexa which interfaces and interface versions that your product supports during its out-of-box-experience (OOBE). This call must be made after you've obtained an access token, and before a connection with the Alexa Voice Service (AVS) is established.
  2. To inform Alexa which interfaces and interface versions that your product supports following an over-the-air (OTA) update. This ensures that a product will only receive directives and message payloads associated with the interface versions published to Alexa.

Frequency

The Capabilities API should be called as infrequently as possible, with the understanding that Alexa should have awareness of your product's supported interfaces and interface versions.

Use these guidelines to determine when it is appropriate to declare the complete list of interfaces that your product supports:

  • If your product has persistent storage, is aware of software updates, and can track previously declared interfaces and interface versions, the Capabilities API should only be called when interface versions are changed, or when support for interfaces are added/removed.
  • If your product has limited storage, and is not aware of previously declared interfaces and interface versions, the Capabilities API should be called on boot up following an OTA.
  • If your product does not have persistent storage, the Capabilities API should be called when the device boots.

Following a successful call, your product will receive an HTTP 204 response. If an HTTP 500 response is returned, your product should retry after 1 second, then back off exponentially until 256 seconds have elapsed and retry every 256 seconds until an HTTP 204 response is received.

Versioning

When new directives and events are added to or removed from an interface, or when message payloads are adjusted, impacted interfaces will be versioned independently using a MAJOR.MINOR scheme.

Minor Version

For backward compatible, non-breaking changes the MINOR number for an interface version is increased. A minor version change generally occurs when:

  • new directives and events are added to an interface
  • parameters are added to the message payload of a directive or event

For example, the Alerts interface was incremented from 1.0 to 1.1 to support Named Timers and Reminders. This change introduced new payload parameters to the SetAlert directive for enhanced functionality, however, it remained backward compatible and didn't break existing clients.

Major Version

When breaking changes are introduced, the MAJOR number for an interface version is increased. Here are a few examples of what would result in a major version change:

  • existing directives and events are removed from an interface
  • the data type for an existing parameter is changed
  • parameters are removed from the message payload of an existing directive or event

For example, the SpeechRecognizer interface was incremented from 1.0 to 2.0 when the initiator parameter's type was changed from a string to an object in ExpectSpeech directives.

Supported Interface Versions

This table lists supported versions of each interface. Changes from version to version are cataloged on each interface page when introduced, and recorded in the documentation changelog. Use the links in the table below to learn more.

All interfaces and interface versions that your product supports must be included in each Capabilities API call. After a successful call to the Capabilities API, Alexa will use the declared versions for each interface until the next call to the Capabilities API is made.

Interface Current Version Supported Versions Required
Alerts☩ 1.3 1.0, 1.1, 1.3 Yes
AudioActivityTracker 1.0 1.0 Required for Focus Management
AudioPlayer 1.0 1.0 Yes
Bluetooth☩ 1.0 1.0 Optional
EqualizerController 1.0 1.0 Optional
InputController 3.0 3.0 Optional
InteractionModel 1.0 1.0 Optional
Notifications 1.0 1.0 Yes
PlaybackController 1.1 1.0, 1.1 Yes
Settings 1.0 1.0 Yes
Speaker 1.0 1.0 Yes
SpeechRecognizer 2.0 1.0, 2.0 Yes
SpeechSynthesizer 1.0 1.0 Yes
System 1.1 1.0, 1.1 Yes
TemplateRuntime☩ 1.0 1.0 Optional
VisualActivityTracker 1.0 1.0 Required for Focus Management

Request

Method PUT
URI https://api.amazonalexa.com/v1/devices/@self/capabilities
Data Format JSON

Header Parameters

Parameter Description Type Required
Content-Type Specifies the format of the message returned by Alexa. Accepted value: application/json. string Yes
Content-Length This indicates the size of the entity-body, in bytes, sent to Alexa. integer Yes
Authorization This is the access token obtained from Login with Amazon (LWA) during authorization. See Authorization for a complete list of authorization options for AVS. string Yes

Sample Request Headers

Content-Type: application/json  
Content-Length: {{INTEGER}}  
Authorization: Bearer {{LWA_ACCESS_TOKEN}}

Body Parameters

Parameter Description Type Required
envelopeVersion This value informs Alexa that you are using a specific version of the APIs. As a result, messages returned by Alexa will conform to the message specification for the declared version. Accepted value: 20160207. string Yes
capabilities This is a list of objects, each representing an interface. All interfaces that your product supports must be included in this list. If an interface is not declared, Alexa will determine whether or not the interface is available for use and subsequently what version of the message is sent. Learn more >. list Yes
capabilities[i].type Accepted value: AlexaInterface. string Yes
capabilities[i].interface Specifies an Alexa interface. Accepted values: All interfaces listed in the Alexa Voice Service Overview. string Yes
capabilities[i].version The version of the interface that your product supports. Important: Each interface is versioned independently, and the contents of message payloads vary from one version to the next. string Yes

Sample Request Body

{
    "envelopeVersion": "20160207",
    "capabilities": [
        {
            "type": "AlexaInterface",
            "interface": "Alerts",
            "version": "1.1"
        },
        {
            "type": "AlexaInterface",  
            "interface": "AudioActivityTracker",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "AudioPlayer",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "Bluetooth",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "EqaulizerController",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "Alexa.InputController",
            "version": "3.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "InteractionModel",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "Notifications",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "PlaybackController",
            "version": "1.1"
        },
        {
            "type": "AlexaInterface",
            "interface": "Settings",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "Speaker",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "SpeechRecognizer",
            "version": "2.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "SpeechSynthesizer",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "System",
            "version": "1.1"
        },
        {
            "type": "AlexaInterface",
            "interface": "TemplateRuntime",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "VisualActivityTracker",
            "version": "1.0"
        }
        ...
        // This should be a complete list of
        // interfaces that your product supports.
        // All required interfaces must be declared.
    ]
}

Response

Alexa will respond to all requests with an HTTP status code.

Status Codes

HTTP Status Code Message Description
204 No Content The request was successfully processed.
400 Bad Request There was an issue with the payload. A 400 error will return a JSON document that includes an error object with details describing the error.
403 Forbidden Authentication failed.
500 Internal Service Error An unknown problem was encountered when processing or storing the capabilities. Retry after 1 second, then back off exponentially until 256 seconds and retry every 256 seconds until an HTTP 204 response is received.

Error Messages

A 400 error will return a JSON document that includes a single error object with details describing the error.

Error Message Description
"Invalid envelope version" An invalid parameter was published for envelopeVersion.
"Missing capabilities" The capabilities list is missing.
"{field} cannot be null or empty" The type, interface, and/or version declared are invalid.
"Unknown interface {name}, type {x}, version {number} combination" An invalid combination of type, interface, and/or version were provided.

400 Error Structure

{
    "error": {
        "message": "{{STRING}}"
    }
}