Knowledge Skill SMAPI Reference

You can use the Alexa Skill Management API (SMAPI) to take the following types of actions on knowledge skills:

  • Common actions – These actions include creating, updating, and enabling skills. For details, see Get Started with SMAPI.
  • Actions specific to knowledge skills – These actions include importing data and retrieving the knowledge skill templates that the skill uses. For details, see Knowledge Skill SMAPI Operations.

For an overview of knowledge skills, see Knowledge Skill Overview.

Manage knowledge skills by using SMAPI

When you use SMAPI to manage knowledge skills, you work with the following four components:

  • Authentication – You must provide an access token in the header of your API requests. For details, see Get an Access Token for SMAPI.
  • Skill resource operations – You can create knowledge skills by using SMAPI skill resource operations and a knowledge skill manifest. You can also use these operations to update your skill manifest, retrieve knowledge skills, and delete knowledge skills.
  • Knowledge skill SMAPI operations – You can import data, poll for the status of one or more imports, and retrieve template IDs.
  • Skill enablement – For testing, you can enable your knowledge skill on devices associated with your developer account. For details, see Enable a skill in the SMAPI documentation. You can also enable and test your knowledge skill on devices associated with Alexa for Hospitality or Alexa for Residential accounts. For details, see Enable a skill in the Alexa for Hospitality documentation or Enable a skill in the Alexa for Residential documentation.

Get started

The following walkthrough shows how to use SMAPI to create a simple knowledge skill, import data to the skill, get the status of the import, and enable the skill for testing. For details and a complete list of these operations, see Knowledge Skill SMAPI Operations.

Step 1: Generate an access token

Every time you make an HTTPS request to SMAPI, you must provide an access token in the header of the API request. You can retrieve an access token by using the Alexa Skills Kit Command Line Interface (ASK CLI).

To get an access token by using the ASK CLI

  1. Install the ASK CLI.
  2. Configure a security profile with LWA.
  3. Get the client ID and client secret of the security profile from the LWA console.
  4. On a command line, enter ask util generate-lwa-tokens.
  5. Enter the LWA client ID and client secret that you copied from your LWA security profile in step 3.
  6. In the browser that opens, sign in with the username and password for your Amazon developer account.
  7. On the access page that opens, click Allow.
  8. Close the browser and return to the command line interface.
    The command line displays an access token and refresh token to include in the header of your API requests.

Step 2: Create a knowledge skill

Next, you submit the following request to create the skill.

POST https://api.amazonalexa.com/v1/skills

As with any Alexa skill, you must include a skill manifest in the body of this request. For details about fields specific to knowledge skills, see Knowledge Skill Manifest. The following example shows a knowledge skill manifest.

{
  "vendorId": "<your vendorId>",
  "manifest": {
    "publishingInformation": {
      "locales": {
        "en-US": {
          "name": "Sample Knowledge Skill",
          "description": "This skill is a sample knowledge skill."
        }
      },
      "distributionCountries": [
                "US"
      ]
    },
    "apis": {
      "knowledge": {
        "locales": {
          "en-US": {
            "answerAttribution": "Insert optional attribution phrase."
          }
        }
      }
    },
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "isExportCompliant": true,
      "isChildDirected": false,
      "usesPersonalInfo": false
    }
  }
}

A successful request returns a 202 status code and a skill ID. For details about this request, see Create a skill.

Step 3: Import data to your knowledge skill

To import data to the knowledge skill you created, you submit the following request.

POST https://api.amazonalexa.com/v1/skills/{skillId}/knowledge/imports

To understand how to format your data, see Knowledge Skill Templates. The following example shows a request body with data from the glossary template.

{
  "contentType": "text/csv",
  "template": {
    "id": "f184839a-c0ff-46d7-84b9-ca557f92519f"
  },
  "importContent": "term,alternate_names,definition\nbar raiser,b.r.^br^,A Bar Raiser is an interviewer at Amazon."
}

A successful request returns 202 Success. The Location header contains a string you can use to track the import. For details about this request, including a list of template IDs, see Import data.

Step 4: Get the status of the import

To get the status of the import, you submit the following request. You use the import ID from the Location header of your import request in the previous step.

GET https://api.amazonalexa.com/v1/skills/{skillId}/knowledge/imports/{importId}

A successful request returns 200 Success and a response body like the following example.

{ 
  "knowledgeImport": {
    "errors": [],      
    "progress": 75,
    "status": "IN_PROGRESS"
  }
}

For details about this request, see Get the status of a specific import. To retrieve template IDs for future imports, see Get template IDs.

Step 5: Enable your knowledge skill

To enable your knowledge skill for testing on devices associated with your developer account, you use the following request.

PUT https://api.amazonalexa.com/v1/skills/{skillId}/stages/development/enablement

In this example, a successful request returns 204 No Content. For details about this request, see Enable a skill.

For details about how to enable knowledge skills for devices associated with an Alexa for Hospitality or Alexa for Residential accounts, see Enable a skill in the Alexa for Hospitality documentation or Enable a skill in the Alexa for Residential documentation.

Step 6: Test your knowledge skill

You can now test your skill by using an Alexa-enabled device, such as an Echo device, that is registered to the same Amazon account as the account in which you created your skill. In this example, you can ask your Echo device, "Alexa, what is a bar raiser?"