Knowledge Skill SMAPI Operations

You can create and update knowledge skills programmatically by using the Alexa Skill Management API (SMAPI).

For a walkthrough of how to use SMAPI to create a simple knowledge skill, see Get started.

Endpoint

The endpoint for SMAPI is https://api.amazonalexa.com.

Each API request must have an Authorization header that contains an access token retrieved from Login with Amazon. For details about obtaining an access token, see Get an Access Token for SMAPI.

Import data

Adds the selected template to your knowledge skill (if it's not already added) and imports new data to the template. The imported data overwrites all data current associated with the template. For details about templates and how to format your data, see Knowledge Skill Templates.

Request

HTTP method and URI path

POST /v1/skills/{skillId}/knowledge/imports

Request body structure

{
  "contentType": string,
  "template": {
    "id": string
  }
  "importContent":string
}

Request parameters

Field Description Type Required

skillId

The ID of your knowledge skill.

String

Yes

contentType

MIME type of the content that is being imported into this knowledge skill. The only supported MIME type is text/csv.

String

Yes

template.id

ID of the knowledge skill template that the data uses. The following table shows the ID that corresponds to each knowledge skill template.

Template ID

Company Locations

2d1adc64-be18-4d3e-a385-e6b8a05e07a8

Events

f9014c76-7cdc-4e6c-ab94-a7873127c25e

Glossary

f184839a-c0ff-46d7-84b9-ca557f92519f

How To

33d0eb44-2451-457c-8aa0-1a53a7067e8b

Inventory

dbdf3800-a805-4214-be1c-d98a966cd3f6

Menu Items

cbfc7250-2981-11eb-adc1-0242ac120002

Menus

76b8edca-a1da-11ea-bb37-0242ac130002

People Directory

45c2ed23-907b-4eb1-b107-f895c327aea8

Points of Interest

cc8157c7-59b1-401b-bd68-08f8c2ba4ba8

Policies

1845aac8-5ed9-11eb-ae93-0242ac130002

Products

8e2d16c5-ab91-42f7-9e99-27ed15479559

Projects

fd716d02-3b80-11eb-adc1-0242ac120002

Property Information

9f3324ac-7619-4785-967c-c006f5e07e33

String

Yes

importContent

The text of the CSV file you want to import, as a string.

String

Yes

Response

A successful request returns 202 Success. The Location header contains a string you can use to track the import.

Errors

Code Description

400

Bad request. Returned when a required parameter is not present, or is badly formatted.

401

The authorization token is invalid/expired or doesn't have access to the resource. To obtain a new access token, use a refresh token. For details, see Get an Access Token for SMAPI.

403

Request is forbidden.

404

The resource being requested is not found.

409

The request could not be completed due to a conflict with the current state of the target resource.

429

Too many requests received.

500

Internal server error.

503

Service unavailable.

Get the status of all imports

Gets the status and percentage completion of all active and completed imports for a knowledge skill. The results are returned as an optionally paginated list of import IDs. You can also apply filters to the imports returned by your request.

Request

HTTP method and URI path

GET /v1/skills/{skillId}/knowledge/imports?nextToken={nextToken}&maxResults={maxResults}&status={status}

Request parameters

Field Description Type Required

skillId

The ID of your knowledge skill.

String

Yes

nextToken

Token that you can use in the next request as the continuation token to list the next page of results.

String

No

maxResults

Total number of results that matched the request query.

Integer

No

status

Status of the knowledge skill import request.
Valid values: PENDING, IN_PROGRESS, FAILED, SUCCEEDED

String

No

Response

A successful request returns 200 Success.

Response body structure

{
  "knowledgeImports": [
    {
      "errors": [string, string,...],
      "id": string,
      "status": string enum
    },
    ...    
  ],
  "paginationContext": {
    "nextToken": string,
    "previousToken": string,
    "totalCount": integer
  }
}

Response body fields

Field Description Type

paginationContext.totalCount

Total number of results that matched the request query.

Integer

paginationContext.nextToken

A value that you can use in the next request as the continuation token to list the next page of results.

String

paginationContext.previousToken

A value that you can use in the next request as the token to list the previous set of results.

String

knowledgeImports[*].id

Unique identifier for the import.

String

knowledgeImports[*].status

The status of the import.
Valid values: PENDING, IN_PROGRESS, FAILED, SUCCEEDED

String

knowledgeImports[*].errors

List of import error messages, which explain the changes you need to make to your file to be able to import it.

Array of strings

Errors

Code Description

400

Bad request. Returned when a required parameter is not present, or is badly formatted.

401

The authorization token is invalid/expired or doesn't have access to the resource. To obtain a new access token, use a refresh token. For details, see Get an Access Token for SMAPI.

403

Request is forbidden.

404

The resource being requested is not found.

429

Too many requests received.

500

Internal server error.

503

Service unavailable.

Get the status of a specific import

Gets the status and percentage completion of a specific import.

Request

HTTP method and URI path

GET /v1/skills/{skillId}/knowledge/imports/{importId}

Request parameters

Field Description Type Required

skillId

The ID of your knowledge skill.

String

Yes

importId

The ID of the import for which to get the status.

String

Yes

Response

A successful request returns 200 Success.

Response body structure

{ 
  "knowledgeImport": {
    "errors": [string, string,...],      
    "progress": integer,
    "status": string enum 
  }
}

Response body fields

Field Description Type

status

The status of the import.
Valid values: PENDING, IN_PROGRESS, FAILED, SUCCEEDED

String

errors

List of import error messages, which explain the changes you need to make to your file to be able to import it.

Array of strings

progress

The percentage completion of the import.

Integer

Errors

Code Description

400

Bad request. Returned when a required parameter is not present, or is badly formatted.

401

The authorization token is invalid/expired or doesn't have access to the resource. To obtain a new access token, use a refresh token. For details, see Get an Access Token for SMAPI.

403

Request is forbidden.

404

The resource being requested is not found.

429

Too many requests received.

500

Internal server error.

503

Service unavailable.

Get template IDs

Returns the IDs of templates that you have added to your knowledge skill, including templates that you haven't imported data to yet.

Request

HTTP method and URI path

GET /v1/skills/{skillId}/knowledge/templates?nextToken={nextToken}&maxResults={maxResults}

Request parameters

Field Description Type Required

skillId

The ID of your knowledge skill.

String

Yes

nextToken

Token that you can use in the next request as the continuation token to list the next page of results.

String

No

maxResults

Total number of results that matched the request query.

Integer

No

Response

A successful request returns 200 Success.

Response body structure

{
  "paginationContext": {
    "previousToken": string,
    "nextToken": string,
    "totalCount": integer
  },
  "templates": [
    {
      "id": string,
      "name": string		
    },
    ...	
  ]
}

Response body fields

Field Description Type

paginationContext.totalCount

Total number of results that matched the request query.

Integer

paginationContext.nextToken

A value that you can use in the next request as the continuation token to list the next page of results.

String

paginationContext.previousToken

A value that you can use in the next request as the token to list the previous set of results.

String

templates[*].id

Unique identifier of the template.

String

templates[*].name

Name of the template.

String

Errors

Code Description

400

Bad request. Returned when a required parameter is not present, or is badly formatted.

401

The authorization token is invalid/expired or doesn't have access to the resource. To obtain a new access token, use a refresh token. For details, see Get an Access Token for SMAPI.

403

Request is forbidden.

404

The resource being requested is not found.

429

Too many requests received.

500

Internal server error.

503

Service unavailable.