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.

API endpoint

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

Authentication

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.

Operations

The Knowledge Skill API includes the following operations.

Operation HTTP method and URI

Import data

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

Get the status of all imports

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

Get the status of a specific import

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

Get template IDs

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

Import data

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

Request

To add the selected template to your knowledge skill and import new data to the template, you make a POST request to the imports resource.

Request header example

Copied to clipboard.

POST /v1/skills/{skillId}/knowledge/imports
Host: api.{region}amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

skillId

ID of your knowledge skill.

String

Yes

Request body example

Copied to clipboard.

{
  "contentType": "text/csv",
  "template": {
    "id": "example-template-id"
  },
  "importContent": "text-of-content-to-import"
}

Request body parameters

Parameter Description Type Required

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

Object that contains the template ID and data.

Object

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

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. For errors, see HTTP status codes.

HTTP status codes

Status Message Description

202

Accepted

The request was accepted.

400

Bad request

A required parameter isn't present, or is badly formatted.

401

Unauthorized

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

Forbidden

The service doesn't authorize the request.

404

Not found

The requested resource isn't found.

409

Conflict

The request couldn't be completed due to a conflict with the current state of the target resource.

429

Too many requests

There are too many requests received.

500

Internal server error

The server encountered an unexpected condition that prevented it from fulfilling the request.

503

Service unavailable

The server is currently unable to handle the request.

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

To get the status and percentage completion of all active and completed imports for a knowledge skill, you make a GET request to the imports resource.

Request header example

Copied to clipboard.

GET /v1/skills/{skillId}/knowledge/imports?nextToken={nextToken}&maxResults={maxResults}&status={status}
Host: api.{region}amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

skillId

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

Request body parameters

The request body is empty.

Response

A successful request returns 200 Success. For errors, see HTTP status codes.

Response body example

{
  "knowledgeImports": [
    {
      "errors": ["error-1", "error-2"],
      "id": "example-template-id-1",
      "status": "SUCCEEDED"
    },
    {
      "errors": ["error-1", "error-2"],
      "id": "example-template-id-2",
      "status": "FAILED"
    }  
  ],
  "paginationContext": {
    "nextToken": "example-next-token",
    "previousToken": "example-previous-token",
    "totalCount": 2
  }
}

Response body parameters

Parameter Description Type

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

knowledgeImports[*].id

Unique identifier for the import.

String

knowledgeImports[*].status

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

String

paginationContext.nextToken

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

String

paginationContext.previousToken

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

String

paginationContext.totalCount

Total number of results that matched the request query.

Integer

HTTP status codes

Status Message Description

200

Success

The request succeeded.

400

Bad request

A required parameter isn't present, or is badly formatted.

401

Unauthorized

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

Forbidden

The service doesn't authorize the request.

404

Not found

The requested resource isn't found.

429

Too many requests

There are too many requests received.

500

Internal server error

The server encountered an unexpected condition that prevented it from fulfilling the request.

503

Service unavailable

The server is currently unable to handle the request.

Get the status of a specific import

Gets the status and percentage completion of a specific import.

Request

To get the status and percentage completion of a specific import for a knowledge skill, you make a GET request to the imports resource.

Request header example

Copied to clipboard.

GET /v1/skills/{skillId}/knowledge/imports/{importId}
Host: api.{region}amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

skillId

ID of your knowledge skill.

String

Yes

importId

ID of the import for which to get the status.

String

Yes

Request body parameters

The request body is empty.

Response

A successful request returns 200 Success. For errors, see HTTP status codes.

Response body example

{ 
  "knowledgeImport": {
    "errors": ["error-1", "error-2"],      
    "progress": 50,
    "status": "PENDING" 
  }
}

Response body parameters

Parameter Description Type

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

Percentage completion of the import.

Integer

status

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

String

HTTP status codes

Status Message Description

200

Success

The request succeeded.

400

Bad request

A required parameter isn't present, or is badly formatted.

401

Unauthorized

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

Forbidden

The service doesn't authorize the request.

404

Not found

The requested resource isn't found.

429

Too many requests

There are too many requests received.

500

Internal server error

The server encountered an unexpected condition that prevented it from fulfilling the request.

503

Service unavailable

The server is currently unable to handle the request.

Get template IDs

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

Request

To return the IDs of templates that you added to your knowledge skill, you make a GET request to the templates resource.

Request header example

Copied to clipboard.

GET /v1/skills/{skillId}/knowledge/templates?nextToken={nextToken}&maxResults={maxResults}
Host: api.{region}amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

skillId

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

Request body parameters

The request body is empty.

Response

A successful request returns 200 Success. For errors, see HTTP status codes.

Response body example

{
  "paginationContext": {
    "nextToken": "example-next-token",
    "previousToken": "example-previous-token",
    "totalCount": 2
  },
  "templates": [
    {
      "id": "example-template-id-1",
      "name": "example-template-name-1"		
    },
    {
      "id": "example-template-id-2",
      "name": "example-template-name-2"   
    }
  ]
}

Response body parameters

Parameter Description Type

paginationContext.nextToken

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

String

paginationContext.previousToken

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

String

paginationContext.totalCount

Total number of results that matched the request query.

Integer

templates[*].id

Unique identifier of the template.

String

templates[*].name

Name of the template.

String

HTTP status codes

Status Message Description

200

Success

The request succeeded.

400

Bad request

A required parameter isn't present, or is badly formatted.

401

Unauthorized

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

Forbidden

The service doesn't authorize the request.

404

Not found

The requested resource isn't found.

429

Too many requests

There are too many requests received.

500

Internal server error

The server encountered an unexpected condition that prevented it from fulfilling the request.

503

Service unavailable

The server is currently unable to handle the request.