Airflow API (Stable) (1.0.

0)
Download OpenAPI specification: Download

Apache Software Foundation: [email protected] URL: https://airflow.apache.org

License: Apache 2.0

https://airflow.apache.org/docs/apache-airflow/stable/

Overview

To facilitate management, Apache Airflow supports a range of REST API endpoints across its
objects. This section provides an overview of the API design, methods, and supported use cases.

Most of the endpoints accept as input and return responses. This means that you
must usually add the following headers to your request:

Accept

Resources

The term refers to a single type of object in the Airflow metadata. An API is broken up
by its endpoint's corresponding resource. The name of a resource is typically plural and expressed
in camelCase. Example: .

Resource names are used as part of endpoint URLs, as well as in API parameters and responses.

CRUD Operations
The platform supports Create, Read, Update, and Delete operations on most resources. You can
review the standards for these operations and their standard parameters below.

Some endpoints have special behavior as exceptions.

Create

To create a resource, you typically submit an HTTP request with the resource's required
metadata in the request body. The response returns a response code upon
success with the resource's metadata, including its internal , in the response body.

Read

The HTTP request can be used to read a resource or to list a number of resources.

A resource's can be submitted in the request parameters to read a specific resource. The
response usually returns a response code upon success, with the resource's metadata in
the response body.

If a request does not include a specific resource , it is treated as a list request. The
response usually returns a response code upon success, with an object containing a list
of resources' metadata in the response body.

When reading resources, some common query parameters are usually available. e.g.:

Query
Type Description
Parameter

limit integer Maximum number of objects to fetch. Usually 25 by default

Offset after which to start returning objects. For use with limit
offset integer
query parameter.

Update

Updating a resource requires the resource , and is typically done using an HTTP
request, with the fields to modify in the request body. The response usually returns a
response code upon success, with information about the modified resource in the response body.

Delete

Deleting a resource requires the resource and is typically executing via an HTTP
request. The response usually returns a response code upon success.
Conventions

Resource names are plural and expressed in camelCase.

Names are consistent between URL parameter name and field name.

Field names are in snake_case.

Update Mask

Update mask is available as a query parameter in patch endpoints. It is used to notify the API which
fields you want to update. Using makes it easier to update objects by helping the
server know which fields to update in an object instead of updating all fields. The update request
ignores any fields that aren't specified in the field mask, leaving them with their current values.

Example:

Versioning and Endpoint Lifecycle

API versioning is not synchronized to specific releases of the Apache Airflow.

APIs are designed to be backward compatible.
Any changes to the API will first go through a deprecation phase.
Summary of Changes

Airflow version Description

v2.0 Initial release

v2.0.2 Added /plugins endpoint

v2.1 New providers endpoint

Trying the API

You can use a third party client, such as curl, HTTPie, Postman or the Insomnia rest client to test
the Apache Airflow API.

Note that you will need to pass credentials data.

For e.g., here is how to pause a DAG with curl, when basic authorization is used:

Using a graphical tool such as Postman or Insomnia, it is possible to import the API specifications
directly:

1. Download the API specification by clicking the Download button at top of this document
2. Import the JSON specification in the graphical tool of your choice.
In Postman, you can click the import button at the top
With Insomnia, you can just drag-and-drop the file on the UI

Note that with Postman, you can also generate code snippets by selecting a request and clicking on
the Code button.
Enabling CORS

Cross-origin resource sharing (CORS) is a browser security feature that restricts HTTP requests
that are initiated from scripts running in the browser.

For details on enabling/configuring CORS, see Enabling CORS.

Authentication

To be able to meet the requirements of many organizations, Airflow supports many authentication
methods, and it is even possible to add your own method.

If you want to check which auth backend is currently set, you can use
command as in the example below.

The default is to deny all requests.

For details on configuring the authentication, see API Authorization.

Errors

We follow the error response format proposed in RFC 7807 also known as Problem Details for
HTTP APIs. As with our normal API responses, your client must be prepared to gracefully handle
additional members of the response.

Unauthenticated
This indicates that the request has not been applied because it lacks valid authentication
credentials for the target resource. Please check that you have valid credentials.

PermissionDenied

This response means that the server understood the request but refuses to authorize it because it
lacks sufficient rights to the resource. It happens when you do not have the necessary permission to
execute the action you performed. You need to get the appropriate permissions in other to resolve
this error.

BadRequest

This response means that the server cannot or will not process the request due to something that is
perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or
deceptive request routing). To resolve this, please ensure that your syntax is correct.

NotFound

This client error response indicates that the server cannot find the requested resource.

MethodNotAllowed

Indicates that the request method is known by the server but is not supported by the target
resource.
NotAcceptable

The target resource does not have a current representation that would be acceptable to the user
agent, according to the proactive negotiation header fields received in the request, and the server is
unwilling to supply a default representation.

AlreadyExists

The request could not be completed due to a conflict with the current state of the target resource,
e.g. the resource it tries to create already exists.

Unknown

This means that the server encountered an unexpected condition that prevented it from fulfilling the
request.

Config
Get current configuration

Responses

GET /config

Response samples

200 401 403

application/json

Connection
List connections

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

order_by string
The name of the field to order the results by. Prefix a field name with to
reverse the sort order.

New in version 2.1.0

Responses

GET /connections

Response samples

200 401 403

application/json
+ …
 POST /connections

Request samples

Payload

application/json

Response samples

200 400 401 403

 connection_id string
required
The connection ID.

Responses

GET /connections/{connection_id}

Response samples

200 401 403 404

application/json
Responses

PATCH /connections/{connection_id}

Request samples

Payload

application/json

Response samples

200 400 401 403 404

 POST /connections/test

Request samples

Payload

application/json

Response samples

200 400 401 403 404

DAG
List DAGs

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

order_by string
The name of the field to order the results by. Prefix a field name with to
reverse the sort order.

New in version 2.1.0

tags strings
List of tags to filter results.

New in version 2.2.0

only_active boolean
Default:
Only return active DAGs.

New in version 2.1.1

Responses

GET /dags

Response samples

200 401
200 401

application/json
Response samples

200 401 403 404

application/json
 PATCH /dags/{dag_id}

Request samples

Payload

application/json

Response samples

200 401 403 404

- "schedule_interval":
 include_subdags boolean
Clear tasks in subdags and clear external tasks indicated by
ExternalTaskMarker.

include_parentdag boolean
Clear tasks in the parent dag of the subdag.

reset_dag_runs boolean
Set state of DAG runs to RUNNING.

Responses

POST /dags/{dag_id}/clearTaskInstances

Request samples

Payload

application/json
 "include_subdags": true

Response samples

200 401 403 404

 include_past boolean
If set to True, also tasks from past DAG Runs are affected.

new_state string
Enum:
Expected new state.

Responses

POST /dags/{dag_id}/updateTaskInstancesState

Request samples

Payload

application/json

Response samples
Response samples

200 401 403 404

application/json
"is_paused": true
 The name of the field to order the results by. Prefix a field name with to
reverse the sort order.

New in version 2.1.0

Responses

GET /dags/{dag_id}/tasks

Response samples

200 401 403 404

application/json
- "class_ref":
"file_token": "string"
application/json
List DAG runs
This endpoint allows specifying as the dag_id to retrieve DAG runs for all DAGs.

dag_id string
required
The DAG ID.

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

execution_date_gte string <date-time>

Returns objects greater or equal to the specified date.

This can be combined with execution_date_lte parameter to receive

only the selected period.

execution_date_lte string <date-time>

Returns objects less than or equal to the specified date.

This can be combined with execution_date_gte parameter to receive

only the selected period.

start_date_gte string <date-time>

Returns objects greater or equal the specified date.

This can be combined with start_date_lte parameter to receive only the

selected period.

start_date_lte string <date-time>

Returns objects less or equal the specified date.

This can be combined with start_date_gte parameter to receive only the

selected period.

end_date_gte string <date-time>

Returns objects greater or equal the specified date.

This can be combined with start_date_lte parameter to receive only the

 selected period.

end_date_lte string <date-time>

Returns objects less than or equal to the specified date.

This can be combined with start_date_gte parameter to receive only the

selected period.

order_by string
The name of the field to order the results by. Prefix a field name with
to reverse the sort order.

New in version 2.1.0

Responses

GET /dags/{dag_id}/dagRuns

Response samples

200 401

application/json
Trigger a new DAG run

dag_id string
required
The DAG ID.

application/json

dag_run_id string Nullable

Run ID.

The value of this field can be set only when creating the object. If you try to
modify the field of an existing object, the request fails with an
BAD_REQUEST error.

If not provided, a value will be generated based on execution_date.

If the specified dag_run_id is in use, the creation request fails with an

ALREADY_EXISTS error.

This together with DAG_ID are a unique key.

logical_date string <date-time> Nullable

The logical date (previously called execution date). This is the time or
interval covered by this DAG run, according to the DAG definition.

The value of this field can be set only when creating the object. If you try to
modify the field of an existing object, the request fails with an
BAD_REQUEST error.

This together with DAG_ID are a unique key.

New in version 2.2.0

execution_date string <date-time> Nullable

Deprecated
The execution date. This is the same as logical_date, kept for backwards
compatibility. If both this field and logical_date are provided but with
different values, the request will fail with an BAD_REQUEST error.

Changed in version 2.2.0: Field becomes nullable.

Deprecated since version 2.2.0: Use 'logical_date' instead.

state string (DagState)

Enum:
DAG State.

Changed in version 2.1.3: 'queued' is added as a possible value.

 conf object
JSON object describing additional configuration parameters.

The value of this field can be set only when creating the object. If you try to
modify the field of an existing object, the request fails with an
BAD_REQUEST error.

Responses

POST /dags/{dag_id}/dagRuns

Request samples

Payload

application/json
Response samples

200 400 401 403 404 409

application/json
 POST /dags/~/dagRuns/list

Request samples

Payload

application/json

Response samples

200 400 401 403

 PATCH /dags/{dag_id}/dagRuns/{dag_run_id}

Request samples

Payload

application/json

Response samples

200 400 401 403 404

List log entries
List log entries from event log.

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

order_by string
The name of the field to order the results by. Prefix a field name with to
reverse the sort order.

New in version 2.1.0

Responses

GET /eventLogs

Response samples

200 401 403

application/json
"event_log_id": 0
List import errors

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

order_by string
The name of the field to order the results by. Prefix a field name with to
reverse the sort order.

New in version 2.1.0

Responses

GET /importErrors

Response samples

200 401 403

application/json
+ …
"filename": "string"
Get instance status
Get the status of Airflow's metadatabase and scheduler. It includes info about metadatabase and
last heartbeat of scheduler.

Responses

GET /health

Response samples

200

application/json
Get version information

Responses

GET /version

Response samples

200

application/json

Pool
List pools

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

order_by string
The name of the field to order the results by. Prefix a field name with to
reverse the sort order.

New in version 2.1.0

Responses

GET /pools

Response samples

200 401 403

application/json
+ …
Response samples

200 400 401 403

Response samples

200 401 403 404

application/json
 PATCH /pools/{pool_name}

Request samples

Payload

application/json

Response samples

200 400 401 403 404 409

Responses

DELETE /pools/{pool_name}

Response samples

400 401 403 404

application/json
List providers
Get a list of providers.

New in version 2.1.0

Responses

GET /providers

Response samples

200 401 403

application/json

TaskInstance
List task instances
This endpoint allows specifying as the dag_id, dag_run_id to retrieve DAG runs for all DAGs
and DAG runs.

dag_id string
required
The DAG ID.

dag_run_id string
required
The DAG run ID.

execution_date_gte string <date-time>

Returns objects greater or equal to the specified date.

This can be combined with execution_date_lte parameter to receive

only the selected period.

execution_date_lte string <date-time>

Returns objects less than or equal to the specified date.

This can be combined with execution_date_gte parameter to receive

only the selected period.

start_date_gte string <date-time>

Returns objects greater or equal the specified date.

This can be combined with start_date_lte parameter to receive only the

selected period.

start_date_lte string <date-time>

Returns objects less or equal the specified date.

This can be combined with start_date_gte parameter to receive only the

selected period.

end_date_gte string <date-time>

Returns objects greater or equal the specified date.

This can be combined with start_date_lte parameter to receive only the

selected period.

end_date_lte string <date-time>

 Returns objects less than or equal to the specified date.

This can be combined with start_date_gte parameter to receive only the

selected period.

duration_gte number
Returns objects greater than or equal to the specified values.

This can be combined with duration_lte parameter to receive only the

selected period.

duration_lte number
Returns objects less than or equal to the specified values.

This can be combined with duration_gte parameter to receive only the

selected range.

state strings
The value can be repeated to retrieve multiple matching values (OR
condition).

pool strings
The value can be repeated to retrieve multiple matching values (OR
condition).

queue strings
The value can be repeated to retrieve multiple matching values (OR
condition).

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

Responses
 GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances

Response samples

200 401 403

application/json
 GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}

Response samples

200 401 403 404

application/json
 The value can be repeated to retrieve multiple matching values (OR
condition).

pool strings
The value can be repeated to retrieve multiple matching values (OR
condition).

queue strings
The value can be repeated to retrieve multiple matching values (OR
condition).

Responses

POST /dags/~/dagRuns/~/taskInstances/list

Request samples

Payload

application/json
 "end_date_gte"
"end_date_lte": "2019-08-24T14:15:22Z"

Response samples

200 401 403 404

 GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/log…

Response samples

200 400 401 403 404

application/json
List variables
The collection does not contain data. To get data, you must get a single entity.

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

order_by string
The name of the field to order the results by. Prefix a field name with to
reverse the sort order.

New in version 2.1.0

Responses

GET /variables

Response samples

200 401 403

application/json
Response samples

200 400 401 403

application/json
Request samples

Payload

application/json

Response samples

200 400 401 403 404

 DELETE /variables/{variable_key}

Response samples

400 401 403 404

application/json
List XCom entries
This endpoint allows specifying as the dag_id, dag_run_id, task_id to retrieve XCOM entries for
for all DAGs, DAG runs and task instances. XCom values won't be returned as they can be large.
Use this endpoint to get a list of XCom entries and then fetch individual entry to get value.

dag_id string
required
The DAG ID.

dag_run_id string
required
The DAG run ID.

task_id string
required
The task ID.

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

Responses

GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xco…

Response samples
200 401 403

application/json
 GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xco…

Response samples

200 401 403 404

application/json
Get a list of loaded plugins
Get a list of loaded plugins.

New in version 2.1.0

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

Responses

GET /plugins

Response samples

200 401 403 404

application/json
+ …
List roles
Get a list of roles.

New in version 2.1.0

limit integer
Default:
The numbers of items to return.

offset integer
The number of items to skip before starting to collect the result set.

order_by string
The name of the field to order the results by. Prefix a field name with to
reverse the sort order.

New in version 2.1.0

Responses

GET /roles

Response samples

200 401 403

application/json
 Payload

application/json

Response samples

200 400 401 403

 GET /roles/{role_name}

Response samples

200 401 403 404

application/json
 PATCH /roles/{role_name}

Request samples

Payload

application/json

Response samples

200 400 401 403 404

 required
The role name

Responses

DELETE /roles/{role_name}

Response samples

400 401 403 404

application/json
List permissions
Get a list of permissions.

New in version 2.1.0

limit integer
Default:
The numbers of items to return.

offset integer