With the HTTP API, you can request actions over the HTTP protocol and also provide queries to Leon from external services.
That means you can easily communicate with Leon from any third-party such as Discord, Signal, Telegram, Messenger and so on…
Example of scenario:
- You send a command on Discord. It could be “!query hello”.
- Your Discord bot catches it and forward “hello” to your Leon server.
- Leon executes the greeting module and returns the response.
- You handle the response and your Discord bot displays it on Discord.
Leon exposes two types of HTTP endpoints: the query endpoint and actions endpoint.
Tip
By default, Leon is exposed over HTTP. You can disable it from the .env file:
HTTP API Key#
To request Leon over HTTP, you need to provide the HTTP API key. This key can be found in the .env file with the environment variable LEON_HTTP_API_KEY.
Generate a New Key#
The HTTP API key is automatically generated during the setup of Leon. If you need to generate a new key, please run the following command:
The Query Endpoint#
Via this endpoint, Leon handles the string you send (query) and then executes the targeted module based on his understanding.
Endpoint#
| Method | URL | Header | Body data |
|---|---|---|---|
POST | /api/query | - Content-Type: application/json | |
- X-API-Key: {LEON_HTTP_API_KEY} | query |
Example#
Actions Endpoints#
By default, every module action is exposed over HTTP. Leon automatically translates actions into HTTP endpoints based on the configuration.
Tip
You can find the generated endpoints in the core/pkgs-endpoints.json file.
Endpoints#
| Method | URL | Header |
|---|---|---|
- POST | ||
- GET | /api/p/{PACKAGE}/{MODULE}/{ACTION} | - Content-Type: application/json |
- X-API-Key: {LEON_HTTP_API_KEY} |
Example 1#
Let’s try an example with the “run” action of the “greeting” module.
Example 2#
Now let’s try another example with an action module that requires parameters/entities to work.
Some actions require specific inputs (entities) and developers of these actions should add support to fully expose them over HTTP.
To know what parameters to put in the body data, go to the packages/{PACKAGE}/data/expressions/{LANG}.json file.
Configuration#
Options#
These options can be configured at the action level in the packages/{PACKAGE}/data/expressions/{LANG}.json file.
| Key | Description | Default |
|---|---|---|
http_api.method | HTTP method of the action. | GET if no entity |
POST if an entity is needed | ||
http_api.timeout | Execution time before timeout (in ms). | 60000 |
http_api.disabled | Disable a specific action. | false |
http_api.entities | Entities that can be passed as parameters in the body data | [] |
Tip
- For entities, you can take example on
packages/trend/data/expressions/en.json. - For a full list of the entities format, please check here.