API

OliveTin API Overview

This section of the documentation is intended for developers, and those who want to hack around with OliveTin and extend it. This page provides a few pointers to get started.

Short version: http://olivetinServer:1337/api for the REST API. Swagger documents the API.

Longer version: The OliveTin API is formally defined using the Protobuf IDL, which generates gRPC stubs, as well as a REST Gateway.

The REST API gateway is used by the WebUI, and you can use it too by default - it is exposed at "/api" by default.

The gRPC API only listens on localhost default, but it can be set to listen publicly. See the network ports documentation for a better description of how the APIs are exposed. Most people do not need to use the gRPC API. The .proto file for the gRPC API is located at the root of the OliveTin Git repository; OliveTin.proto.

Links

Please do talk to the developers on Discord if you’d like help using the API, or you’re thinking about building something interesting using the API!

Starting Actions from the API

There are several variants of this API call available which might be easier for scripts (or humans) to work with!

Webhook/API reference table
Function HTTP Method Request Type (How to select an action) Response Type

StartAction

POST

OliveTin request object

Execution Tracking ID

StartActionByGet

GET

Action ID in the URL

Execution Tracking ID

StartActionAndWait

POST

OliveTin request object

Log Entry (waits for the action to finish)

StartActionByGetAndWait

GET

Action ID in the URL

Log Entry (waits for the action to finish)

Request type: Action ID in the URL

Used by:

  • StartActionByGet

  • StartActionByGetAndWait

If you are trying to integrate OliveTin with your own scripts or processes, it’s probably easiest to start actions by using an ID directly in the URL, see the example.

Request type: OliveTin request object

Used by:

  • StartAction

  • StartActionAndWait

OliveTin request object structure
{
  "actionId": "string",
  "arguments": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "uniqueTrackingId": "string"
}

To find your Action ID, and understand how Action IDs work, see the Action ID documentation

If you need more control over the execution, then the only other option is to submit a OliveTin reqjest object, which is just a very simple JSON structure like this;

{
    "actionId": "Generate cryptocurrency",
    "arguments": [],
    "uniqueTrackingId": "my-tracking-id",
}

More detailed examples can be seen below.

Response type: Execution Tracking ID

Used by:

  • StartAction

  • StartActionByGet

Example Execution Tracking ID response
{"executionTrackingId":"5bb4860c-bbd0-4bc9-a7d6-42240551500c"}

Response type: LogEntry

Used by:

  • StartActionAndWait

  • StartActionByGetAndWait

Example log entry
{
    "logEntry": {
        "datetimeStarted": "2024-02-27 14:14:49",
        "actionTitle": "Restart httpd on server1",
        "stdout": "",
        "stderr": "",
        "timedOut": true,
        "exitCode": -1,
        "user": "",
        "userClass": "",
        "actionIcon": "🔄",
        "tags": [

        ],
        "executionTrackingId": "b04b1e90-d457-4158-b7dc-da9e81f21568",
        "datetimeFinished": "2024-02-27 14:14:52",
        "actionId": "restart_httpd",
        "executionStarted": true,
        "executionFinished": true,
        "blocked": false
    }
}

Example API call; Start an action by ID in the URL

curl
user@host: curl http://olivetin.example.com/api/StartActionByGet/pingGithub

The corresponding config.yaml would look like this;

actions:
  - title: Ping GitHub.com
    id: pingGithub
    shell: ping github.com -c 1

IDs are used by these API calls, as you probably want the interface to display a human-readable title, whereas the API call doesn’t want to have spaces or punctuation.

Example API call: Start an action using StartAction

curl
user@host: curl -X POST "http://olivetin.webapps.teratan.lan/api/StartAction" -d '{"actionId": "nuclear_reactor_shutdown"}'
Powershell
PS C:\Users\xcons> $json = '{"actionId": "deploy_attack_gnomes"}'
PS C:\Users\xcons> Invoke-RestMethod -Method "Post" -Uri "http://olivetinServer:1337/api/StartAction" -Body $json

Example API call: Start an action using StartAction with arguments

curl
user:host: curl -X POST 'http://olivetin.example.com/api/StartAction' -d '{"actionId": "Ping_host", "arguments": [{"name": "host", "value": "example.com"},{"name": "count", "value": "1"}]}'

Misc API calls

Example API call: Get the dashboard buttons ("components")

curl
user@host: curl http://olivetinServer:1337/api/GetDashboardComponents

Example API call: readyz Healthcheck

This is useful for configuring healthchecks in docker containers, or on Kubernetes.

curl
user@host: curl http://olivetinServer:1337/api/readyz
{"status": "ok"}

The response will always be "status: ok" to indicate that the API is up, or it will timeout.

Local User Login via API

OliveTin supports serveral different ways to login, and most installations will probably login via reverse proxy, or via local user login.

To login via local user login, you can use the following API call: /LocalUserLogin. This is documented in the API documentation which can be found here; https://docs.olivetin.app/api/

The API call is a POST request, and you need to provide a username and password as a JSON object in the body of the request. Here is an example of how you can login via a cURL request;

user@host: curl -X POST "http://olivetin-server:1337/api/LocalUserLogin" -H "accept: application/json" -H "Content-Type: application/json" -d '{"username":"admin","password":"toomanysecrets"}' -v
...
< Set-Cookie: olivetin-sid-local=c6c5b2b3-a58b-4dbc-b070-ed7bdd3f1956; Path=/; Max-Age=31556952; HttpOnly
...
{"success":true}

You can see from the above example that the header response sets a cookie called "olivetin-sid-local" to a UUID which is your session ID. You must include this cookie with future requests to authenticate yourself.

You can also that the body of the response is a JSON object with a simple success key, which will be true if the login was successful, and false if it was not.

Check login with WhoAmI

You can check your current login status by using the /WhoAmI API call. This is a GET request, and you need to provide the olivetin-sid-local cookie in the request. Here is an example of how you can check your login status via a cURL request;

user@host: curl -X GET http://localhost:1337/api/WhoAmI -H "accept: application/json" -H 'Content-Type: application/json' -b "olivetin-sid-local=cd33aa9c-c613-473e-8581-2b742716ab8e"
{"authenticatedUser":"admin", "usergroup":"", "provider":"local", "acls":[], "sid":""}