Apache Airflow Asset State Store API

openapi: 3.2.0
info:
  title: Airflow Asset State Store API
  description: 'Airflow API. All endpoints located under ``/api/v2`` can be used safely, are stable and backward compatible. Endpoints located under ``/ui`` are dedicated to the UI and are subject to breaking change depending on the need of the frontend. Users should not rely on those but use the public ones instead.


    **Filtering with pattern parameters.** Many list endpoints accept ``*_pattern`` and ``*_prefix_pattern`` query parameters. Unless a parameter''s own description says otherwise, ``*_pattern`` is a case-insensitive substring match (SQL ``ILIKE ''%term%''``) where ``%`` matches any sequence and ``_`` matches any single character (e.g. ``%customer_%``) — convenient, but it cannot use B-tree indexes, so it is slow on large tables. ``*_prefix_pattern`` matches the start of the value, is case-sensitive and index-friendly (prefer it at scale); there ``%`` and ``_`` are literal and trailing non-alphanumeric characters are stripped so the range scan stays index-compatible under locale-aware collations (e.g. ``test_`` matches values starting with ``test``, and ``s3://`` matches ``s3``). In both, ``|`` means OR (e.g. ``dag1|dag2``) and ``~`` matches everything. Regular expressions are not supported by these parameters; regex-capable endpoints expose a separate parameter.'
  version: '2'
tags:
- name: Asset State Store
paths:
  /api/v2/assets/{asset_id}/state-store:
    get:
      tags:
      - Asset State Store
      summary: List Asset State Store
      description: List all state store entries for an asset.
      operationId: list_asset_state_store
      security:
      - OAuth2PasswordBearer: []
      - HTTPBearer: []
      parameters:
      - name: asset_id
        in: path
        required: true
        schema:
          type: integer
          title: Asset Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetStateStoreCollectionResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Asset State Store
      summary: Clear Asset State Store
      description: Delete all state store keys for an asset.
      operationId: clear_asset_state_store
      security:
      - OAuth2PasswordBearer: []
      - HTTPBearer: []
      parameters:
      - name: asset_id
        in: path
        required: true
        schema:
          type: integer
          title: Asset Id
      responses:
        '204':
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/assets/{asset_id}/state-store/{key}:
    get:
      tags:
      - Asset State Store
      summary: Get Asset State Store
      description: Get a single asset state store entry.
      operationId: get_asset_state_store
      security:
      - OAuth2PasswordBearer: []
      - HTTPBearer: []
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
          title: Key
      - name: asset_id
        in: path
        required: true
        schema:
          type: integer
          title: Asset Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetStateStoreResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Asset State Store
      summary: Set Asset State Store
      description: Set an asset state store value. Creates or overwrites the key.
      operationId: set_asset_state_store
      security:
      - OAuth2PasswordBearer: []
      - HTTPBearer: []
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
          title: Key
      - name: asset_id
        in: path
        required: true
        schema:
          type: integer
          title: Asset Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetStateStoreBody'
      responses:
        '204':
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Asset State Store
      summary: Delete Asset State Store
      description: Delete a single asset state store key. No-op if the key does not exist.
      operationId: delete_asset_state_store
      security:
      - OAuth2PasswordBearer: []
      - HTTPBearer: []
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
          title: Key
      - name: asset_id
        in: path
        required: true
        schema:
          type: integer
          title: Asset Id
      responses:
        '204':
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AssetStateStoreBody:
      properties:
        value:
          $ref: '#/components/schemas/JsonValue'
      additionalProperties: false
      type: object
      required:
      - value
      title: AssetStateStoreBody
      description: Request body for setting an asset state store value.
    AssetStateStoreCollectionResponse:
      properties:
        asset_state_store:
          items:
            $ref: '#/components/schemas/AssetStateStoreResponse'
          type: array
          title: Asset State Store
        total_entries:
          type: integer
          title: Total Entries
      type: object
      required:
      - asset_state_store
      - total_entries
      title: AssetStateStoreCollectionResponse
      description: All asset state store entries for an asset.
    AssetStateStoreWriterKind:
      type: string
      enum:
      - task
      - watcher
      - api
      title: AssetStateStoreWriterKind
      description: 'Identifies what kind of writer last updated an asset state store entry.


        ``TASK`` — written by a task via the execution API.

        ``WATCHER`` — written by a ``BaseEventTrigger`` (no task instance).

        ``API`` — written directly through the Core API (e.g. manual admin write).'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AssetStateStoreLastUpdatedBy:
      properties:
        kind:
          $ref: '#/components/schemas/AssetStateStoreWriterKind'
        dag_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Dag Id
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Id
        map_index:
          anyOf:
          - type: integer
          - type: 'null'
          title: Map Index
      type: object
      required:
      - kind
      title: AssetStateStoreLastUpdatedBy
      description: Writer info for the last write to an asset state store entry.
    JsonValue: {}
    HTTPExceptionResponse:
      properties:
        detail:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          title: Detail
      type: object
      required:
      - detail
      title: HTTPExceptionResponse
      description: HTTPException Model used for error response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AssetStateStoreResponse:
      properties:
        key:
          type: string
          title: Key
        value:
          $ref: '#/components/schemas/JsonValue'
        updated_at:
          type: string
          format: date-time
          title: Updated At
        last_updated_by:
          anyOf:
          - $ref: '#/components/schemas/AssetStateStoreLastUpdatedBy'
          - type: 'null'
      type: object
      required:
      - key
      - value
      - updated_at
      title: AssetStateStoreResponse
      description: A single asset state store key/value pair with metadata.
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      description: To authenticate Airflow API requests, clients must include a JWT (JSON Web Token) in the Authorization header of each request. This token is used to verify the identity of the client and ensure that they have the appropriate permissions to access the requested resources. You can use the endpoint ``POST /auth/token`` in order to generate a JWT token. Upon successful authentication, the server will issue a JWT token that contains the necessary information (such as user identity and scope) to authenticate subsequent requests. To learn more about Airflow public API authentication, please read https://airflow.apache.org/docs/apache-airflow/stable/security/api.html.
      flows:
        password:
          scopes: {}
          tokenUrl: /auth/token
    HTTPBearer:
      type: http
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Apache Airflow
  source: https://airflow.apache.org/docs/apache-airflow/stable/_static/dot-dot/src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)