Capabilities API

The Capabilities API provides the mechanism for declaring support for new Alexa interfaces and versions at the individual device level. This allows each unit of your product to take advantage of new Alexa features as soon as its software is updated, rather than waiting for enough devices to have their software updated and then asserting support for Alexa interface changes at the overall product level in the AVS Developer Console.

Use Cases

These are the primary use cases for the Capabilities API:

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

In both cases, the Capabilities API call is required to provide a complete list of all capability interfaces your device implements: For every message your device processes (including events, directives, and context entries), the value of the namespace field in the header objects must appear in the list of your device's capabilities.

Frequency

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

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

  • Every time that your device acquires a new access token due to an association with a new or different Amazon customer account, the capabilities associated with your device are cleared and the Capabilities API must be called. This should be considered an OOBE.
  • If your device 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 support for interfaces is added, removed, or changed.
  • If your device has limited storage and is not aware of previously declared interfaces and interface versions, the Capabilities API should be called on startup following a software update.
  • If your device does not have persistent storage, the Capabilities API should be called on startup.

Following a successful call, your device will receive an HTTP 204 No Content response. If an HTTP 500 Internal Service Error response is returned, then your device should retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until an HTTP 204 response is received.

Versioning

See the Versioning documentation for more information.

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.

Changes from version to version are cataloged on each interface page when introduced, and recorded in the documentation changelog.

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.

Legacy Devices

Adoption of the Capabilities API is required to integrate support for new and changed Alexa interfaces into your device.

However, if you are no longer updating your product's software, implementing the Capabilities API is unnecessary. In that case, or if you intend to but have not yet implemented the Capabilities API, Alexa will infer support for specific interfaces and versions based on the following logic:

  • Required interfaces will be assumed to be at version 1.0:
    • Alerts 1.0
    • AudioPlayer 1.0
    • Notifications 1.0
    • PlaybackController 1.0
    • Settings 1.0
    • Speaker 1.0
    • SpeechRecognizer 1.0
    • SpeechSynthesizer 1.0
    • System 1.0
  • Capabilities set for all units of your product through the AVS Developer Console will imply the following versions:
    • Named Timers and Reminders: Alerts 1.3 (Note that this will override the default assumption of Alerts 1.0 as a required interface.)
    • Bluetooth: Bluetooth 1.0
    • Display Cards: TemplateRuntime 1.0

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
x-amz-access-token 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}}  
x-amz-access-token: {{LWA_ACCESS_TOKEN}}

Body Parameters

Parameter Description Type Required
envelopeVersion This value informs Alexa which version of AVS's message format and interaction model your device uses. The format's specifications are implicit in the API documentation, controlling the structure outside of any individual interface's payload objects. All events and directives must conform to the declared version.
Accepted value:
20160207		 string Yes
capabilities This is a list of objects, each representing a capability interface. All interfaces that your device supports must be included in this list. The values of each top-level field inside these objects are defined by the interface. 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 device supports. Important: Each interface is versioned independently, and the contents of message payloads vary from one version to the next. string Yes
capabilities[i].configurations If the version of the interface defines any optional interface-specific configurations, this object informs Alexa of how the interface is implemented in device software. The schema for configurations belongs to the interface spec. object No

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.2"
        },
        {
            "type": "AlexaInterface",
            "interface": "TemplateRuntime",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "VisualActivityTracker",
            "version": "1.0"
        }
        ...
        // This should be a complete list of
        // interfaces that your device 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, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter 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}}"
    }
}