API
Getting started
bashCopied1airplane apikeys create <token name>
airplane tasks list
from
the CLI. Once you have the task slug, you can execute the task by running the following curl
command:bashCopied1# Substitute YOUR_API_KEY_HERE with your API key2curl 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}'
X-Airplane-Env-Slug: <YOUR ENV SLUG>
to your
request. If you do not specify an environment, the default environment will be used.jsonCopied1{2"runID": "run20220215zv10o6s52qj"3}
bashCopied1curl https://api.airplane.dev/v0/runs/get \2-H "X-Airplane-API-Key: YOUR_API_KEY_HERE" \3-d 'id=run20220215zv10o6s52qj' \4-G
Authentication
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
.bashCopied1airplane apikeys create <token name>
Team admins
, Developers
, and Restricted developers
. See
Roles for details.401
error.bashCopied1# Authenticated request example2curl https://api.airplane.dev/v0/runs/get \3-H 'X-Airplane-API-Key: tkn_examplekey123456789EXAMPLEKEY1234567' \4-d id=run20220222example \5-G
Idempotency
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.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.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.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:Copied1Idempotency-Key: 4ff56c9a-c216-4cfa-84fe-e7a3aa887b84
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.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
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
) and sometimes contain an error
code (code
) intended for programatic use.jsonCopied1{2"error": "Invalid body"3}
Tasks
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
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 TaskCopied1curl 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
Slug of the environment to execute the task in. Either an ID or a slug can be provided.
ID of the environment to execute the task in. Either an ID or a slug can be provided.
Body Parameters
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.
Information about zone that inputs were saved in.
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.
Mapping of resource aliases to id identifiers used by the task.
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
Unique ID of the task execution's run.
ResponseCopied1{2"runID": "run20220215zv10o6s52qj"3}
Runs
Get Run
Get information about an existing run.
Get RunCopied1curl 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 of the run to retrieve.
Response
When the run became active. Empty if this run has not started yet.
When the run was cancelled. Empty if this run was not cancelled.
ID of the user who cancelled this run.
Child runs of this run.
When this run was created.
ID of the user that created this run.
When the run failed. Empty if this run did not fail.
Unique ID of this run.
ID of the storage zone that was used for the run's inputs.
Unique token used to identify the inputs in the previous zone.
Whether or not this run is private.
Mapping of parameter slug to value used in this run's execution.
Schema for the set of values users can provide when executing this run. More details.
Explicit permissions of this run if it is private. More details.
Mapping of resource name to resource ID of the resources that were used for this run. More details.
ID of the session this run was spawned from if triggered by a session.
Status of this run.
Possible Values |
NotStarted |
Queued |
Active |
Succeeded |
Failed |
When the run succeeded. Empty if this run did not succeed.
ID of the task this run was spawned from if triggered by a task.
ID of the team that owns this run.
Maximum amount of time in seconds the run could have executed for. More details.
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.
ResponseCopied1{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 logs from an existing run.
Get Run LogsCopied1curl https://api.airplane.dev/v0/runs/getLogs \2-H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \3-d 'runID=run20220215zv10o6s52qj' \4-G
Query Parameters
ID of the run to retrieve.
Response
ResponseCopied1{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 outputs from an existing run.
Get Run OutputsCopied1curl 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 of the run to retrieve.
Response
Outputs from this run. More details.
ResponseCopied1{2"output": {3"element": "hydrogen",4"weight": "1.008"5}6}
List Runs
List RunsCopied1curl 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
Unique ID of the task to fetch runs for.
Unique slug of the task to fetch runs for.
Fetch runs last updated after this time (RFC 3339 format).
Fetch runs last updated before this time (RFC 3339 format).
Number of results per call. Accepted values: 0 - 50. Default: 50.
The offset used for this page of results.
Response
Retrieved runs.
ResponseCopied1{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
Cancel a run. Check on the status of your run with /runs/get.
Cancel RunCopied1curl 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
Unique ID of the run to cancel.
Prompts
Get Prompt
Get information about an existing prompt.
Get PromptCopied1curl 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 of the prompt to retrieve.
Response
Retrieved prompt.
ResponseCopied1{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
List prompts from an existing run.
List PromptsCopied1curl https://api.airplane.dev/v0/prompts/list \2-H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \3-d 'runID=run20220215zv10o6s52qj' \4-G
Query Parameters
ID of the run to retrieve prompts for.
Response
Retrieved prompts.
ResponseCopied1{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
Cancel a prompt.
Cancel PromptCopied1curl 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
Unique ID of the prompt.
Response
Unique ID of the prompt.
ResponseCopied1{2"id": "pmt20221122zyydx3rho2t"3}
Submit Prompt
Submit a prompt with a set of parameter values.
Submit PromptCopied1curl 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
Unique ID of the prompt.
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
Unique ID of the prompt.
ResponseCopied1{2"id": "pmt20221122zyydx3rho2t"3}
Resources
Create a resource
Create a new Airplane resource.
Create a resourceCopied1curl 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
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.
The kind of resource to create.
Possible Values |
airplane_postgres |
bigquery |
graphql |
mailgun |
mongodb |
Show more |
Dictates which users and groups can access this resource. Permissions can only be set on private resources.
The resource configuration. The fields in this object depend on the kind of resource.
Response
ID of the resource that was created.
ResponseCopied1{2"id": ""3}
Update a resource
Update an existing Airplane resource by id using PUT semantics.
Update a resourceCopied1curl 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
The ID of the resource to update.
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.
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 |
Dictates which users and groups can access this resource. Permissions can only be set on private resources.
The resource configuration. The fields in this object depend on the kind of resource.
Response
ID of the resource that was updated.
ResponseCopied1{2"id": ""3}
Resource bodies
resource
object that depends on the resource kind.jsonCopied1{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 configuration9"sshHost": "host",10"sshPort": "5432",11"sshUsername": "username",12"sshPrivateKey": "private_key",13}
jsonCopied1{2"baseURL": "https://api.example.com/path",3"headers": { "header": "value" }4}
jsonCopied1{2"apiKey": "my_api_key",3"domain": "my_domain"4}
jsonCopied1{2"baseURL": "https://api.example.com/path",3"headers": { "header": "value" }4}
jsonCopied1{2"apiKey": "my_api_key"3}
Runbooks
session
. See Sessions API for how to track
a session's status after you've executed a runbook.Execute Runbook
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 RunbookCopied1curl 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
Slug of the environment to execute the runbook in. Either an ID or a slug can be provided.
ID of the environment to execute the runbook in. Either an ID or a slug can be provided.
Body Parameters
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
Mapping of parameter slug to value. You can find your runbooks's parameter slugs inside the runbook editor on Airplane.
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
Unique ID of the runbook's session.
ResponseCopied1{2"sessionID": "ses20220120za1pskd"3}
Sessions
Get Session
Get information about an existing session.
Get SessionCopied1curl 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 of the session to retrieve.
Response
When this session was created.
ID of the user that created this session.
Unique ID of this session.
Whether or not the session is private.
Name of this session.
Mapping of parameter slug to value used in this session's execution.
Schema for the set of values users can provide when executing this session. More details.
Explicit permissions of this session if it is private. More details.
ID of the runbook this session was spawned from if triggered from a runbook.
ID of the team that owns this session.
When this session was updated.
ID of the user who updated this session.
ResponseCopied1{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
List SessionsCopied1curl 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
Only fetch sessions for this specific runbook.
Fetch sessions last updated after this time (RFC 3339 format).
Fetch sessions last updated before this time (RFC 3339 format).
Number of results per call. Accepted values: 0 - 50. Default: 50.
The offset used for this page of results.
Response
Retrieved sessions.
ResponseCopied1{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}