Skip to main content
POST
/
runbooks
/
exec
Runbook Exec
curl --request POST \
  --url https://use.hoop.dev/api/runbooks/exec \
  --header 'Content-Type: application/json' \
  --data '
{
  "connection_name": "pgdemo",
  "file_name": "myrunbooks/run-backup.runbook.sql",
  "repository": "github.com/myorg/myrepo",
  "client_args": [
    "--verbose"
  ],
  "correlation_id": "task-12345",
  "env_vars": {
    "envvar": "PASSWORD:MTIz",
    "filesystem": "SECRET_FILE:bXlzZWNyZXQ="
  },
  "jira_fields": {},
  "metadata": {},
  "parameters": {
    "amount": "10",
    "wallet_id": "6736"
  },
  "ref_hash": "20320ebbf9fc612256b67dc9e899bbd6e4745c77",
  "session_batch_id": "batch-abc-123"
}
'
{
  "execution_time": 5903,
  "exit_code": 1,
  "has_review": false,
  "output": "<string>",
  "output_status": "failed",
  "session_id": "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
  "truncated": false
}

Body

application/json

The request body resource

​
connection_name
string
required

Connection name to execute the runbook against

Example:

"pgdemo"

​
file_name
string
required

The relative path name of the runbook file from the git source

Example:

"myrunbooks/run-backup.runbook.sql"

​
repository
string
required

Repository name where the runbook is located

Example:

"github.com/myorg/myrepo"

​
client_args
string[]

Additional arguments to pass down to the connection

Example:
["--verbose"]
​
correlation_id
string

External workflow/task id to group related sessions

Example:

"task-12345"

​
env_vars
object

Environment Variables that will be included in the runtime

  • { envvar:[env-key]: [base64-val] } - Expose the value as environment variable
  • { filesystem:[env-key]: [base64-val] } - Expose the value as a temporary file path creating the value in the filesystem
Example:
{
  "envvar": "PASSWORD:MTIz",
  "filesystem": "SECRET_FILE:bXlzZWNyZXQ="
}
​
jira_fields
object

Jira fields to create a Jira issue

​
metadata
object

Metadata attributes to add in the session

​
parameters
object

The parameters of the runbook. It must match with the declared attributes

Example:
{ "amount": "10", "wallet_id": "6736" }
​
ref_hash
string

The commit sha reference to obtain the file

Example:

"20320ebbf9fc612256b67dc9e899bbd6e4745c77"

​
session_batch_id
string

Batch identifier to group sessions that were executed simultaneously

Example:

"batch-abc-123"

Response

The execution has finished

​
execution_time
integer

The amount of time the execution took in miliseconds

Example:

5903

​
exit_code
integer

The shell exit code, any non zero code means an error

  • 0 - Linux success exit code
  • -2 - internal gateway code that means it was unable to obtain a valid exit code number from the agent outcome packet
  • 254 - internal agent code that means it was unable to obtain a valid exit code number from the process
Example:

1

​
has_review
boolean

Inform if the connection has review enabled

Example:

false

​
output
string

Output contains an utf-8 output containing the outcome of the ad-hoc execution

​
output_status
enum<string>

Status reports if the outcome of the execution

  • success - The execution was executed with success
  • failed - In case of internal error or when the agent returns an exit code greater than 0 or different than -2
  • running - The execution may still be running.
Available options:
success,
failed,
running
Example:

"failed"

​
session_id
string<uuid>

Each execution creates a unique session id

Example:

"5701046A-7B7A-4A78-ABB0-A24C95E6FE54"

​
truncated
boolean

If the `output`` field is truncated or not

Example:

false