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"
}
json

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",
}
json

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"}
json

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
    }
}
json

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

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

The corresponding config.yaml would look like this;

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

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"}'
bash
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
powershell

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"}]}'
bash