Capabilities API

Warning: The Capabilities API has been deprecated in favor of Alexa.Discovery, which describes the circumstances under which migrating is immediately required. No new AVS integrations should use the Capabilities API.

Alexa.Discovery must be used for all new AVS integrations, and no capability support should be configured in the Developer Console. Previously registered products can use the Developer Console to assert capabilities only as a mechanism to correct bugs until all individual devices can adopt Alexa.Discovery.

When your device begins making successful calls to Alexa.Discovery, Alexa will no longer assume support for required interfaces, such as SpeechRecognizer or SpeechSynthesizer. Additionally, for the individual device using Alexa.Discovery, no capabilities set in the AVS Developer Console will apply.

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

Important: All new products should use the Capabilities API to assert support for Alexa capability interfaces instead of the Developer Console. Previously registered products can use the Developer Console to assert capabilities only as a mechanism to correct bugs until all individual devices can adopt the Capabilities API.

These are the primary use cases for the Capabilities API:

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

Warning: When your device begins making successful calls to the Capabilities API, Alexa will no longer assume support for required interfaces, such as SpeechRecognizer or SpeechSynthesizer. Additionally, for the individual device calling the Capabilities API, no capabilities set in the AVS Developer Console will apply.

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.

Warning: We strongly discourage calling the Capabilities API on every reconnection to AVS.

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.

Important: To provide end users with the correct experience, it is critical that your device informs Alexa of adoption of minor version changes, even though as a non-breaking change, failing to do so would not cause an error state in your device's software.

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

Important: If your device failed to assert support for its capabilities since the last time an access token was acquired, it will be subject to the logic above. Devices running software that expect different or higher versions of the above interfaces may thereby end up in error states or manifest degraded user experiences.

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

Note: This sample is representative, not exhaustive. Your device must include all supported interfaces in the capabilities list.

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

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023