A REST API on top of Mycroft AI Core

Hi Mycroft,

Half of the text below comes from the README.md from GitHub. :stuck_out_tongue:
Please read the README.md to get information about how to install and configure the API.

As usual, this is not perfect but it’s useful for us so we hope it could be useful to you, enjoy!

Introduction

For some of our needs we wrote an API on top of Mycroft AI Core. The goal of it is to provide a layer on top of the core to perform actions such as:

  • Install or uninstall skills
  • Retrieve information (version, location, name, etc…)
  • Reload configuration to notify services if a change occurred
  • Delete TTS cache files
  • Microphone mute and un-mute (software)
  • Stop any speech or audio output
  • And more!

Here is a quick list of use cases where the API could be used:

  • Install or uninstall skills remotely
  • Monitoring and get information
  • Interface other IoT devices with Mycroft
  • Ask for speech from remote sources
  • Connect buttons to trigger actions such as stop or listen
  • Update skills via an external scheduler
  • The sky is the limit…

Architecture

In order to interface with Mycroft AI core instance, the API connects to the core messages bus to send and receive messages. Some messages used by this API are native to the core such as stop, mycroft.skills.list, etc… but most of the messages used are custom for the API requirements such as mycroft.api.skill_settings, mycroft.api.websocket, etc…

The API will send messages to the bus but for non-native messages a skill is required on the core to interpret these messages. This is why the mycroft-rest-api-skill skill should be installed on the core. The API and the skill authenticate via an API key shared between both of them.

The API_KEY needs to be defined within the .env file and this same key must be defined on home.mycroft.ai (see the skill README for more information).

Mycroft API Flow

To consume the API a user is required, this user will allow to retrieve a JSON Web Token (JWT) using a basic authentication method. Once the authentication has been validated an access and a refresh tokens will be provided.

Consume the API

To consume the API you could use different tools from the very basic but powerful such as curl or something more user friendly like Postman (a collection is provided, more about it below). Once the API is up and running, you could get the complete list of the available endpoints at http://10.12.50.21:8000/docs (replace with your IP address and port).

Mycroft API Swagger

Here are some curl examples toe retrieve tokens, information, stop audio output, and more!

Retrieve tokens

curl -s -H "Content-Type: application/json" -d '{"user": "mycroft", "password": "c-h-a-n-g-e-m-e"}' -X POST http://10.12.50.21:8000/v1/auth/tokens
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJteWNyb2Z0IiwiZXhwIjoxNjQxMTY1MDA4LCJpYXQiOjE2NDExNjMyMDgsImlzcyI6Im15Y3JvZnQtYXBpIiwic2NvcGUiOiJhY2Nlc3MifQ.iIXr0NhYo9A5X9xI06UjVWw8FDGm1ZC4AD8fuBFM2mQ",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJteWNyb2Z0IiwiZXhwIjoxNzE4OTIzMjA4LCJpYXQiOjE2NDExNjMyMDgsImlzcyI6Im15Y3JvZnQtYXBpIiwic2NvcGUiOiJyZWZyZXNoIn0._bp2FUqAzoPWzgDHOlkjIfZvb76BdY6nShqDV1_lJPk"
}

If the basic authentication worked then two tokens will be returned:

  1. An access token to consume the API only valid 30 minutes (could be change in config.py)
  2. A refresh token valid 6 hours (could be change in config.py) to refresh an access token without the user and password

Retrieve system information

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJteWNyb2Z0IiwiZXhwIjoxNjQxMTY1MDA4LCJpYXQiOjE2NDExNjMyMDgsImlzcyI6Im15Y3JvZnQtYXBpIiwic2NvcGUiOiJhY2Nlc3MifQ.iIXr0NhYo9A5X9xI06UjVWw8FDGm1ZC4AD8fuBFM2mQ" -X GET http://10.12.50.21:8000/v1/system/info
{
  "results": {
    "core_version": "21.2.2",
    "device_uuid": "74318843-0812-4903-a1c2-36da5a98e041",
    "name": "docker",
    "audio_backend": "vlc",
    "city": "Montréal",
    "country": "Canada",
    "lang": "en-us",
    "platform": "mycroft_mark_2",
    "timezone": "America/Toronto",
    "tts_engine": "mimic2"
  }
}

Stop speech or audio output

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJteWNyb2Z0IiwiZXhwIjoxNjQxMTY1MDA4LCJpYXQiOjE2NDExNjMyMDgsImlzcyI6Im15Y3JvZnQtYXBpIiwic2NvcGUiOiJhY2Nlc3MifQ.iIXr0NhYo9A5X9xI06UjVWw8FDGm1ZC4AD8fuBFM2mQ" -X DELETE -I http://10.12.50.21:8000/v1/voice/speech 
HTTP/1.1 204 No Content
date: Sun, 02 Jan 2022 22:50:58 GMT
server: uvicorn

The -I option will return the HTTP status.

Update all installed skills

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJteWNyb2Z0IiwiZXhwIjoxNjQxMTY1MDA4LCJpYXQiOjE2NDExNjMyMDgsImlzcyI6Im15Y3JvZnQtYXBpIiwic2NvcGUiOiJhY2Nlc3MifQ.iIXr0NhYo9A5X9xI06UjVWw8FDGm1ZC4AD8fuBFM2mQ" -X PUT -I http://10.12.50.21:8000/v1/skills/update

The -I option will return the HTTP status.

Refresh an access token

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJteWNyb2Z0IiwiZXhwIjoxNzE4OTIzMjA4LCJpYXQiOjE2NDExNjMyMDgsImlzcyI6Im15Y3JvZnQtYXBpIiwic2NvcGUiOiJyZWZyZXNoIn0._bp2FUqAzoPWzgDHOlkjIfZvb76BdY6nShqDV1_lJPk" -X GET http://10.12.50.21:8000/v1/auth/refresh
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJteWNyb2Z0IiwiZXhwIjoxNjQxMTY2MjUxLCJpYXQiOjE2NDExNjQ0NTEsImlzcyI6Im15Y3JvZnQtYXBpIiwic2NvcGUiOiJhY2Nlc3MifQ.V7UP3MHm19Db3P-28ZBCkL4pAZX2T3V-nMk6a9u0S0A"
}

Postman

As previously mentioned, a Postman collection is provided in this repository under the postman directory with a list of multiple requests.

Mycroft API Postman collection

Please follow the official documentation to import the Mycroft API Postman collection.

Once the collection has been imported, make sure to update the default variables and to set the right access token.

Links

5 Likes

@goldyfruit - WOW, that is so cool! :grinning_face_with_smiling_eyes:

Not sure who “we” is, but thanks so much to you and your team.

I was just thinking the other day: “I wonder if there is a Mycroft RESTfui API to do [this]”.

-Mike M
1 Like

Thanks for this very important building block for Mycroft. I can easily see that this will be a key tool to integrating Mycroft with other software.

1 Like

thanks for the awesome information.

1 Like

You are welcome!
I would love to here some feedback. :stuck_out_tongue:

Is there a list of the APIs available? I go to https://github.com/smartgic/mycroft-rest-api-skill
and was hoping to see examples of URLs that can be dropped into a browser.

Thanks.

-Mike M

Hey @mike99mac

As mentioned in the first post in the Consume the API section, you will have to install the API to get the list.

@goldyfruit , thanks for the quick reply.

And as mentioned, I

in the github repo.

I’d be more motivated to try it if I had a better understanding of what it provided.

But maybe I’ll try to install it, find the list of APIs, try out a few, then add a PR to the README with some examples. … (there I just added that to my TODO list)

-Mike M

There are already few examples in the initial post and the README.

  • Retrieve tokens
  • Retrieve system information
  • Stop speech or audio output
  • Update all installed skills
  • Refresh an access token

Here is a full list a API calls available:

I hope it helps.

Yes, it does, Thanks.

1 Like