Migration of SMAPI from v0 to v1

Version 1 of the Skill Management API (SMAPI v1) allows the developer to obtain more information about a skill and its sub-resources, and to perform more specific operations. Version 1 is interoperable with Version 0, although the interfaces for the API calls have changed in many cases. Developers are encouraged to migrate to SMAPI v1 when possible. Refer to the SMAPI v1 documentation for each operation that you have used in your code to ensure that you make the appropriate updates.

The following changelog lists the differences between SMAPI v0 and SMAPI v1.

Name changes

The key skillManifest in requests/responses for v0 has been renamed to manifest in v1 requests/responses.

Changes to APIs

Skill Operations

For more details about each API, see Skill Manifest REST API Reference.

SMAPI v1 supports development and live (case-sensitive) as stage values for all GET operations that expect stage input. Otherwise, only development (case-sensitive) is a supported value for stage. SMAPI v0 works with development stage implicitly, and therefore the stage parameter is not used.

Create a Skill

  • v0: POST /v0/skills

  • v1: POST /v1/skills

Get a Skill Manifest

  • v0: GET /v0/skills/{skillId}

  • v1: GET /v1/skills/{skillId}/stages/{stage}/manifest

New error response:

  • HTTP/1.1 303 See Other when this API is called, and the skill creation process has not yet completed.

Update a Skill

  • v0: PUT /v0/skills/{skillId}

  • v1: PUT /v1/skills/{skillId}/stages/{stage}/manifest

New error responses:

  • HTTP/1.1 409 Conflict when an update is already is progress.

  • HTTP/1.1 403 Forbidden when the request cannot be fulfilled.

Get Skill Status

Version 1 returns manifest as well as interactionModel status. It also supports optional filtering by resource (interactionModel or manifest).

  • v0: /v0/skills/{skillId}/status

  • v1: /v1/skills/{skillId}/status?resource=name1&resource=name2

In the response, lastModified key has been renamed to lastUpdateRequest. The 'time' field is not returned in lastUpdateRequest. The error field in v0 has been replaced with errors in v1 which is now a list of error objects.

See Get skill status.

Delete a skill

  • v0: DELETE /v0/skills/{skillId}/

  • v1: DELETE /v1/skills/{skillId}/

New error responses:

Instead of HTTP/1.1 400 Bad Request as in v0, SMAPI v1 returns HTTP/1.1 403 Forbidden when there is a live stage, or if the skill is in certification, or if model building is in progress.

List skills

Version 1 optionally allows the developer to retrieve listings for specified skill(s) under a specific vendorId, rather than skills page by page under that vendorId.

  • v0: GET /v0/skills?vendorId={vendorId}&maxResults={num}&nextToken={token}

  • v1: GET /v1/skills?vendorId={vendorId}&maxResults={num}&nextToken={token} OR GET /v1/skills?vendorId={vendorId}&skillId={skillId1}&skillId={skillId2}

Additional skill information fields (apis and publicationStatus) are included in the response.

Account Linking

The Account Linking Operations APIs now accept stage as a parameter. For details, see Account Linking Management.

The accountLinkingRequest structure now contains redirectUrls as a possible field. For details, see Account Linking Request.

Get account linking partner

  • v0: GET /v0/skills/{skillId}/accountLinkingClient

  • v1: GET /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

The AccountLinkingInformation in the response includes a new field, defaultTokenExpirationInSeconds, which indicates the number of seconds that the accessToken is valid. If the Oauth client returns "expires_in", it overwrites the defaultTokenExpirationInSeconds parameter.

Set account linking partner

  • v0: PUT /v0/skills/{skillId}/accountLinkingClient

  • v1: PUT /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

Version 1 throws HTTP/1.1 403 Forbidden when the skill is in certification, whereas v0 throws HTTP/1.1 400 Bad Request.

Delete account linking partner

New to v1.

  • v1: DELETE /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

Skill enablement operations

This set of APIs, which allows you to programmatically manage skill enablements rather than rely on the developer console, is new to v1. See Skill Enablement Operations.

Interaction Model Operations

The Interaction Model Operations APIs now accept stage as a parameter. For details, see Interaction Model Management.

Get interaction model

  • v0: GET /v0/skills/{skillId}/interactionModel/locales/{locale}

  • v1: GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

Head interaction model

  • v0: HEAD /v0/skills/{skillId}/interactionModel/locales/{locale}

  • v1: HEAD /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

The successful status codes have changed as follows:

  • v0: HTTP/1.1 200 OK

  • v1: HTTP/1.1 204 No Content

Update an interaction model

The verb for updating an interaction model has changed.

  • v0: POST /v0/skills/{skillId}/interactionModel/locales/{locale}

  • v1: PUT /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

The API returns HTTP/1.1 403 Forbidden when the request cannot be fulfilled.

Interaction model building status

SMAPI v1 does not provide dedicated api to get interaction model building status. However, it can be retrieved using 'get skill status' api. See Get skill status.

v1 API doesn't take locale as input and therefore returns status for all available locales in response. The status value in case the last interaction model was built successfully, has been renamed from SUCCESS in v0 to SUCCEEDED in v1.

  • v0: GET /v0/skills/{skillId}/interactionModel/locales/{locale}/status

  • v1: GET /v1/skills/{skillId}/status?resource=interactionModel

Skill Certification Operations

The error responses have changed from HTTP/1.1 400 Bad Request to HTTP/1.1 403 Forbidden. For details, see Skill Certification Operations.

Submit skill for certification

v0: POST /v0/skills/{skillId}/submit

v1: POST /v1/skills/{skillId}/submit

Withdraw skill from certification

v0: POST /v0/skills/{skillId}/withdraw

v1: POST /v1/skills/{skillId}/withdraw

ASK CLI Changes

All of the SMAPI v1 changes described on this page have corresponding changes in the ASK CLI Command Reference.

Last updated: Jan 03, 2023