API

The Airplane API enables customers to further integrate Airplane into their workflows. The API is loosely organized around top-level resources, is more RPC than REST, accepts JSON-encoded bodies, and returns JSON-encoded responses. The current API endpoints allow for programmatic execution of tasks and runbooks.

Getting started

To use the API to execute a task, you first need an API key. Download the Airplane CLI and generate a key by running:

bash
Copied
1
airplane apikeys create <token name>

See Authentication for details.

Once you have your API key, you need to find the slug of the task you wish to run. You can find your task's slug next to the task's name within the task editor or by running airplane tasks list from the CLI. Once you have the task slug, you can execute the task by running the following curl command:

bash
Copied
1
# Substitute YOUR_API_KEY_HERE with your API key
2
curl https://api.airplane.dev/v0/tasks/execute \
3
  -X POST \
4
  -H "X-Airplane-API-Key: YOUR_API_KEY_HERE" \
5
  -d '{
6
        "slug": "hello_world",
7
        "paramValues": {
8
            "limit": "10"
9
        },
10
    }'

If your team uses Environments, you can specify which environment the request should run against. To do so, add the header X-Airplane-Env-Slug: <YOUR ENV SLUG> to your request. If you do not specify an environment, the default environment will be used.

Executing the task returns a run ID:

json
Copied
1
{
2
  "runID": "run20220215zv10o6s52qj"
3
}

You can then use the run ID to check on the status of the run along with other metadata:

bash
Copied
1
curl https://api.airplane.dev/v0/runs/get \
2
  -H "X-Airplane-API-Key: YOUR_API_KEY_HERE" \
3
  -d 'id=run20220215zv10o6s52qj' \
4
  -G

Authentication

The Airplane API uses API keys to authenticate your requests. API keys are prefixed with tkn_. Authentication to the API is performed by supplying the X-Airplane-API-Key header. Runs and sessions created through the API are recorded as being run by API user.

You can view and manage your API keys with the Airplane CLI. To generate a new token:

bash
Copied
1
airplane apikeys create <token name>

API keys can be created by Team admins, Developers, and Restricted developers. See Roles for details.

Your API keys carry the privileges to execute every task and runbook your team owns so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, etc.

All API requests must be made over HTTPS. Any requests made over plain HTTP will fail. Requests without a valid API key will fail and return a 401 error.

bash
Copied
1
# Authenticated request example
2
curl https://api.airplane.dev/v0/runs/get \
3
    -H 'X-Airplane-API-Key: tkn_examplekey123456789EXAMPLEKEY1234567' \
4
    -d id=run20220222example \
5
    -G

Idempotency

The Airplane API supports idempotency which allows clients to safely retry requests without the risk of duplicating operations.

To take advantage of this, clients must include an Idempotency-Key header in their requests. This header is used to uniquely identify an API request across multiple retries. Airplane will store this identifier and ensure future requests with the same identifier are not processed again.

For example, say a client issues an HTTP request to execute a task via POST /v0/tasks/execute. The Airplane API receives the request, starts executing the task, but a network error prevents the API from responding to the client. The client can safely retry the request with the same Idempotency-Key and the API server will return the original request's response instead of re-executing the task.

All GET, PUT, and DELETE methods are safe to retry without any additional client logic. It is still safe to send an Idempotency-Key header with those requests, but it will have no effect.

For POST and PATCH requests, a client should generate a random UUID for each API request and send it via an Idempotency-Key header. For example:


Copied
1
Idempotency-Key: 4ff56c9a-c216-4cfa-84fe-e7a3aa887b84

The Airplane SDKs automatically generate this header and use it for retries.

Idempotency keys are only stored if a request returns a successful (2xx) HTTP status code. It is recommended to retry API requests that return a 429 or 5xx status code (excluding 501). HTTP responses that return a 429 status code will include a Retry-After header that identifies how long clients should wait before retrying.

The Airplane API retains idempotency keys for one hour. If a request is retried more than one hour after the initial request then it will be executed as if it was the first attempt.

If a POST or PATCH HTTP request includes an idempotency key, the HTTP response will include an Idempotency-Key header with an identical value in the response.

Errors

Airplane uses standard HTTP response codes to indicate the success or failure of an API request.

In general:

2xx - A successful request.
4xx - An error caused by the request payload. (e.g. an omitted required parameter, invalid API key, etc.)
5xx - An error with Airplane's servers.

Error responses always contain a human readable message (error) and sometimes contain an error code (code) intended for programatic use.

json
Copied
1
{
2
  "error": "Invalid body"
3
}

The following list documents all status codes that can be returned by the Airplane API.

200 Successful request.

400 The request payload was invalid. This often indicates the parameters were not correct.

401 An invalid API key was provided.

403 The provided API key does not have permissions to perform the request.

404 The requested resource does not exist.

409 The request conflicts with another active request.

423 The requested resource is currently being accessed by another active request.

429 Too many requests hit the API too quickly.

500 Airplane server error.

Tasks

A Task is a lightweight app that represents a single business operation for people at your company to execute.

The current tasks API is focused around allowing you to execute tasks. An instance of an executed task is called a run. See Runs API for how to track a run's status or fetch a run's output after you've executed a task.

Execute Task

POST /v0/tasks/execute

Execute a task with a set of parameter values and receive a run ID to track the task's execution. Check on the status of your newly created run with /runs/get.

Execute Task
Copied
1
curl https://api.airplane.dev/v0/tasks/execute \
2
  -X POST \
3
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
4
  -H "X-Airplane-Env-Slug: prod" \
5
  -d '{
6
    "inputsZoneID": "zon20230615zelxgkdstfe",
7
    "inputsZoneToken": "aip20230615zelxgkdstfe:zoneslug",
8
    "paramValues": {
9
        "limit": "20",
10
        "user": "eric"
11
    },
12
    "resources": {
13
        "db": "demo_db"
14
    },
15
    "slug": "hello_world"
16
}'

Headers

X-Airplane-Env-Slug

string

optional

Slug of the environment to execute the task in. Either an ID or a slug can be provided.

X-Airplane-Env-ID

string

optional

ID of the environment to execute the task in. Either an ID or a slug can be provided.

Body Parameters

string

optional

Unique ID of the task. You can find your task's ID by visiting the task's page on Airplane. The task ID is located at the end of the url.

e.g. the task ID for https://app.airplane.dev/tasks/tsk20210728zxb2vxn is tsk20210728zxb2vxn

Either an ID or a slug must be provided.

inputsZoneID

string

optional

Information about zone that inputs were saved in.

inputsZoneToken

string

optional

paramValues

key value

optional

Mapping of parameter slug to value. You can find your task's parameter slugs inside the task editor on Airplane or by running airplane tasks list from the CLI.

resources

key value

optional

Mapping of resource aliases to id identifiers used by the task.

slug

string

optional

Unique slug of the task. You can find your task's slug next to the task's name within the task editor on Airplane or by running airplane tasks list from the CLI.

Either an ID or a slug must be provided.

Response

runID

string

Unique ID of the task execution's run.

Response
Copied
1
{
2
    "runID": "run20220215zv10o6s52qj"
3
}

Runs

A run represents an instance of a task's execution. See Tasks API for how to execute tasks.

Get Run

GET /v0/runs/get

Get information about an existing run.

Get Run
Copied
1
curl https://api.airplane.dev/v0/runs/get \
2
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
3
  -d 'id=run20220215zv10o6s52qj' \
4
  -G

Query Parameters

string

REQUIRED

ID of the run to retrieve.

Response

activeAt

string

When the run became active. Empty if this run has not started yet.

cancelledAt

string

When the run was cancelled. Empty if this run was not cancelled.

cancelledBy

string

ID of the user who cancelled this run.

childRunIDs

array of string

Child runs of this run.

constraints

object

Constraints for this run. More details.

Show child attributes

createdAt

string

When this run was created.

createdBy

string

ID of the user that created this run.

failedAt

string

When the run failed. Empty if this run did not fail.

string

Unique ID of this run.

inputsZoneID

string

ID of the storage zone that was used for the run's inputs.

inputsZoneToken

string

Unique token used to identify the inputs in the previous zone.

isPrivate

boolean

Whether or not this run is private.

paramValues

key value

Mapping of parameter slug to value used in this run's execution.

params

array of object

Schema for the set of values users can provide when executing this run. More details.

Show child attributes

permissions

array of object

Explicit permissions of this run if it is private. More details.

Show child attributes

resources

key value

Mapping of resource name to resource ID of the resources that were used for this run. More details.

runtime

enum

Runtime that this run executed on. More details.

Possible Values

standard

workflow

sessionID

string

ID of the session this run was spawned from if triggered by a session.

status

enum

Status of this run.

Possible Values

NotStarted

Queued

Active

Succeeded

Failed

succeededAt

string

When the run succeeded. Empty if this run did not succeed.

taskID

string

ID of the task this run was spawned from if triggered by a task.

teamID

string

ID of the team that owns this run.

timeout

integer

Maximum amount of time in seconds the run could have executed for. More details.

zoneID

string

ID of the storage zone that the run used for its runs and outputs. Will be null if there was no storage zone, in which case logs and outputs will be in the airplane API.

Response
Copied
1
{
2
    "activeAt": "2022-01-11 22:32:45.707231+00",
3
    "cancelledAt": "2022-01-11 22:33:03.78416+00",
4
    "cancelledBy": "run20220111zlq2ig4",
5
    "childRunIDs": [],
6
    "constraints": {
7
        "labels": [
8
            {
9
                "key": "aws-region",
10
                "value": "west-2"
11
            }
12
        ]
13
    },
14
    "createdAt": "2022-01-11 22:32:45.601486+00",
15
    "createdBy": "usr20220103zlufhym",
16
    "failedAt": "2022-01-11 22:33:03.78416+00",
17
    "id": "run20220111zlq2ig4",
18
    "inputsZoneID": "zon20230224zu6zo7yyn65",
19
    "inputsZoneToken": "aip20230224zu6zo7yyn65:testzone",
20
    "isPrivate": true,
21
    "paramValues": {
22
        "limit": "20",
23
        "user": "eric"
24
    },
25
    "params": [
26
        {
27
            "component": "textarea",
28
            "constraints": {
29
                "optional": false,
30
                "options": {},
31
                "regex": "",
32
                "validate": ""
33
            },
34
            "default": {},
35
            "desc": "Email to use for selecting which user to edit.",
36
            "hidden": "{{true}}",
37
            "multi": false,
38
            "name": "User Email",
39
            "params": [],
40
            "slug": "user_email",
41
            "type": "string",
42
            "values": {}
43
        }
44
    ],
45
    "permissions": [
46
        {
47
            "action": "sessions.get",
48
            "roleID": "team_admin",
49
            "subGroupID": "grp20220222zaigy4h2bw3",
50
            "subUserID": "usr20211123zz1dv7z"
51
        }
52
    ],
53
    "resources": {
54
        "rest": "res20220208zmwoqk9"
55
    },
56
    "runtime": "standard",
57
    "sessionID": "",
58
    "status": "Succeeded",
59
    "succeededAt": "2022-01-11 22:33:03.78416+00",
60
    "taskID": "tsk20210728zxb2vxn",
61
    "teamID": "tea20220103zvy4auu",
62
    "timeout": 3600,
63
    "zoneID": "zon20230224zu6zo7yyn65"
64
}

Get Run Logs

GET /v0/runs/getLogs

Get logs from an existing run.

Get Run Logs
Copied
1
curl https://api.airplane.dev/v0/runs/getLogs \
2
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
3
  -d 'runID=run20220215zv10o6s52qj' \
4
  -G

Query Parameters

runID

string

REQUIRED

ID of the run to retrieve.

Response

logs

array of object

Show child attributes

next_token

string

prev_token

string

runID

string

Response
Copied
1
{
2
    "logs": [
3
        {
4
            "insertID": "",
5
            "level": "",
6
            "taskSlug": "",
7
            "text": "",
8
            "timestamp": ""
9
        }
10
    ],
11
    "next_token": "",
12
    "prev_token": "",
13
    "runID": ""
14
}

Get Run Outputs

GET /v0/runs/getOutputs

Get outputs from an existing run.

Get Run Outputs
Copied
1
curl https://api.airplane.dev/v0/runs/getOutputs \
2
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
3
  -d 'id=run20220215zv10o6s52qj' \
4
  -G

Query Parameters

string

REQUIRED

ID of the run to retrieve.

Response

output

key value

Outputs from this run. More details.

Response
Copied
1
{
2
    "output": {
3
        "element": "hydrogen",
4
        "weight": "1.008"
5
    }
6
}

List Runs

GET /v0/runs/list

List Runs
Copied
1
curl https://api.airplane.dev/v0/runs/list \
2
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
3
  -d 'taskID=tsk20210728zxb2vxn' \
4
  -d 'taskSlug=hello_world' \
5
  -d 'since=2022-01-01T12:00:00-00:00' \
6
  -d 'until=2022-01-01T13:00:00-00:00' \
7
  -d 'limit=10' \
8
  -d 'page=0' \
9
  -G

Query Parameters

taskID

string

optional

Unique ID of the task to fetch runs for.

taskSlug

string

optional

Unique slug of the task to fetch runs for.

since

string

optional

Fetch runs last updated after this time (RFC 3339 format).

until

string

optional

Fetch runs last updated before this time (RFC 3339 format).

limit

integer

optional

Number of results per call. Accepted values: 0 - 50. Default: 50.

page

integer

optional

The offset used for this page of results.

Response

runs

array of object

Retrieved runs.

Show child attributes

Response
Copied
1
{
2
    "runs": [
3
        {
4
            "activeAt": "2022-01-11 22:32:45.707231+00",
5
            "cancelledAt": "2022-01-11 22:33:03.78416+00",
6
            "cancelledBy": "run20220111zlq2ig4",
7
            "childRunIDs": [],
8
            "constraints": {
9
                "labels": [
10
                    {
11
                        "key": "aws-region",
12
                        "value": "west-2"
13
                    }
14
                ]
15
            },
16
            "createdAt": "2022-01-11 22:32:45.601486+00",
17
            "createdBy": "usr20220103zlufhym",
18
            "failedAt": "2022-01-11 22:33:03.78416+00",
19
            "id": "run20220111zlq2ig4",
20
            "inputsZoneID": "zon20230224zu6zo7yyn65",
21
            "inputsZoneToken": "aip20230224zu6zo7yyn65:testzone",
22
            "isPrivate": true,
23
            "paramValues": {
24
                "limit": "20",
25
                "user": "eric"
26
            },
27
            "params": [
28
                {
29
                    "component": "textarea",
30
                    "constraints": {
31
                        "optional": false,
32
                        "options": {},
33
                        "regex": "",
34
                        "validate": ""
35
                    },
36
                    "default": {},
37
                    "desc": "Email to use for selecting which user to edit.",
38
                    "hidden": "{{true}}",
39
                    "multi": false,
40
                    "name": "User Email",
41
                    "params": [],
42
                    "slug": "user_email",
43
                    "type": "string",
44
                    "values": {}
45
                }
46
            ],
47
            "permissions": [
48
                {
49
                    "action": "sessions.get",
50
                    "roleID": "team_admin",
51
                    "subGroupID": "grp20220222zaigy4h2bw3",
52
                    "subUserID": "usr20211123zz1dv7z"
53
                }
54
            ],
55
            "resources": {
56
                "rest": "res20220208zmwoqk9"
57
            },
58
            "runtime": "standard",
59
            "sessionID": "",
60
            "status": "Succeeded",
61
            "succeededAt": "2022-01-11 22:33:03.78416+00",
62
            "taskID": "tsk20210728zxb2vxn",
63
            "teamID": "tea20220103zvy4auu",
64
            "timeout": 3600,
65
            "zoneID": "zon20230224zu6zo7yyn65"
66
        }
67
    ]
68
}

Cancel Run

POST /v0/runs/cancel

Cancel a run. Check on the status of your run with /runs/get.

Cancel Run
Copied
1
curl https://api.airplane.dev/v0/runs/cancel \
2
  -X POST \
3
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
4
  -d '{
5
    "runID": "run20220111zlq2ig4"
6
}'

Body Parameters

runID

string

REQUIRED

Unique ID of the run to cancel.

Prompts

A prompt is used to gather user input during a task's execution. See Prompts to see how prompts are used.

Get Prompt

GET /v0/prompts/get

Get information about an existing prompt.

Get Prompt
Copied
1
curl https://api.airplane.dev/v0/prompts/get \
2
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
3
  -d 'id=pmt20221122zyydx3rho2t' \
4
  -G

Query Parameters

string

REQUIRED

ID of the prompt to retrieve.

Response

prompt

object

Retrieved prompt.

Show child attributes

Response
Copied
1
{
2
    "prompt": {
3
        "cancelText": "Reject workflow.",
4
        "cancelledAt": "2022-01-11 22:32:46.601486+00",
5
        "cancelledBy": "usr20220103zlufhym",
6
        "confirmText": "Approve workflow.",
7
        "createdAt": "2022-01-11 22:32:45.601486+00",
8
        "description": "Prompt workflow description.",
9
        "id": "pmt20221122zyydx3rho2t",
10
        "reviewers": {
11
            "allowSelfApprovals": false,
12
            "groups": [],
13
            "users": []
14
        },
15
        "runID": "run20220111zlq2ig4",
16
        "schema": {
17
            "parameters": [
18
                {
19
                    "component": "textarea",
20
                    "constraints": {
21
                        "allowUnknownKeys": false,
22
                        "optional": false,
23
                        "options": {},
24
                        "regex": "",
25
                        "validate": ""
26
                    },
27
                    "default": {},
28
                    "desc": "Email to use for selecting which user to edit.",
29
                    "hidden": "{{true}}",
30
                    "multi": false,
31
                    "name": "User Email",
32
                    "parameters": [],
33
                    "slug": "user_email",
34
                    "type": "string",
35
                    "values": {}
36
                }
37
            ]
38
        },
39
        "submittedAt": "2022-01-11 22:32:46.601486+00",
40
        "submittedBy": "usr20220103zlufhym",
41
        "values": {
42
            "limit": "20",
43
            "user": "eric"
44
        }
45
    }
46
}

List Prompts

GET /v0/prompts/list

List prompts from an existing run.

List Prompts
Copied
1
curl https://api.airplane.dev/v0/prompts/list \
2
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
3
  -d 'runID=run20220215zv10o6s52qj' \
4
  -G

Query Parameters

runID

string

REQUIRED

ID of the run to retrieve prompts for.

Response

prompts

array of object

Retrieved prompts.

Show child attributes

Response
Copied
1
{
2
    "prompts": [
3
        {
4
            "cancelText": "Reject workflow.",
5
            "cancelledAt": "2022-01-11 22:32:46.601486+00",
6
            "cancelledBy": "usr20220103zlufhym",
7
            "confirmText": "Approve workflow.",
8
            "createdAt": "2022-01-11 22:32:45.601486+00",
9
            "description": "Prompt workflow description.",
10
            "id": "pmt20221122zyydx3rho2t",
11
            "reviewers": {
12
                "allowSelfApprovals": false,
13
                "groups": [],
14
                "users": []
15
            },
16
            "runID": "run20220111zlq2ig4",
17
            "schema": {
18
                "parameters": [
19
                    {
20
                        "component": "textarea",
21
                        "constraints": {
22
                            "allowUnknownKeys": false,
23
                            "optional": false,
24
                            "options": {},
25
                            "regex": "",
26
                            "validate": ""
27
                        },
28
                        "default": {},
29
                        "desc": "Email to use for selecting which user to edit.",
30
                        "hidden": "{{true}}",
31
                        "multi": false,
32
                        "name": "User Email",
33
                        "parameters": [],
34
                        "slug": "user_email",
35
                        "type": "string",
36
                        "values": {}
37
                    }
38
                ]
39
            },
40
            "submittedAt": "2022-01-11 22:32:46.601486+00",
41
            "submittedBy": "usr20220103zlufhym",
42
            "values": {
43
                "limit": "20",
44
                "user": "eric"
45
            }
46
        }
47
    ]
48
}

Cancel Prompt

POST /v0/prompts/cancel

Cancel a prompt.

Cancel Prompt
Copied
1
curl https://api.airplane.dev/v0/prompts/cancel \
2
  -X POST \
3
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
4
  -d '{
5
    "id": "pmt20221122zyydx3rho2t"
6
}'

Body Parameters

string

REQUIRED

Unique ID of the prompt.

Response

string

Unique ID of the prompt.

Response
Copied
1
{
2
    "id": "pmt20221122zyydx3rho2t"
3
}

Submit Prompt

POST /v0/prompts/submit

Submit a prompt with a set of parameter values.

Submit Prompt
Copied
1
curl https://api.airplane.dev/v0/prompts/submit \
2
  -X POST \
3
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
4
  -d '{
5
    "id": "pmt20221122zyydx3rho2t",
6
    "values": {
7
        "limit": "20",
8
        "user": "eric"
9
    }
10
}'

Body Parameters

string

REQUIRED

Unique ID of the prompt.

values

key value

optional

Mapping of parameter slug to value. You can find your prompt's parameter slugs on the Airplane runs page or by fetching the prompt via the API.

Response

string

Unique ID of the prompt.

Response
Copied
1
{
2
    "id": "pmt20221122zyydx3rho2t"
3
}

Resources

Resources in Airplane allow you to easily configure connections to external systems like databases and APIs and use them in your tasks and runbooks. See Resources for more information.

Create a resource

POST /v0/resources/create

Create a new Airplane resource.

Create a resource
Copied
1
curl https://api.airplane.dev/v0/resources/create \
2
  -X POST \
3
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
4
  -d '{
5
    "isPrivate": false,
6
    "kind": "postgres",
7
    "name": "My Database",
8
    "permissions": [
9
        {
10
            "action": "sessions.get",
11
            "roleID": "team_admin",
12
            "subGroupID": "grp20220222zaigy4h2bw3",
13
            "subUserID": "usr20211123zz1dv7z"
14
        }
15
    ],
16
    "resource": {},
17
    "slug": "my_database"
18
}'

Body Parameters

isPrivate

boolean

optional

If true, the resource is private and can only be accessed by specific members or groups. If false, the resource is public and can be accessed by all team members who have access to resources. This field must be set to true for permissions to take effect.

kind

enum

REQUIRED

The kind of resource to create.

Possible Values

airplane_postgres

bigquery

graphql

mailgun

mongodb

name

string

REQUIRED

permissions

array of object

optional

Dictates which users and groups can access this resource. Permissions can only be set on private resources.

Show child attributes

resource

key value

REQUIRED

The resource configuration. The fields in this object depend on the kind of resource.

slug

string

REQUIRED

Response

string

ID of the resource that was created.

Response
Copied
1
{
2
    "id": ""
3
}

Update a resource

POST /v0/resources/update

Update an existing Airplane resource by id using PUT semantics.

Update a resource
Copied
1
curl https://api.airplane.dev/v0/resources/update \
2
  -X POST \
3
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
4
  -d '{
5
    "id": "res20230911zuhm71k",
6
    "isPrivate": false,
7
    "kind": "postgres",
8
    "name": "My Database",
9
    "permissions": [
10
        {
11
            "action": "sessions.get",
12
            "roleID": "team_admin",
13
            "subGroupID": "grp20220222zaigy4h2bw3",
14
            "subUserID": "usr20211123zz1dv7z"
15
        }
16
    ],
17
    "resource": {},
18
    "slug": "my_database"
19
}'

Body Parameters

string

REQUIRED

The ID of the resource to update.

isPrivate

boolean

optional

kind

enum

REQUIRED

The kind of resource to update. This field must match the kind of the existing resource.

Possible Values

airplane_postgres

bigquery

graphql

mailgun

mongodb

name

string

REQUIRED

permissions

array of object

optional

Dictates which users and groups can access this resource. Permissions can only be set on private resources.

Show child attributes

resource

key value

REQUIRED

The resource configuration. The fields in this object depend on the kind of resource.

slug

string

REQUIRED

Response

string

ID of the resource that was updated.

Response
Copied
1
{
2
    "id": ""
3
}

Resource bodies

Each resource operation returns or requires a resource object that depends on the resource kind.

json
Copied
1
{
2
  "host": "34.1.2.3",
3
  "port": "5432",
4
  "database": "my_database",
5
  "username": "username",
6
  "password": "password",
7
  "ssl": "require",
8
  // Optional SSH tunneling configuration
9
  "sshHost": "host",
10
  "sshPort": "5432",
11
  "sshUsername": "username",
12
  "sshPrivateKey": "private_key",
13
}

Runbooks

Since Runbooks launched, a number of Tasks features shipped that bring Tasks to parity with Runbooks. For many use-cases, you may prefer to use a Task over a Runbook. To learn more, see Migrate to Tasks.

A Runbook is a multi-step, human-in-the-loop workflow. Runbooks are able to take a set of top-level parameters, run one or more functions, and generate output at each step of the way.

The current runbooks API is focused around allowing you to execute runbooks. Each instance of an executed runbook is called a session. See Sessions API for how to track a session's status after you've executed a runbook.

Execute Runbook

POST /v0/runbooks/execute

Execute a runbook and receive a session ID to track the runbook's execution. Check on the status of your newly created session with /sessions/get.

Execute Runbook
Copied
1
curl https://api.airplane.dev/v0/runbooks/execute \
2
  -X POST \
3
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
4
  -H "X-Airplane-Env-Slug: prod" \
5
  -d '{
6
    "paramValues": {
7
        "limit": "20",
8
        "user": "eric"
9
    },
10
    "slug": "hello_world"
11
}'

Headers

X-Airplane-Env-Slug

string

optional

Slug of the environment to execute the runbook in. Either an ID or a slug can be provided.

X-Airplane-Env-ID

string

optional

ID of the environment to execute the runbook in. Either an ID or a slug can be provided.

Body Parameters

string

optional

Unique ID of the runbook. You can find your runbook's ID by visiting the runbook's page on Airplane. The runbook ID is located at the end of the url.

e.g. the runbook ID for https://app.airplane.dev/runbooks/rbk20220120z15kl79 is rbk20220120z15kl79

paramValues

key value

optional

Mapping of parameter slug to value. You can find your runbooks's parameter slugs inside the runbook editor on Airplane.

slug

string

optional

Unique slug of the runbook. You can find your runbook's slug next to the runbook's name within the runbook editor on Airplane.

Either an ID or a slug must be provided.

Response

sessionID

string

Unique ID of the runbook's session.

Response
Copied
1
{
2
    "sessionID": "ses20220120za1pskd"
3
}

Sessions

A session represents an instance of a runbook's execution. See Runbooks API for how to execute runbooks.

Get Session

GET /v0/sessions/get

Get information about an existing session.

Get Session
Copied
1
curl https://api.airplane.dev/v0/sessions/get \
2
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
3
  -d 'id=ses20220120za1pskd' \
4
  -G

Query Parameters

string

REQUIRED

ID of the session to retrieve.

Response

createdAt

string

When this session was created.

createdBy

string

ID of the user that created this session.

string

Unique ID of this session.

isPrivate

boolean

Whether or not the session is private.

name

string

Name of this session.

paramValues

key value

Mapping of parameter slug to value used in this session's execution.

params

array of object

Schema for the set of values users can provide when executing this session. More details.

Show child attributes

permissions

array of object

Explicit permissions of this session if it is private. More details.

Show child attributes

runbookID

string

ID of the runbook this session was spawned from if triggered from a runbook.

status

enum

Status of this session.

Possible Values

Pending

Active

Waiting

Succeeded

Failed

teamID

string

ID of the team that owns this session.

updatedAt

string

When this session was updated.

updatedBy

string

ID of the user who updated this session.

Response
Copied
1
{
2
    "createdAt": "2022-01-11 22:32:45.601486+00",
3
    "createdBy": "usr20220103zlufhym",
4
    "id": "ses20220120za1pskd",
5
    "isPrivate": true,
6
    "name": "MySession",
7
    "paramValues": {
8
        "limit": "20",
9
        "user": "eric"
10
    },
11
    "params": [
12
        {
13
            "component": "textarea",
14
            "constraints": {
15
                "optional": false,
16
                "options": {},
17
                "regex": "",
18
                "validate": ""
19
            },
20
            "default": {},
21
            "desc": "Email to use for selecting which user to edit.",
22
            "hidden": "{{true}}",
23
            "multi": false,
24
            "name": "User Email",
25
            "params": [],
26
            "slug": "user_email",
27
            "type": "string",
28
            "values": {}
29
        }
30
    ],
31
    "permissions": [
32
        {
33
            "action": "sessions.get",
34
            "roleID": "team_admin",
35
            "subGroupID": "grp20220222zaigy4h2bw3",
36
            "subUserID": "usr20211123zz1dv7z"
37
        }
38
    ],
39
    "runbookID": "rbk20220120z15kl79",
40
    "status": "Succeeded",
41
    "teamID": "tea20220103zvy4auu",
42
    "updatedAt": "2022-01-11 22:35:45.238512+00",
43
    "updatedBy": "ses20220120za1pskd"
44
}

List Sessions

GET /v0/sessions/list

List Sessions
Copied
1
curl https://api.airplane.dev/v0/sessions/list \
2
  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
3
  -d 'runbookID=rbk20220120z15kl79' \
4
  -d 'updatedAfter=2022-01-01T12:00:00-00:00' \
5
  -d 'updatedBefore=2022-01-01T13:00:00-00:00' \
6
  -d 'limit=10' \
7
  -d 'page=0' \
8
  -G

Query Parameters

runbookID

string

optional

Only fetch sessions for this specific runbook.

updatedAfter

string

optional

Fetch sessions last updated after this time (RFC 3339 format).

updatedBefore

string

optional

Fetch sessions last updated before this time (RFC 3339 format).

limit

integer

optional

Number of results per call. Accepted values: 0 - 50. Default: 50.

page

integer

optional

The offset used for this page of results.

Response

sessions

array of object

Retrieved sessions.

Show child attributes

Response
Copied
1
{
2
    "sessions": [
3
        {
4
            "createdAt": "2022-01-11 22:32:45.601486+00",
5
            "createdBy": "usr20220103zlufhym",
6
            "id": "ses20220120za1pskd",
7
            "isPrivate": true,
8
            "name": "MySession",
9
            "paramValues": {
10
                "limit": "20",
11
                "user": "eric"
12
            },
13
            "params": [
14
                {
15
                    "component": "textarea",
16
                    "constraints": {
17
                        "optional": false,
18
                        "options": {},
19
                        "regex": "",
20
                        "validate": ""
21
                    },
22
                    "default": {},
23
                    "desc": "Email to use for selecting which user to edit.",
24
                    "hidden": "{{true}}",
25
                    "multi": false,
26
                    "name": "User Email",
27
                    "params": [],
28
                    "slug": "user_email",
29
                    "type": "string",
30
                    "values": {}
31
                }
32
            ],
33
            "permissions": [
34
                {
35
                    "action": "sessions.get",
36
                    "roleID": "team_admin",
37
                    "subGroupID": "grp20220222zaigy4h2bw3",
38
                    "subUserID": "usr20211123zz1dv7z"
39
                }
40
            ],
41
            "runbookID": "rbk20220120z15kl79",
42
            "status": "Succeeded",
43
            "teamID": "tea20220103zvy4auu",
44
            "updatedAt": "2022-01-11 22:35:45.238512+00",
45
            "updatedBy": "ses20220120za1pskd"
46
        }
47
    ]
48
}