The Role API from Apache Airflow — 2 operation(s) for role.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/apache-airflow:apache-airflow-role-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
contact:
email: dev@airflow.apache.org
name: Apache Software Foundation
url: https://airflow.apache.org
x-twitter: TheASF
description: '# 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 `JSON` as input and return `JSON` responses. This means that you must usually add the following headers to your request:
```
Content-type: application/json
Accept: application/json
```
## Resources
The term `resource` 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: `dagRuns`. Resource names are used as part of endpoint URLs, as well as in API parameters and responses. ## CRUD Operations
The platform supports **C**reate, **R**ead, **U**pdate, and **D**elete 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 `POST` request with the resource''s required metadata
in the request body. The response returns a `201 Created` response code upon success with the resource''s metadata, including
its internal `id`, in the response body. ### Read
The HTTP `GET` request can be used to read a resource or to list a number of resources. A resource''s `id` can be submitted in the request parameters to read a specific resource. The response usually returns a `200 OK` response code upon success, with the resource''s metadata in
the response body. If a `GET` request does not include a specific resource `id`, it is treated as a list request. The response usually returns a `200 OK` 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.:
```
v1/connections?limit=25&offset=25
```
|Query Parameter|Type|Description|
|---------------|----|-----------|
|limit|integer|Maximum number of objects to fetch. Usually 25 by default|
|offset|integer|Offset after which to start returning objects. For use with limit query parameter.|
### Update
Updating a resource requires the resource `id`, and is typically done using an HTTP `PATCH` request,
with the fields to modify in the request body. The response usually returns a `200 OK` response code upon success, with information about the modified
resource in the response body. ### Delete
Deleting a resource requires the resource `id` and is typically executing via an HTTP `DELETE` request. The response usually returns a `204 No Content` 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. ```json
{
"name": "string",
"slots": 0,
"occupied_slots": 0,
"used_slots": 0,
"queued_slots": 0,
"open_slots": 0
}
```
### 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 `update_mask` 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:
```
resource = request.get(''/resource/my-id'').json()
resource[''my_field''] = ''new-value''
request.patch(''/resource/my-id?update_mask=my_field'', data=json.dumps(resource))
```
## 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. # 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.'
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Airflow API (Stable) Role API
version: 2.5.3
x-apisguru-categories:
- messaging
x-logo:
url: https://twitter.com/TheASF/profile_image?size=original
x-origin:
- format: openapi
url: https://airflow.apache.org/docs/apache-airflow/stable/_specs/v1.yaml
version: '3.0'
x-providerName: apache.org
x-serviceName: airflow
servers:
- description: Apache Airflow Stable API.
url: /api/v1
- url: https://apache.local
security: []
tags:
- name: Role
paths:
/roles:
get:
description: 'Get a list of roles.
*New in version 2.1.0*'
operationId: get_roles
parameters:
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/PageOffset'
- $ref: '#/components/parameters/OrderBy'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RoleCollection'
description: Success.
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/PermissionDenied'
summary: Apache Airflow List Roles
tags:
- Role
x-openapi-router-controller: airflow.api_connexion.endpoints.role_and_permission_endpoint
post:
description: 'Create a new role.
*New in version 2.1.0*'
operationId: post_role
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
description: Success.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/PermissionDenied'
summary: Apache Airflow Create a Role
tags:
- Role
x-openapi-router-controller: airflow.api_connexion.endpoints.role_and_permission_endpoint
/roles/{role_name}:
parameters:
- $ref: '#/components/parameters/RoleName'
delete:
description: 'Delete a role.
*New in version 2.1.0*'
operationId: delete_role
responses:
'204':
description: Success.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/PermissionDenied'
'404':
$ref: '#/components/responses/NotFound'
summary: Apache Airflow Delete a Role
tags:
- Role
x-openapi-router-controller: airflow.api_connexion.endpoints.role_and_permission_endpoint
get:
description: 'Get a role.
*New in version 2.1.0*'
operationId: get_role
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
description: Success.
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/PermissionDenied'
'404':
$ref: '#/components/responses/NotFound'
summary: Apache Airflow Get a Role
tags:
- Role
x-openapi-router-controller: airflow.api_connexion.endpoints.role_and_permission_endpoint
patch:
description: 'Update a role.
*New in version 2.1.0*'
operationId: patch_role
parameters:
- $ref: '#/components/parameters/UpdateMask'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
description: Success.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/PermissionDenied'
'404':
$ref: '#/components/responses/NotFound'
summary: Apache Airflow Update a Role
tags:
- Role
x-openapi-router-controller: airflow.api_connexion.endpoints.role_and_permission_endpoint
components:
schemas:
RoleCollection:
allOf:
- properties:
roles:
items:
$ref: '#/components/schemas/Role'
type: array
type: object
- $ref: '#/components/schemas/CollectionInfo'
description: 'A collection of roles.
*New in version 2.1.0*
'
type: object
Role:
description: 'a role item.
*New in version 2.1.0*
'
properties:
actions:
items:
$ref: '#/components/schemas/ActionResource'
type: array
name:
description: 'The name of the role
*Changed in version 2.3.0*: A minimum character length requirement (''minLength'') is added.
'
minLength: 1
type: string
type: object
CollectionInfo:
description: Metadata about collection.
properties:
total_entries:
description: 'Count of total objects in the current result set before pagination parameters
(limit, offset) are applied.
'
type: integer
type: object
Resource:
description: 'A resource on which permissions are granted.
*New in version 2.1.0*
'
properties:
name:
description: The name of the resource
type: string
type: object
Error:
description: '[RFC7807](https://tools.ietf.org/html/rfc7807) compliant response.
'
properties:
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
instance:
description: 'A URI reference that identifies the specific occurrence of the problem. It may or may
not yield further information if dereferenced.
'
type: string
status:
description: The HTTP status code generated by the API server for this occurrence of the problem.
type: number
title:
description: A short, human-readable summary of the problem type.
type: string
type:
description: 'A URI reference [RFC3986] that identifies the problem type. This specification
encourages that, when dereferenced, it provide human-readable documentation for
the problem type.
'
type: string
required:
- type
- title
- status
type: object
ActionResource:
description: 'The Action-Resource item.
*New in version 2.1.0*
'
properties:
action:
$ref: '#/components/schemas/Action'
description: The permission action
type: object
resource:
$ref: '#/components/schemas/Resource'
description: The permission resource
type: object
type: object
Action:
description: 'An action Item.
*New in version 2.1.0*
'
properties:
name:
description: The name of the permission "action"
type: string
type: object
responses:
PermissionDenied:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Client does not have sufficient permission.
NotFound:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: A specified resource is not found.
Unauthenticated:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request not authenticated due to missing, invalid, authentication info.
BadRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Client specified an invalid argument.
parameters:
PageLimit:
description: The numbers of items to return.
in: query
name: limit
required: false
schema:
default: 100
type: integer
RoleName:
description: The role name
in: path
name: role_name
required: true
schema:
type: string
PageOffset:
description: The number of items to skip before starting to collect the result set.
in: query
name: offset
required: false
schema:
minimum: 0
type: integer
OrderBy:
description: '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*
'
in: query
name: order_by
required: false
schema:
type: string
UpdateMask:
description: 'The fields to update on the resource. If absent or empty, all modifiable fields are updated.
A comma-separated list of fully qualified names of fields.
'
explode: false
in: query
name: update_mask
schema:
items:
type: string
type: array
style: form
securitySchemes:
Basic:
scheme: basic
type: http
GoogleOpenId:
openIdConnectUrl: https://accounts.google.com/.well-known/openid-configuration
type: openIdConnect
Kerberos:
scheme: negotiate
type: http
externalDocs:
url: https://airflow.apache.org/docs/apache-airflow/stable/