Pegasus Reference

In an effort to give more control to users and facilitate Snips's platform configuration, Snips created a REST HTTPS webservice called Pegasus.

It provides several functionalities, including but not limited to :

  • Install & update Snips Platform packages

  • Basic audio setup

  • Install assistant from the console or a zip file

  • Manage actions configuration individually

  • Control Snips' platform components (start, stop, status, logs)

  • Manage skills

Pegasus is currently in beta. If you encounter any issues, have ideas about new features we can provide, please open a ticket https://github.com/snipsco/snips-issues/issues

Installation

Linux - Debian - RaspberryPi

sudo apt-get install snips-pegasus

If you want to install and manage assistant's actions, you will need snips-skill-server

sudo apt-get install snips-skill-server

Other platforms

Not supported yet.

API definition

Once installed, Pegasus will start & load this specification on your local network. e.g. on a RaspberryPi: https://raspberrypi.local:8443/pegasus/swagger

Pegasus uses a self signed certificate that can't be validated by your browser. Thus, when visiting the swagger definition on your browser, you will be warned that the connection is not private. You can safely ignore this warning and go the website.

Pegasus' uses OpenAPI specification to describe its API. It will give you all the routes available on Pegasus and the ability to test them directly in your browser.

Connection

Pegasus uses HTTPS on port 8443 and basic route authentication (username / password encoded in Base64). Two routes are available without authentication

  • POST Signing up as a new user

  • GET Certificate authority

Other routes will need a basic authentication token.

Asynchronous routes

Pegasus contains asynchronous long running tasks for these routes :

  • POST /pegasus/platform

  • POST /pegasus/platform/{component}

  • PUT /pegasus/assistant

  • POST /pegasus/actions/git

After calling one of this endpoint, Pegasus will create a new task and return it's id. Tasks are executed one at a time synchronously. If a task is running, a new created task will be queued waiting for the first one to complete.

You can retrieve the logs of a single task by calling GET /pegasus/tasks/{taskid}.

You can retrieve all tasks status by calling GET /pegasus/tasks.

Task's status can be running / queued / completed / failed.

You cannot cancel a task at this time.

Signing up

POST /pegasus/user
{
"login": "",
"password": "",
}

Self signed certificate

Pegasus is protected by a self-signing certificate that is generated :

  • During the first installation

  • Everytime the hostname of the host machine changes

If you want to sign your requests with Pegasus' certificate authority, you can retrieve the certificate using the route GET /pegasus/certificate

⚠️ Pegasus will not reject requests that are not signed.

Configuration

Pegasus' configuration can be edited in etc/snips.toml

Changing port

Uncomment and change the address value in snips.toml

Uncomment and make values empty for certificate keys :

tls_certificate_chain = ""
tls_private_key = ""

And relaunch Pegasus sudo systemctl restart snips-pegasus