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. Create a new service account and associated API key on the Service account settings page. See Service accounts and API keys 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.
API keys are associated with Service accounts. You can view and manage your API keys on the Service account settings page.
Service accounts and API keys can be created by Team admins, Developers, and Restricted developers. See Roles for details.
Your API keys carry the privileges to complete sensitive operations, 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
"allowCachedMaxAge": 0,
7
"inputsZoneID": "zon20230615zelxgkdstfe",
8
"inputsZoneParamValuesHash": "",
9
"inputsZoneToken": "aip20230615zelxgkdstfe:zoneslug",
10
"paramValues": {
11
"limit": "20",
12
"user": "eric"
13
},
14
"resources": {
15
"db": "demo_db"
16
},
17
"slug": "hello_world"
18
}'

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

allowCachedMaxAge
integer
optional
id
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.

inputsZoneParamValuesHash
string
optional

Hash of the input values for caching purposes.

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

isCached
boolean

Whether the run being returned is a cached result.

runID
string

Unique ID of the task execution's run.

Response
Copied
1
{
2
"isCached": false,
3
"runID": "run20220215zv10o6s52qj"
4
}

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

id
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.

id
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

id
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

id
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
"zoneID": "",
46
"zoneToken": ""
47
}
48
}

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
"zoneID": "",
47
"zoneToken": ""
48
}
49
]
50
}

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

id
string
REQUIRED

Unique ID of the prompt.

Response

id
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

id
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

id
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
Show more
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

id
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

id
string
REQUIRED

The ID of the resource to update.

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 update. This field must match the kind of the existing resource.

Possible Values
airplane_postgres
bigquery
graphql
mailgun
mongodb
Show more
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

id
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

id
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

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 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

id
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.

id
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
Show more
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
}