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
- Authentication
- Operations
- Import data
- Get the status of all imports
- Get the status of a specific import
- Get template IDs
- Related topics
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
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
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 |
|---|---|---|---|
|
|
ID of your knowledge skill. |
String |
Yes |
Request body example
{
"contentType": "text/csv",
"template": {
"id": "example-template-id"
},
"importContent": "text-of-content-to-import"
}
Request body parameters
| Parameter | Description | Type | Required | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
MIME type of the content that is being imported into this knowledge skill. The only supported MIME type is |
String |
Yes | ||||||||||||||||||||||||||||
|
|
Object that contains the template ID and data. |
Object |
Yes | ||||||||||||||||||||||||||||
|
|
ID of the knowledge skill template that the data uses. The following table shows the ID that corresponds to each knowledge skill template.
|
String |
Yes | ||||||||||||||||||||||||||||
|
|
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 |
|---|---|---|
|
|
|
The request was accepted. |
|
|
|
A required parameter isn't present, or is badly formatted. |
|
|
|
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. |
|
|
|
The service doesn't authorize the request. |
|
|
|
The requested resource isn't found. |
|
|
|
The request couldn't be completed due to a conflict with the current state of the target resource. |
|
|
|
There are too many requests received. |
|
|
|
The server encountered an unexpected condition that prevented it from fulfilling the request. |
|
|
|
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
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 |
|---|---|---|---|
|
|
ID of your knowledge skill. |
String |
Yes |
|
|
Token that you can use in the next request as the continuation token to list the next page of results. |
String |
No |
|
|
Total number of results that matched the request query. |
Integer |
No |
|
|
Status of the knowledge skill import request. |
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 |
|---|---|---|
|
|
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 |
|
|
Unique identifier for the import. |
String |
|
|
Status of the import. |
String |
|
|
Value that you can use in the next request as the continuation token to list the next page of results. |
String |
|
|
Value that you can use in the next request as the token to list the previous set of results. |
String |
|
|
Total number of results that matched the request query. |
Integer |
HTTP status codes
| Status | Message | Description |
|---|---|---|
|
|
|
The request succeeded. |
|
|
|
A required parameter isn't present, or is badly formatted. |
|
|
|
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. |
|
|
|
The service doesn't authorize the request. |
|
|
|
The requested resource isn't found. |
|
|
|
There are too many requests received. |
|
|
|
The server encountered an unexpected condition that prevented it from fulfilling the request. |
|
|
|
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
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 |
|---|---|---|---|
|
|
ID of your knowledge skill. |
String |
Yes |
|
|
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 |
|---|---|---|
|
|
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 |
|
|
Percentage completion of the import. |
Integer |
|
|
Status of the import. |
String |
HTTP status codes
| Status | Message | Description |
|---|---|---|
|
|
|
The request succeeded. |
|
|
|
A required parameter isn't present, or is badly formatted. |
|
|
|
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. |
|
|
|
The service doesn't authorize the request. |
|
|
|
The requested resource isn't found. |
|
|
|
There are too many requests received. |
|
|
|
The server encountered an unexpected condition that prevented it from fulfilling the request. |
|
|
|
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
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 |
|---|---|---|---|
|
|
ID of your knowledge skill. |
String |
Yes |
|
|
Token that you can use in the next request as the continuation token to list the next page of results. |
String |
No |
|
|
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 |
|---|---|---|
|
|
Value that you can use in the next request as the continuation token to list the next page of results. |
String |
|
|
Value that you can use in the next request as the token to list the previous set of results. |
String |
|
|
Total number of results that matched the request query. |
Integer |
|
|
Unique identifier of the template. |
String |
|
|
Name of the template. |
String |
HTTP status codes
| Status | Message | Description |
|---|---|---|
|
|
|
The request succeeded. |
|
|
|
A required parameter isn't present, or is badly formatted. |
|
|
|
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. |
|
|
|
The service doesn't authorize the request. |
|
|
|
The requested resource isn't found. |
|
|
|
There are too many requests received. |
|
|
|
The server encountered an unexpected condition that prevented it from fulfilling the request. |
|
|
|
The server is currently unable to handle the request. |