API Method: StartAction

This is the method the OliveTin web UI uses to start actions, and is probably the best method to use if you are writing scripts.

  • HTTP Method: POST

  • Request Type: StartAction request object (bindingId, arguments, uniqueTrackingId, justification)

  • Response Type: Execution Tracking ID

StartAction selects the action with bindingId, not actionId. For a normal action, the binding ID is the same as the action id from your config.yaml. See Action IDs vs Binding IDs.

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

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.

Example API call: Start an action using StartAction

curl
user@host: curl "http://olivetin.example.com:1337/api/StartAction" --json '{"bindingId": "nuclear_reactor_shutdown"}'
{"executionTrackingId":"6ecda25d-b6e1-4621-898c-d4e6f2dbeda5"}
Powershell
PS C:\Users\xcons> $json = '{"bindingId": "deploy_attack_gnomes"}'
PS C:\Users\xcons> Invoke-RestMethod -Method "Post" -Uri "http://olivetinServer:1337/api/StartAction" -ContentType "application/json" -Body $json

Example API call: Start an action using StartAction with arguments

curl
user@host: curl 'http://olivetin.example.com:1337/api/StartAction' --json '{"bindingId": "Ping_host", "arguments": [{"name": "host", "value": "example.com"},{"name": "count", "value": "1"}]}'