API Reference

The Pipetower API allows you to interact with your account through a simple REST API, e.g. retrieve servers and metrics, execute actions or workflows or read run logs.

All responses from the Pipetower API will be formatted as JSON.

BASE URL

https://app.pipetower.com/api

Authentication

The Pipetower API uses API tokens to authenticate requests. You can view and manage your API tokens in your Pipetower Account.

The API token should be included in the request as a bearer token value.

AUTHENTICATED REQUEST

curl https://app.pipetower.com/api/status \
  -H "Authorization: Bearer $API_TOKEN"

Headers

Make sure you have the following content type headers are set on every request:

Accept: application/json

Content-Type: application/json

Errors

Pipetower uses the following HTTP response codes to indicate the success or failure of an API request:

200	Everything is ok.
400	Valid data was given but the request has failed.
401	No valid API token was given.
404	The request resource could not be found.
422	The payload has missing required parameters or invalid data was given.
429	Too many attempts.
500	Request failed due to an internal error in Pipetower.
503	Pipetower is offline for maintenance.

Account

To check your Pipetower account you can use this endpoint.

Attributes

id string

The unique identifier for your account.

GET /account

curl https://app.pipetower.com/api/account \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "e86bn6",
  "name": "Joe Bloggs",
  "email": "jbloggs@pipetower.com",
  "timezone": "UTC",
  "email_verified": true,
  "2fa_enabled": true,
  "created_at": "2023-04-09T10:56:38+00:00",
  "updated_at": "2023-07-29T13:24:11+00:00"
}

Retrieve your user variables

Retrieves the user variables of your account.

Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /account/vars

curl https://app.pipetower.com/api/account/vars \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "secret": false,
      "name": "SYSTEM_USER",
      "value": "morpheus"
    },
    {
      "secret": true,
      "name": "APP_KEY",
      "value": "***"
    },
    {...}
  ],
  "meta": {...}
}

Servers

Servers in Pipetower represent your physical servers to which Pipetower connects and on which actions and workflows are executed.

ENDPOINTS

GET /servers

GET /servers/:id

GET /servers/:id/runs

GET /servers/:id/metrics

GET /servers/:id/vars

The server object

Attributes

id string

The unique identifier for the server.
team_id string

The ID of the team to which this server belongs.

THE SERVER OBJECT

{
  "id": "r0em4n",
  "team_id": "n80b40",
  "name": "Pipetower",
  "connected": true,
  "host": "pipetower.com",
  "port": "22",
  "tags": [
    {
      "name": "prod",
      "color": "#38bdf8"
    }
  ],
  "created_at": "2023-03-16T09:21:59+00:00",
  "updated_at": "2023-10-03T17:11:03+00:00"
}

List all servers

Returns a list of your servers.

Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /servers

curl https://app.pipetower.com/api/servers \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "r0em4n",
      "team_id": "n80b40",
      "name": "Pipetower",
      "connected": true,
      "host": "pipetower.com",
      "port": "22",
      "tags": [
        {
          "name": "prod",
          "color": "#38bdf8"
        }
      ],
      "created_at": "2023-03-16T09:21:59+00:00",
      "updated_at": "2023-10-03T17:11:03+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Retrieve a server

Retrieves a server object.

Parameters

id REQUIRED

The ID of the server you want to retrieve.

GET /servers/:id

curl https://app.pipetower.com/api/servers/:id \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "r0em4n",
  "team_id": "n80b40",
  "name": "Pipetower",
  "connected": true,
  "host": "pipetower.com",
  "port": "22",
  "tags": [
    {
      "name": "prod",
      "color": "#38bdf8"
    }
  ],
  "created_at": "2023-03-16T09:21:59+00:00",
  "updated_at": "2023-10-03T17:11:03+00:00"
}

Retrieve a server's runs

Retrieves the runs of the specified server.

Parameters

id REQUIRED

The ID of the server for which you want to retrieve the runs.
limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /servers/:id/runs

curl https://app.pipetower.com/api/servers/:id/runs \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "e0k229",
      "team_id": "n80b40",
      "status": "successful",
      "executable": {
        "id": "92eb93",
        "type": "Action",
        "name": "Install UFW"
      },
      "executions": [
        "5035k0",
        "w0v6m0"
      ],
      "created_at": "2023-10-07T10:26:40+00:00",
      "started_at": "2023-10-07T10:26:41+00:00",
      "finished_at": "2023-10-07T10:26:50+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Retrieve a server's metrics

Retrieves the metrics of the specified server.

Parameters

id REQUIRED

The ID of the server for which you want to retrieve the metrics.
limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /servers/:id/metrics

curl https://app.pipetower.com/api/servers/:id/metrics \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "type": "CpuModel",
      "metric": "name",
      "value": "Intel(R) Core(TM) i7-10510U CPU @ 1.80GHz",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "CpuModel",
      "metric": "cpus",
      "value": "8",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "HostInfo",
      "metric": "hostname",
      "value": "morpheus-prod",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "HostInfo",
      "metric": "operating_system",
      "value": "Ubuntu 22.04.3 LTS",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "HostInfo",
      "metric": "kernel",
      "value": "Linux 5.15.0-84-generic",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "HostInfo",
      "metric": "architecture",
      "value": "x86-64",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "\/|total",
      "value": "248617984",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "\/|used",
      "value": "48326376",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "\/|available",
      "value": "187589708",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "sum|total",
      "value": "487816836",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "sum|used",
      "value": "171749904",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "\/home|total",
      "value": "239198852",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "\/home|used",
      "value": "123423528",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "\/home|available",
      "value": "103551888",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "DiskUsage",
      "metric": "sum|used_percent",
      "value": "35.21",
      "timestamp": "2023-10-07T10:26:00+00:00"
    },
    {
      "type": "CpuUsage",
      "metric": "idle",
      "value": "89.2",
      "timestamp": "2023-10-07T10:27:00+00:00"
    },
    {
      "type": "CpuUsage",
      "metric": "load",
      "value": "10.8",
      "timestamp": "2023-10-07T10:27:00+00:00"
    },
    {
      "type": "LoadAverage",
      "metric": "average_1",
      "value": "1.23",
      "timestamp": "2023-10-07T10:27:00+00:00"
    },
    {
      "type": "LoadAverage",
      "metric": "average_5",
      "value": "1.45",
      "timestamp": "2023-10-07T10:27:00+00:00"
    },
    {
      "type": "LoadAverage",
      "metric": "average_15",
      "value": "1.18",
      "timestamp": "2023-10-07T10:27:00+00:00"
    },
    {
      "type": "MemoryUsage",
      "metric": "mem_total",
      "value": "16023304",
      "timestamp": "2023-10-07T10:27:00+00:00"
    },
    {
      "type": "MemoryUsage",
      "metric": "mem_available",
      "value": "6043860",
      "timestamp": "2023-10-07T10:27:00+00:00"
    },
    {
      "type": "MemoryUsage",
      "metric": "mem_used",
      "value": "9979444",
      "timestamp": "2023-10-07T10:27:00+00:00"
    },
    {
      "type": "MemoryUsage",
      "metric": "mem_used_percent",
      "value": "62.28",
      "timestamp": "2023-10-07T10:27:00+00:00"
    }
  ],
  "meta": {...}
}

Retrieve a server's environment variables

Retrieves the environment variables of the specified server.

Parameters

id REQUIRED

The ID of the server for which you want to retrieve the environment variables.
limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /servers/:id/vars

curl https://app.pipetower.com/api/servers/:id/vars \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "secret": false,
      "name": "SYSTEM_USER",
      "value": "morpheus"
    },
    {
      "secret": true,
      "name": "APP_KEY",
      "value": "***"
    },
    {...}
  ],
  "meta": {...}
}

Actions

Actions define the tasks that can be automated, like executing commands.

ENDPOINTS

GET /actions

GET /actions/:id

GET /actions/:id/runs

The action object

Attributes

id string

The unique identifier for the action.
team_id string

The ID of the team to which this action belongs.

THE ACTION OBJECT

{
  "id": "92eb93",
  "team_id": "n80b40",
  "name": "Install UFW",
  "steps": [
    {
      "order": 0,
      "type": "execute_command",
      "name": "Install",
      "execution": {
        "command": "sudo apt install ufw"
      }
    },
    {
      "order": 1,
      "type": "execute_command",
      "name": "Enable",
      "execution": {
        "command": "sudo ufw enable",
        "expectations": [
          {
            "send": "y",
            "regex": true,
            "expect": "Proceed(.*)"
          }
        ],
        "with_expectations": true
      }
    }
  ],
  "tags": [],
  "created_at": "2023-08-19T09:05:11+00:00",
  "updated_at": "2023-08-20T12:45:53+00:00"
}

List all actions

Returns a list of your actions.

Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /actions

curl https://app.pipetower.com/api/actions \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "92eb93",
      "team_id": "n80b40",
      "name": "Install UFW",
      "steps": [
        {
          "order": 0,
          "type": "execute_command",
          "name": "Install",
          "execution": {
            "command": "sudo apt install ufw"
          }
        },
        {
          "order": 1,
          "type": "execute_command",
          "name": "Enable",
          "execution": {
            "command": "sudo ufw enable",
            "expectations": [
              {
                "send": "y",
                "regex": true,
                "expect": "Proceed(.*)"
              }
            ],
            "with_expectations": true
          }
        }
      ],
      "tags": [],
      "created_at": "2023-08-19T09:05:11+00:00",
      "updated_at": "2023-08-20T12:45:53+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Retrieve an action

Retrieves an action object.

Parameters

id REQUIRED

The ID of the action you want to retrieve.

GET /actions/:id

curl https://app.pipetower.com/api/actions/:id \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "92eb93",
  "team_id": "n80b40",
  "name": "Install UFW",
  "steps": [
    {
      "order": 0,
      "type": "execute_command",
      "name": "Install",
      "execution": {
        "command": "sudo apt install ufw"
      }
    },
    {
      "order": 1,
      "type": "execute_command",
      "name": "Enable",
      "execution": {
        "command": "sudo ufw enable",
        "expectations": [
          {
            "send": "y",
            "regex": true,
            "expect": "Proceed(.*)"
          }
        ],
        "with_expectations": true
      }
    }
  ],
  "tags": [],
  "created_at": "2023-08-19T09:05:11+00:00",
  "updated_at": "2023-08-20T12:45:53+00:00"
}

Retrieve an action's runs

Retrieves the runs of the specified action.

Parameters

id REQUIRED

The ID of the action for which you want to retrieve the runs.
limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /actions/:id/runs

curl https://app.pipetower.com/api/actions/:id/runs \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "e0k229",
      "team_id": "n80b40",
      "status": "successful",
      "executable": {
        "id": "92eb93",
        "type": "Action",
        "name": "Install UFW"
      },
      "executions": [
        "5035k0",
        "w0v6m0"
      ],
      "created_at": "2023-10-07T10:26:40+00:00",
      "started_at": "2023-10-07T10:26:41+00:00",
      "finished_at": "2023-10-07T10:26:50+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Workflows

Workflows are sequences of Actions that are executed one after the other.

ENDPOINTS

GET /workflows

GET /workflows/:id

GET /workflows/:id/runs

The workflow object

Attributes

id string

The unique identifier for the workflow.
team_id string

The ID of the team to which this workflow belongs.

THE WORKFLOW OBJECT

{
  "id": "m5e8kv",
  "team_id": "n80b40",
  "name": "Initial server setup",
  "steps": [
    {
      "order": 0,
      "execution": {
        "action": "92e843"
      }
    },
    {
      "order": 1,
      "execution": {
        "action": "36b28n"
      }
    },
    {
      "order": 2,
      "execution": {
        "action": "83k1m8",
        "conditions": [
          [
            {
              "condition_rule": "exec_successful|bool",
              "condition_value": "",
              "condition_action": "1|36b28n"
            }
          ]
        ]
      }
    }
  ],
  "tags": [],
  "created_at": "2023-07-08T14:42:23+00:00",
  "updated_at": "2023-08-26T12:34:04+00:00"
}

List all workflows

Returns a list of your workflows.

Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /workflows

curl https://app.pipetower.com/api/workflows \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "m5e8kv",
      "team_id": "n80b40",
      "name": "Initial server setup",
      "steps": [
        {
          "order": 0,
          "execution": {
            "action": "92e843"
          }
        },
        {
          "order": 1,
          "execution": {
            "action": "36b28n"
          }
        },
        {
          "order": 2,
          "execution": {
            "action": "83k1m8",
            "conditions": [
              [
                {
                  "condition_rule": "exec_successful|bool",
                  "condition_value": "",
                  "condition_action": "1|36b28n"
                }
              ]
            ]
          }
        }
      ],
      "tags": [],
      "created_at": "2023-07-08T14:42:23+00:00",
      "updated_at": "2023-08-26T12:34:04+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Retrieve a workflow

Retrieves a workflow object.

Parameters

id REQUIRED

The ID of the workflow you want to retrieve.

GET /workflows/:id

curl https://app.pipetower.com/api/workflows/:id \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "m5e8kv",
  "team_id": "n80b40",
  "name": "Initial server setup",
  "steps": [
    {
      "order": 0,
      "execution": {
        "action": "92e843"
      }
    },
    {
      "order": 1,
      "execution": {
        "action": "36b28n"
      }
    },
    {
      "order": 2,
      "execution": {
        "action": "83k1m8",
        "conditions": [
          [
            {
              "condition_rule": "exec_successful|bool",
              "condition_value": "",
              "condition_action": "1|36b28n"
            }
          ]
        ]
      }
    }
  ],
  "tags": [],
  "created_at": "2023-07-08T14:42:23+00:00",
  "updated_at": "2023-08-26T12:34:04+00:00"
}

Retrieve a workflow's runs

Retrieves the runs of the specified workflow.

Parameters

id REQUIRED

The ID of the workflow for which you want to retrieve the runs.
limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /workflows/:id/runs

curl https://app.pipetower.com/api/workflows/:id/runs \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "4b27a4",
      "team_id": "n80b40",
      "status": "successful",
      "executable": {
        "id": "m5e8kv",
        "type": "Workflow",
        "name": "Initial server setup"
      },
      "executions": [
        "n3m993",
        "k0bm69"
      ],
      "created_at": "2023-10-07T10:26:40+00:00",
      "started_at": "2023-10-07T10:26:41+00:00",
      "finished_at": "2023-10-07T10:28:06+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Pipes

Pipes are sequences of Actions or Workflows triggered by an event (When -> Then).

ENDPOINTS

GET /pipes

GET /pipes/:id

GET /pipes/:id/runs

The pipe object

Attributes

id string

The unique identifier for the pipe.
team_id string

The ID of the team to which this pipe belongs.

THE PIPE OBJECT

{
  "id": "e47d20",
  "team_id": "n80b40",
  "name": "Check available Updates",
  "active": true,
  "trigger": {
    "type": "schedule",
    "event": "every_week",
    "execution": {
      "day": "monday",
      "time": "10"
    }
  },
  "steps": [
    {
      "order": 0,
      "type": "action",
      "event": "execute_action",
      "execution": {
        "action": "026nw2",
        "servers": [
          "r0em4n",
          "kbe67n",
          "b27a36"
        ]
      }
    },
    {
      "order": 1,
      "type": "notification",
      "event": "send_notification",
      "execution": {
        "channel": "email",
        "message": "Updates are available!",
        "conditions": [
          [
            {
              "condition_rule": "output_contains|value",
              "condition_field": "1|step_execute_action_action",
              "condition_value": "upgradable from:",
              "condition_server": "any_of_executed_servers"
            }
          ]
        ],
        "recipients": [
          "e86bn6"
        ]
      }
    }
  ],
  "tags": [],
  "created_at": "2023-07-16T19:19:17+00:00",
  "updated_at": "2023-10-07T09:22:02+00:00"
}

List all pipes

Returns a list of your pipes.

Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /pipes

curl https://app.pipetower.com/api/pipes \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "e47d20",
      "team_id": "n80b40",
      "name": "Check available Updates",
      "active": true,
      "trigger": {
        "type": "schedule",
        "event": "every_week",
        "execution": {
          "day": "monday",
          "time": "10"
        }
      },
      "steps": [
        {
          "order": 0,
          "type": "action",
          "event": "execute_action",
          "execution": {
            "action": "026nw2",
            "servers": [
              "r0em4n",
              "kbe67n",
              "b27a36"
            ]
          }
        },
        {
          "order": 1,
          "type": "notification",
          "event": "send_notification",
          "execution": {
            "channel": "email",
            "message": "Updates are available!",
            "conditions": [
              [
                {
                  "condition_rule": "output_contains|value",
                  "condition_field": "1|step_execute_action_action",
                  "condition_value": "upgradable from:",
                  "condition_server": "any_of_executed_servers"
                }
              ]
            ],
            "recipients": [
              "e86bn6"
            ]
          }
        }
      ],
      "tags": [],
      "created_at": "2023-07-16T19:19:17+00:00",
      "updated_at": "2023-10-07T09:22:02+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Retrieve a pipe

Retrieves a pipe object.

Parameters

id REQUIRED

The ID of the pipe you want to retrieve.

GET /pipes/:id

curl https://app.pipetower.com/api/pipes/:id \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "e47d20",
  "team_id": "n80b40",
  "name": "Check available Updates",
  "active": true,
  "trigger": {
    "type": "schedule",
    "event": "every_week",
    "execution": {
      "day": "monday",
      "time": "10"
    }
  },
  "steps": [
    {
      "order": 0,
      "type": "action",
      "event": "execute_action",
      "execution": {
        "action": "026nw2",
        "servers": [
          "r0em4n",
          "kbe67n",
          "b27a36"
        ]
      }
    },
    {
      "order": 1,
      "type": "notification",
      "event": "send_notification",
      "execution": {
        "channel": "email",
        "message": "Updates are available!",
        "conditions": [
          [
            {
              "condition_rule": "output_contains|value",
              "condition_field": "1|step_execute_action_action",
              "condition_value": "upgradable from:",
              "condition_server": "any_of_executed_servers"
            }
          ]
        ],
        "recipients": [
          "e86bn6"
        ]
      }
    }
  ],
  "tags": [],
  "created_at": "2023-07-16T19:19:17+00:00",
  "updated_at": "2023-10-07T09:22:02+00:00"
}

Retrieve a pipe's runs

Retrieves the runs of the specified pipe.

Parameters

id REQUIRED

The ID of the pipe for which you want to retrieve the runs.
limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /pipes/:id/runs

curl https://app.pipetower.com/api/pipes/:id/runs \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "e69vm3",
      "team_id": "n80b40",
      "status": "successful",
      "executable": {
        "id": "e47d20",
        "type": "Pipe",
        "name": "Check available Updates"
      },
      "runs": [
        "m60b76",
        "73r7k6"
      ],
      "created_at": "2023-10-08T07:19:04+00:00",
      "started_at": "2023-10-08T07:19:04+00:00",
      "finished_at": "2023-10-08T07:19:06+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Templates

Templates are reusable text files that you can copy to your server.

ENDPOINTS

GET /templates

GET /templates/:id

The template object

Attributes

id string

The unique identifier for the template.
team_id string

The ID of the team to which this template belongs.

THE TEMPLATE OBJECT

{
  "id": "kw386m",
  "team_id": "n80b40",
  "name": "NGINX server block",
  "file_name": "$DOMAIN.conf",
  "content": "server {\n  listen 80 default_server;\n  server_name $DOMAIN;\n\n  root \/var\/www\/$FOLDER\/htdocs;\n  index index.html;\n\n  location \/ {\n    try_files $uri $uri\/ =404;\n  }\n}",
  "tags": [],
  "created_at": "2023-09-10T10:51:02+00:00",
  "updated_at": "2023-09-23T15:02:32+00:00"
}

List all templates

Returns a list of your templates.

Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /templates

curl https://app.pipetower.com/api/templates \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "kw386m",
      "team_id": "n80b40",
      "name": "NGINX server block",
      "file_name": "$DOMAIN.conf",
      "content": "server {\n  listen 80 default_server;\n  server_name $DOMAIN;\n\n  root \/var\/www\/$FOLDER\/htdocs;\n  index index.html;\n\n  location \/ {\n    try_files $uri $uri\/ =404;\n  }\n}",
      "tags": [],
      "created_at": "2023-09-10T10:51:02+00:00",
      "updated_at": "2023-09-23T15:02:32+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Retrieve a template

Retrieves a template object.

Parameters

id REQUIRED

The ID of the template you want to retrieve.

GET /templates/:id

curl https://app.pipetower.com/api/templates/:id \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "kw386m",
  "team_id": "n80b40",
  "name": "NGINX server block",
  "file_name": "$DOMAIN.conf",
  "content": "server {\n  listen 80 default_server;\n  server_name $DOMAIN;\n\n  root \/var\/www\/$FOLDER\/htdocs;\n  index index.html;\n\n  location \/ {\n    try_files $uri $uri\/ =404;\n  }\n}",
  "tags": [],
  "created_at": "2023-09-10T10:51:02+00:00",
  "updated_at": "2023-09-23T15:02:32+00:00"
}

Teams

Teams are a group of people who can work together on their automation.

ENDPOINTS

GET /teams

GET /teams/:id

GET /teams/:id/vars

The team object

Attributes

id string

The unique identifier for the team.

THE TEAM OBJECT

{
  "id": "n80b40",
  "name": "Acme",
  "members": [
    {
      "name": "Joe Bloggs",
      "email": "jbloggs@pipetower.com",
      "role": "owner",
      "2fa_enabled": true
    },
    {
      "name": "Sarah Johnson",
      "email": "sjohnson@pipetower.com",
      "role": "admin",
      "2fa_enabled": true
    }
  ],
  "created_at": "2023-08-12T07:05:53+00:00",
  "updated_at": "2023-09-10T13:10:02+00:00"
}

List all teams

Returns a list of your teams.

Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /teams

curl https://app.pipetower.com/api/teams \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "n80b40",
      "name": "Acme",
      "members": [
        {
          "name": "Joe Bloggs",
          "email": "jbloggs@pipetower.com",
          "role": "owner",
          "2fa_enabled": true
        },
        {
          "name": "Sarah Johnson",
          "email": "sjohnson@pipetower.com",
          "role": "admin",
          "2fa_enabled": true
        }
      ],
      "created_at": "2023-08-12T07:05:53+00:00",
      "updated_at": "2023-09-10T13:10:02+00:00"
    },
    {...},
    {...}
  ],
  "meta": {...}
}

Retrieve a team

Retrieves a team object.

Parameters

id REQUIRED

The ID of the team you want to retrieve.

GET /teams/:id

curl https://app.pipetower.com/api/teams/:id \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "n80b40",
  "name": "Acme",
  "members": [
    {
      "name": "Joe Bloggs",
      "email": "jbloggs@pipetower.com",
      "role": "owner",
      "2fa_enabled": true
    },
    {
      "name": "Sarah Johnson",
      "email": "sjohnson@pipetower.com",
      "role": "admin",
      "2fa_enabled": true
    }
  ],
  "created_at": "2023-08-12T07:05:53+00:00",
  "updated_at": "2023-09-10T13:10:02+00:00"
}

Retrieve a team's variables

Retrieves the variables of the specified team.

Parameters

id REQUIRED

The ID of the team for which you want to retrieve the variables.
limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /teams/:id/vars

curl https://app.pipetower.com/api/teams/:id/vars \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "secret": false,
      "name": "SYSTEM_USER",
      "value": "morpheus"
    },
    {
      "secret": true,
      "name": "APP_KEY",
      "value": "***"
    },
    {...}
  ],
  "meta": {...}
}

Runs

Runs hold information about the execution of actions, workflows, or pipes.

ENDPOINTS

GET /runs

POST /runs

GET /runs/:id

The run object

Attributes

id string

The unique identifier for the run.
team_id string

The ID of the team to which this run belongs.

THE RUN OBJECT

{
  "id": "e0k229",
  "team_id": "n80b40",
  "status": "successful",
  "executable": {
    "id": "92eb93",
    "type": "Action",
    "name": "Install UFW"
  },
  "executions": [
    "5035k0",
    "w0v6m0"
  ],
  "created_at": "2023-10-07T10:26:40+00:00",
  "started_at": "2023-10-07T10:26:41+00:00",
  "finished_at": "2023-10-07T10:26:50+00:00"
}

List all runs

Returns a list of your runs.

Parameters

limit optional

A limit on the number of objects to be returned. Limit can range between 1 and 100. The default is 15.
page optional

The page of results you would like to retrieve.

GET /runs

curl https://app.pipetower.com/api/runs \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "data": [
    {
      "id": "e0k229",
      "team_id": "n80b40",
      "status": "successful",
      "executable": {
        "id": "92eb93",
        "type": "Action",
        "name": "Install UFW"
      },
      "executions": [
        "5035k0",
        "w0v6m0"
      ],
      "created_at": "2023-10-07T10:26:40+00:00",
      "started_at": "2023-10-07T10:26:41+00:00",
      "finished_at": "2023-10-07T10:26:50+00:00"
    },
    {
      "id": "e69vm3",
      "team_id": "n80b40",
      "status": "successful",
      "executable": {
        "id": "e47d20",
        "type": "Pipe",
        "name": "Check available Updates"
      },
      "runs": [
        "m60b76",
        "73r7k6"
      ],
      "created_at": "2023-10-08T07:19:04+00:00",
      "started_at": "2023-10-08T07:19:04+00:00",
      "finished_at": "2023-10-08T07:19:06+00:00"
    },
    {...}
  ],
  "meta": {...}
}

Create a run

To execute an action or a workflow on one or multiple servers, create a new run object.

Parameters

action_id CONDITIONALLY REQUIRED

The ID of the action you want to execute.
This field is required when workflow_id is not present.
workflow_id CONDITIONALLY REQUIRED

The ID of the workflow you want to execute.
This field is required when action_id is not present.
server_ids REQUIRED array

An array containing the server IDs on which you want to execute the action / workflow.

POST /runs

curl https://app.pipetower.com/api/runs \
  -H "Authorization: Bearer $API_TOKEN"
  -d action_id="92eb93"
  -d server_ids[]="r0em4n"
  -d server_ids[]="kbe67n"

RESPONSE

{
  "id": "e0k229",
  "team_id": "n80b40",
  "status": "pending",
  "executable": {
    "id": "92eb93",
    "type": "Action",
    "name": "Install UFW"
  },
  "executions": [
    "5035k0",
    "w0v6m0"
  ],
  "created_at": "2023-10-07T10:26:40+00:00",
  "started_at": null,
  "finished_at": null
}

Retrieve a run

Retrieves a run object.

Parameters

id REQUIRED

The ID of the run you want to retrieve.

GET /runs/:id

curl https://app.pipetower.com/api/runs/:id \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "e0k229",
  "team_id": "n80b40",
  "status": "successful",
  "executable": {
    "id": "92eb93",
    "type": "Action",
    "name": "Install UFW"
  },
  "executions": [
    "5035k0",
    "w0v6m0"
  ],
  "created_at": "2023-10-07T10:26:40+00:00",
  "started_at": "2023-10-07T10:26:41+00:00",
  "finished_at": "2023-10-07T10:26:50+00:00"
}

Run executions

Run executions hold information about a specific execution of an action or a workflow on a server, with details like status, exit code, output etc.

ENDPOINTS

GET /run-executions/:id

GET /run-executions/:id/details

The run execution object

Attributes

id string

The unique identifier for the run execution.
team_id string

The ID of the team to which this run execution belongs.

THE RUN EXECUTION OBJECT

{
  "id": "5035k0",
  "team_id": "n80b40",
  "run_id": "e0k229",
  "server_id": "r0em4n",
  "status": "successful",
  "executable": {
    "id": "92eb93",
    "type": "Action",
    "name": "Install UFW"
  },
  "results": [
    {
      "status": "successful",
      "type": "ActionStep",
      "name": "Install",
      "started_at": "2023-10-07T10:26:41+00:00",
      "finished_at": "2023-10-07T10:26:49+00:00"
    },
    {
      "status": "successful",
      "type": "ActionStep",
      "name": "Enable",
      "started_at": "2023-10-07T10:26:49+00:00",
      "finished_at": "2023-10-07T10:26:50+00:00"
    }
  ],
  "started_at": "2023-10-07T10:26:41+00:00",
  "finished_at": "2023-10-07T10:26:50+00:00"
}

Retrieve a run execution

Retrieves a run execution object.

Parameters

id REQUIRED

The ID of the run execution you want to retrieve.

GET /run-executions/:id

curl https://app.pipetower.com/api/run-executions/:id \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "5035k0",
  "team_id": "n80b40",
  "run_id": "e0k229",
  "server_id": "r0em4n",
  "status": "successful",
  "executable": {
    "id": "92eb93",
    "type": "Action",
    "name": "Install UFW"
  },
  "results": [
    {
      "status": "successful",
      "type": "ActionStep",
      "name": "Install",
      "started_at": "2023-10-07T10:26:41+00:00",
      "finished_at": "2023-10-07T10:26:49+00:00"
    },
    {
      "status": "successful",
      "type": "ActionStep",
      "name": "Enable",
      "started_at": "2023-10-07T10:26:49+00:00",
      "finished_at": "2023-10-07T10:26:50+00:00"
    }
  ],
  "started_at": "2023-10-07T10:26:41+00:00",
  "finished_at": "2023-10-07T10:26:50+00:00"
}

Retrieve a run execution's details

Retrieves the details of the specified run execution.

Parameters

id REQUIRED

The ID of the run execution for which you want to retrieve the details.

GET /run-executions/:id/details

curl https://app.pipetower.com/api/run-executions/:id/details \
  -H "Authorization: Bearer $API_TOKEN"

RESPONSE

{
  "id": "5035k0",
  "team_id": "n80b40",
  "run_id": "e0k229",
  "server_id": "r0em4n",
  "status": "successful",
  "executable": {
    "id": "92eb93",
    "type": "Action",
    "name": "Install UFW"
  },
  "results": [
    {
      "status": "successful",
      "type": "ActionStep",
      "name": "Install",
      "details": {
        "exit_code": "0",
        "type": "execute_command",
        "command": "sudo apt install ufw",
        "output": "[sudo] password for pipetower: \r\nReading package lists... 100%\r\n(...)"
      },
      "started_at": "2023-10-07T10:26:41+00:00",
      "finished_at": "2023-10-07T10:26:49+00:00"
    },
    {
      "status": "successful",
      "type": "ActionStep",
      "name": "Enable",
      "details": {
        "exit_code": "0",
        "type": "execute_command",
        "command": "sudo ufw enable",
        "output": "[sudo] password for pipetower: \r\nFirewall is active and enabled on system startup"
      },
      "started_at": "2023-10-07T10:26:49+00:00",
      "finished_at": "2023-10-07T10:26:50+00:00"
    }
  ],
  "started_at": "2023-10-07T10:26:41+00:00",
  "finished_at": "2023-10-07T10:26:50+00:00"
}