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
• Frequency
• Versioning
  • Minor Version
  • Major Version
• Legacy Devices
• Request
  • Header Parameters
  • Body Parameters
• Response
  • Status Codes
  • Error Messages

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

Header Parameters

Sample Request Headers

Content-Type: application/json  
Content-Length: {{INTEGER}}  
x-amz-access-token: {{LWA_ACCESS_TOKEN}}

Body Parameters

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

Error Messages

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

400 Error Structure

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