REST task configuration

Configure a task's metadata as code
Task configuration defines the core metadata of an Airplane task in a .task.yaml or .task.json task definition file; this includes all information like the task name and parameters aside from the actual code that is executed when the task is run.
While tasks can be configured in the cloud using Studio with cloud workspaces, defining tasks as code is advantageous because it allows you to reap the benefits of version control; you can view the current state of a task and its history, subject tasks to the same code review and deploy mechanisms as the rest of your codebase, or roll back a task to a previous commit.
If you do edit the task in a cloud workspace, you can rerun airplane tasks init --from YOUR_TASK_SLUG path/to/defn.task.yaml to sync changes back to your task definition file.
The following is a complete reference of fields supported in .task.yaml or .task.json task definition file.

Standard fields
The fields below apply to all task definitions, regardless of the type of task.
slug
string
REQUIRED
A unique identifier that ties this definition file to a task in Airplane. This cannot be changed (a different slug will end up creating a new task).
Slugs must:
  • Be fewer than 50 characters long
  • Use only lowercase letters, numbers, and underscores
  • Start with a lowercase letter
name
string
REQUIRED
User-facing name for the task. This can be changed.
description
string
User-facing description for the task. This can be changed.
parameters
list
A list of parameters. Each parameter is a user-facing field to input data into the task.
Example:
yaml
Copied
1
parameters:
2
- slug: name
3
  name: Name
4
  type: shorttext
5
  description: The user's name.
6
  default: Alfred Pennyworth
7
  required: false
8
  options:
9
  - Alfred Pennyworth
10
  - Bruce Wayne
11
  regex: "^[a-zA-Z ]+$"
parameters.slug
string
REQUIRED
Unique identifier for the parameter. This is the identifier you'll use to interpolate parameters into arguments, pass them when calling from the CLI, etc.
parameters.name
string
REQUIRED
User-facing name for the parameter.
parameters.type
enum
REQUIRED
Possible Values
shorttextYour commonly used string input
longtextA string, but with a larger input box for users
sqlSimilar to Long Text inputs but offer SQL syntax highlighting
booleanPresented as on/off toggles
uploadAllows users to upload a file
Show more
The type of the parameter. See Parameter types for more information.
parameters.description
string
User-facing description of the parameter.
parameters.required
boolean
Default
true
Whether the parameter is required.
parameters.multi
boolean
Default
false
Whether the parameter is a list parameter or not. See Multi parameters for more information.
parameters.default
string/number/boolean
The default value of the parameter. The type depends on the type of the parameter.
parameters.options
list of string/number/boolean/object
Constrains the value of parameter to a list of options.
The type depends on the type of the parameter.
You can optionally add a label to each option. Labels are shown to the user instead of the value. To add a label, the option should be an object with fields label and value.
Example:
yaml
Copied
1
options:
2
- Alfred Pennyworth
3
- Bruce Wayne
4
- label: BW
5
  value: Bruce Wayne
For more information, see Select options.
parameters.regex
string
Allows you to more dynamically control what values are permitted. For more information, see Regular expressions.
requireRequests
boolean
Default
false
If true, a task must be requested before it can start executing. This disables direct execution, including schedules.
Requiring requests will disable schedules. Any existing schedules will be paused on the next attempted execution.
allowSelfApprovals
boolean
Default
true
If true, a request can be approved by the requestor.
restrictCallers
list of strings ("task" or "view")
Default
[]
The restrict callers execute rule disables direct execution of a task in the web UI and hides the task in the library. This rule can be configured to allow the task to be called from other tasks/runbooks and views.
timeout
number (in seconds)
Default
3600 (1 hour)
Limits how long a task can run before it is automatically cancelled.
Maximum of 43200 (12 hours)
For more information, see timeouts.
allowCachedMaxAge
number (in seconds)
If set, runs with identical inputs within the configured age (in seconds) may get cached results.
For more information, see server-side task caching.
constraints
object
Restricts this task to run only on agents with matching labels.
Example:
yaml
Copied
1
constraints:
2
  aws-region: us-west-2
For more information, see Run constraints.
schedules
object
Mapping of unique identifiers to schedules that should be deployed with the task.
For more information, see Schedules.
Example:
yaml
Copied
1
schedules:
2
  my_first_schedule:
3
    cron: 0 0 * * *
4
    name: My First Schedule
5
    description: This is my first daily midnight UTC schedule!
6
    paramValues:
7
      my_first_param: my_first_param_value
The unique identifier is used to add, update and remove schedules as changes are made to the task definition file. Adding a new entry will create a new schedule, modifying an entry will update the schedule and removing an entry will pause the schedule.
The unique identifier must adhere to the slug format.
schedules.cron
string
REQUIRED
Cron string of the schedule. To see acceptable formats, see Cron syntax.
schedules.name
string
Name of the schedule.
schedules.description
string
Description of the schedule.
schedules.paramValues
object
Map of param slugs and values to pass to the task on each run.
resources
object
Mapping of resource aliases to resource slugs. Slugs for your resource can be found in the resource settings.
For more information on resource attachments, see resource attachments.
Example:
yaml
Copied
1
resources:
2
  db: prod_postgres_db
If you would like to use the resource slug as the alias for all resources passed into this task, you can also use a list shorthand:
yaml
Copied
1
resources:
2
  - prod_postgres_db
3
  - prod_rest_api
webhooks
`list of strings` or `object`
An object whose keys are webhook slugs and values are webhook settings. As a shorthand, you can also use a list of webhook slugs. Each slug is a unique identifier that must adhere to the slug format.
permissions
object or "team_access"
Configure who has access to the task. Permissions can either be omitted to manage permissions in the UI, set to "team_access" to allow full access to everyone on the team, or defined with explicit granular permissions.
For more information, see Permissions.
Example:
yaml
Copied
1
permissions: "team_access"
If you want to define granular permissions, you can assign viewer, requester, executer, and/or admin access to groups by slug or to users by email.
yaml
Copied
1
permissions:
2
  viewers:
3
    groups:
4
      - customer_success
5
    users:
6
      - success@airplane.dev
7
  requesters:
8
    groups:
9
      - support
10
    users:
11
      - support@airplane.dev
12
  executers:
13
    groups:
14
      - devs
15
  admins:
16
    groups:
17
      - team_admins
Once permissions are defined in code for a task, they will no longer be editable in the UI until the task is deployed again without the permissions field.
permissions.viewers
object
Groups and users who can see task information, but can't request or execute tasks.
permissions.requesters
object
Groups and users who have all the permission of viewers, and can also request tasks.
permissions.executers
object
Groups and users who have all the permissions of requesters, and can also execute tasks and approve others' requests.
permissions.admins
object
Groups and users who have full access to the task, and can change task configurations and permissions.
defaultRunPermissions
enum
Default
task-viewers
Possible Values
task-viewersAnyone who can view the task can also view the run.
task-participantsCan only be viewed by those who execute, request, or approve the run.
Manage who can view new runs of this task.
outputDisplay
one of the output display objects
Configure a task's output display to change how the task run's output is displayed. By default, a task run's output is displayed as a table. You can change this to one of many display types: code, description list, file, JSON, statistic, table, or text.
For more information on output displays, also see the output display docs.
Possible Values

Code

Code is a syntax-highlighted code block.

type
REQUIRED
"code"

Indicates that the output should be displayed as a code block.

language
optional
Default
plaintext
string

Language to use for syntax highlighting.

actions
optional
list

List of actions to show above the output.

Action definition

Actions become buttons with the corresponding label, linking to an entity according to the method specified by as or opening a link from the href. as defaults to "side_peek". A maximum of 3 actions are shown.

Any of the configuration fields can take in a JST that can reference the output of the task.

Description list

Description list is a list of term and description pairs (aka key and value pairs).

type
REQUIRED
"descriptionList"

Indicates that the output should be displayed as a description list.

value
optional
string

Value of the display.

The value should be a JST that evaluates to the expected format of a description list, which is a list of objects with term anddescription fields. The JST can reference the output of the task.

actions
optional
list

List of actions to show above the output.

Action definition

Actions become buttons with the corresponding label, linking to an entity according to the method specified by as or opening a link from the href. as defaults to "side_peek". A maximum of 3 actions are shown.

Any of the configuration fields can take in a JST that can reference the output of the task.

File

File is a file preview. File requires the output to be an Airplane file.

type
REQUIRED
"file"

Indicates that the output should be displayed as a file preview.

actions
optional
list

List of actions to show above the output.

Action definition

Actions become buttons with the corresponding label, linking to an entity according to the method specified by as or opening a link from the href. as defaults to "side_peek". A maximum of 3 actions are shown.

Any of the configuration fields can take in a JST that can reference the output of the task.

Show more

REST
rest
object
Marks the task as a REST task.
Examples:
POST
yaml
Copied
1
rest:
2
  resource: internal_api
3
  method: POST
4
  path: "/users/{{params.user_id}}/update"
5
  bodyType: json
6
  body:
7
    name: "{{params.user_name}}"
GET
yaml
Copied
1
rest:
2
  resource: internal_api
3
  method: GET
4
  path: "/users/{{params.user_id}}"
5
  urlParams:
6
    page: 3
rest.resource
string
REQUIRED
The slug of a REST API resource. If you don't have an existing resource, visit the Resources settings page to add a new resource.
rest.method
enum
REQUIRED
Possible Values
GET
POST
PATCH
PUT
DELETE
The HTTP method to use.
rest.path
string
REQUIRED
The path to request. Your REST resource may specify a path prefix as part of its base URL, in which case this path is joined to it. Airplane recommends that this start with a leading slash.
rest.urlParams
object
A key value map from param name to value.
Example:
yaml
Copied
1
page: 3
2
name: "{{params.user_name}}"
rest.headers
object
A key value map from header name to value.
Example:
yaml
Copied
1
My-Custom-Header: "{{params.header_value}}"
rest.bodyType
enum
Possible Values
json
raw
form-data
x-www-form-urlencoded
The type of body that this request should send.
rest.body
object
The body of the request for a request of method POST, PUT or PATCH. This field is required when bodytype is json or raw.
Example:
yaml
Copied
1
bodyType: json
2
body:
3
  name: John
4
  email: "{{params.user_email}}"
rest.formData
object
The form data of the request for a request of method POST, PUT or PATCH. This field is required when bodytype is form-data or x-www-form-urlencoded.
Example:
yaml
Copied
1
bodyType: form-data
2
formData:
3
  name: John
4
  email: "{{params.user_email}}"
rest.retryFailures
boolean/string
If true, the request will be retried if the server returns a 500, 502, 503, or 504 error code. Requests will always be retried on 408 and 429 error codes. This field supports JS templates.
rest.configs
object
The configs attached to this task. See Config variables for more details on how to use config variables in your task.
Example:
yaml
Copied
1
configs:
2
- API_KEY
PrivacyTermsSupport