Starting Actions from the API

There are two API methods for starting actions: StartAction, which returns straight away, and StartActionAndWait, which waits for the action to finish.

There are 2 methods to start an action in OliveTin, which can be used in scripts or other applications. These methods allow you to trigger actions either immediately or wait for them to complete. Like every OliveTin API method, they are called with an HTTP POST and a JSON request body (eg: curl --json '{…​}').

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

StartAction

POST

bindingId, arguments, tracking ID, justification

Execution Tracking ID

StartActionAndWait

POST

actionId, arguments, justification

Log Entry (waits for the action to finish)

StartActionAndWait checks that the caller is allowed to view the action’s logs after the action has finished. A caller that can start an action but cannot view its logs receives a permission error, even though the action has already run - so retrying on that error can run the action again. Use StartAction when you do not need the log entry.
StartActionByGet and StartActionByGetAndWait are deprecated and will be removed in a future version. Use StartAction or StartActionAndWait instead.

You can also browse these methods in the OpenAPI/Swagger docs if you prefer. The Protobuf definition is the source of truth for all request and response fields.

All request and response field names below are the protobuf JSON names (lowerCamelCase) from the OliveTin Protobuf definition, which is the source of truth for the API.

Action IDs vs Binding IDs

  • actionId is the id you set on the action in your config.yaml. To find your Action ID, and understand how Action IDs work, see the Action ID documentation.

  • bindingId identifies one button/instance of an action. For a normal action this is the same as the action ID. For actions generated from entities, each entity gets its own binding ID. Binding IDs are returned by GetDashboard (as action.bindingId).

Despite its name, the actionId field used by StartActionAndWait is looked up as a binding ID. For normal actions this makes no difference, but for entity-generated actions you must send the entity’s binding ID - sending the configured action id returns not_found.

Request type: StartAction request object

Used by:

This is the request the OliveTin web UI uses, and gives you the most control over the execution.

StartActionRequest
{
  "bindingId": "string",
  "arguments": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "uniqueTrackingId": "string",
  "justification": "string"
}
  • bindingId (required) - see Action IDs vs Binding IDs.

  • arguments (optional) - values for the action’s arguments.

  • uniqueTrackingId (optional) - if you set this, it is used as the execution tracking ID, otherwise one is generated for you. It must be up to 36 characters of hex digits and dashes (eg: a UUID), and must not already have been used. An invalid or previously used ID is silently replaced with a generated UUID, so always track the execution using the executionTrackingId returned in the response.

  • justification (optional) - the reason for running the action, for actions that require a justification.

Example
{
  "bindingId": "generate_cryptocurrency",
  "arguments": [],
  "uniqueTrackingId": "0f8b1c2e-6d3a-4e5f-9a7b-1c2d3e4f5a6b"
}

Request type: StartActionAndWait request object

Used by:

StartActionAndWaitRequest
{
  "actionId": "string",
  "arguments": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "justification": "string"
}

Note that this request selects the action with actionId (not bindingId), and does not accept a uniqueTrackingId.

Response type: Execution Tracking ID

Used by:

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

Response type: LogEntry

Used by:

The output field contains the combined stdout and stderr of the action.

Example log entry
{
  "logEntry": {
    "datetimeStarted": "2026-11-12 11:56:29",
    "actionTitle": "Restart httpd on server1",
    "output": "Restarting httpd...\n",
    "timedOut": false,
    "exitCode": 0,
    "user": "guest",
    "userClass": "",
    "actionIcon": "🔄",
    "tags": [],
    "executionTrackingId": "56588051-80da-4b31-8cd8-461a4566e3a9",
    "datetimeFinished": "2026-11-12 11:56:31",
    "executionStarted": true,
    "executionFinished": true,
    "blocked": false,
    "datetimeIndex": "4",
    "canKill": false,
    "datetimeRateLimitExpires": "",
    "bindingId": "restart_httpd",
    "queued": false,
    "queuedForGroup": "",
    "justification": "",
    "arguments": [
      {
        "name": "server",
        "value": "server1"
      }
    ]
  }
}

Deprecated: StartActionByGet and StartActionByGetAndWait

StartActionByGet and StartActionByGetAndWait are deprecated, and will be removed in a future version of OliveTin. They only accept an actionId (no arguments), and despite their names they no longer support GET requests - the OliveTin 2k style of putting the action ID in the URL returns 404.

When either method is called, OliveTin shows a warning on the Diagnostics page (code deprecated_api_call), so you can find integrations that still need updating. The warning is cleared when OliveTin restarts.

Deprecated method Use instead Change

StartActionByGet

StartAction

Send {"bindingId": "…​"} instead of {"actionId": "…​"}

StartActionByGetAndWait

StartActionAndWait

Change the method name only - the request is the same