Apache NiFi Provenance API

openapi: 3.2.0
info:
  contact:
    email: dev@nifi.apache.org
    url: https://nifi.apache.org
  description: REST API definition for Apache NiFi web services
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: Apache NiFi REST Provenance API
  version: 2.12.0
security:
- HTTPBearerJWT: []
- CookieSecureAuthorizationBearer: []
tags:
- name: Provenance
paths:
  /provenance:
    post:
      description: Provenance queries may be long running so this endpoint submits a request. The response will include the current state of the query. If the request is not completed the URI in the response can be used at a later time to get the updated state of the query. Once the query has completed the provenance request should be deleted by the client who originally submitted it.
      operationId: submitProvenanceRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvenanceEntity'
        description: The provenance query details.
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceEntity'
        '400':
          description: NiFi was unable to complete the request because it was invalid. The request should not be retried without modification.
        '401':
          description: Client could not be authenticated.
        '403':
          description: Client is not authorized to make this request.
        '409':
          description: The request was valid but NiFi was not in the appropriate state to process it.
      security:
      - Read - /provenance: []
      - Read - /data/{component-type}/{uuid}: []
      summary: Submits a provenance query
      tags:
      - Provenance
  /provenance/lineage:
    post:
      description: Lineage queries may be long running so this endpoint submits a request. The response will include the current state of the query. If the request is not completed the URI in the response can be used at a later time to get the updated state of the query. Once the query has completed the lineage request should be deleted by the client who originally submitted it.
      operationId: submitLineageRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineageEntity'
        description: The lineage query details.
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineageEntity'
        '400':
          description: NiFi was unable to complete the request because it was invalid. The request should not be retried without modification.
        '401':
          description: Client could not be authenticated.
        '403':
          description: Client is not authorized to make this request.
        '404':
          description: The specified resource could not be found.
        '409':
          description: The request was valid but NiFi was not in the appropriate state to process it.
      security:
      - Read - /provenance: []
      - Read - /data/{component-type}/{uuid}: []
      summary: Submits a lineage query
      tags:
      - Provenance
  /provenance/lineage/{id}:
    delete:
      operationId: deleteLineage
      parameters:
      - description: The id of the node where this query exists if clustered.
        in: query
        name: clusterNodeId
        schema:
          type: string
      - description: The id of the lineage query.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineageEntity'
        '400':
          description: NiFi was unable to complete the request because it was invalid. The request should not be retried without modification.
        '401':
          description: Client could not be authenticated.
        '403':
          description: Client is not authorized to make this request.
        '404':
          description: The specified resource could not be found.
        '409':
          description: The request was valid but NiFi was not in the appropriate state to process it.
      security:
      - Read - /provenance: []
      summary: Deletes a lineage query
      tags:
      - Provenance
    get:
      operationId: getLineage
      parameters:
      - description: The id of the node where this query exists if clustered.
        in: query
        name: clusterNodeId
        schema:
          type: string
      - description: The id of the lineage query.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineageEntity'
        '400':
          description: NiFi was unable to complete the request because it was invalid. The request should not be retried without modification.
        '401':
          description: Client could not be authenticated.
        '403':
          description: Client is not authorized to make this request.
        '404':
          description: The specified resource could not be found.
        '409':
          description: The request was valid but NiFi was not in the appropriate state to process it.
      security:
      - Read - /provenance: []
      - Read - /data/{component-type}/{uuid}: []
      summary: Gets a lineage query
      tags:
      - Provenance
  /provenance/search-options:
    get:
      operationId: getSearchOptions
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceOptionsEntity'
        '400':
          description: NiFi was unable to complete the request because it was invalid. The request should not be retried without modification.
        '401':
          description: Client could not be authenticated.
        '403':
          description: Client is not authorized to make this request.
        '409':
          description: The request was valid but NiFi was not in the appropriate state to process it.
      security:
      - Read - /provenance: []
      summary: Gets the searchable attributes for provenance events
      tags:
      - Provenance
  /provenance/{id}:
    delete:
      operationId: deleteProvenance
      parameters:
      - description: The id of the node where this query exists if clustered.
        in: query
        name: clusterNodeId
        schema:
          type: string
      - description: The id of the provenance query.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceEntity'
        '400':
          description: NiFi was unable to complete the request because it was invalid. The request should not be retried without modification.
        '401':
          description: Client could not be authenticated.
        '403':
          description: Client is not authorized to make this request.
        '404':
          description: The specified resource could not be found.
        '409':
          description: The request was valid but NiFi was not in the appropriate state to process it.
      security:
      - Read - /provenance: []
      summary: Deletes a provenance query
      tags:
      - Provenance
    get:
      operationId: getProvenance
      parameters:
      - description: The id of the node where this query exists if clustered.
        in: query
        name: clusterNodeId
        schema:
          type: string
      - description: Whether or not to summarize provenance events returned. This property is false by default.
        in: query
        name: summarize
        schema:
          type: boolean
          default: false
      - description: Whether or not incremental results are returned. If false, provenance events are only returned once the query completes. This property is true by default.
        in: query
        name: incrementalResults
        schema:
          type: boolean
          default: true
      - description: The id of the provenance query.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvenanceEntity'
        '400':
          description: NiFi was unable to complete the request because it was invalid. The request should not be retried without modification.
        '401':
          description: Client could not be authenticated.
        '403':
          description: Client is not authorized to make this request.
        '404':
          description: The specified resource could not be found.
        '409':
          description: The request was valid but NiFi was not in the appropriate state to process it.
      security:
      - Read - /provenance: []
      - Read - /data/{component-type}/{uuid}: []
      summary: Gets a provenance query
      tags:
      - Provenance
components:
  schemas:
    ProvenanceDTO:
      type: object
      properties:
        expiration:
          type: string
          description: The timestamp when the query will expire.
        finished:
          type: boolean
          description: Whether the query has finished.
        id:
          type: string
          description: The id of the provenance query.
        percentCompleted:
          type: integer
          format: int32
          description: The current percent complete.
        request:
          $ref: '#/components/schemas/ProvenanceRequestDTO'
        results:
          $ref: '#/components/schemas/ProvenanceResultsDTO'
        submissionTime:
          type: string
          description: The timestamp when the query was submitted.
        uri:
          type: string
          description: The URI for this query. Used for obtaining/deleting the request at a later time
    LineageDTO:
      type: object
      properties:
        expiration:
          type: string
          description: When the lineage query will expire.
        finished:
          type: boolean
          description: Whether the lineage query has finished.
        id:
          type: string
          description: The id of this lineage query.
        percentCompleted:
          type: integer
          format: int32
          description: The percent complete for the lineage query.
        request:
          $ref: '#/components/schemas/LineageRequestDTO'
        results:
          $ref: '#/components/schemas/LineageResultsDTO'
        submissionTime:
          type: string
          description: When the lineage query was submitted.
        uri:
          type: string
          description: The URI for this lineage query for later retrieval and deletion.
    ProvenanceOptionsEntity:
      type: object
      properties:
        provenanceOptions:
          $ref: '#/components/schemas/ProvenanceOptionsDTO'
      xml:
        name: provenanceOptionsEntity
    ProvenanceEventDTO:
      type: object
      description: The provenance events that matched the search criteria.
      properties:
        alternateIdentifierUri:
          type: string
          description: The alternate identifier uri for the fileflow for the event.
        attributes:
          type: array
          description: The attributes of the flowfile for the event.
          items:
            $ref: '#/components/schemas/AttributeDTO'
        childUuids:
          type: array
          description: The child uuids for the event.
          items:
            type: string
            description: The child uuids for the event.
        clusterNodeAddress:
          type: string
          description: The label for the node where the event originated.
        clusterNodeId:
          type: string
          description: The identifier for the node where the event originated.
        componentId:
          type: string
          description: The id of the component that generated the event.
        componentName:
          type: string
          description: The name of the component that generated the event.
        componentType:
          type: string
          description: The type of the component that generated the event.
        connectorId:
          type: string
          description: The id of the connector that manages the component that generated the event. If the component is not managed by a connector, this will not be set.
        contentEqual:
          type: boolean
          description: Whether the input and output content claim is the same.
        details:
          type: string
          description: The event details.
        eventDuration:
          type: integer
          format: int64
          description: The event duration in milliseconds.
        eventId:
          type: integer
          format: int64
          description: The event id. This is a one up number that's unique per node.
        eventTime:
          type: string
          description: The timestamp of the event.
        eventTimestamp:
          type: string
          description: Event Timestamp formatted using ISO8601
        eventType:
          type: string
          description: The type of the event.
        fileSize:
          type: string
          description: The size of the flowfile for the event.
        fileSizeBytes:
          type: integer
          format: int64
          description: The size of the flowfile in bytes for the event.
        flowFileUuid:
          type: string
          description: The uuid of the flowfile for the event.
        groupId:
          type: string
          description: The id of the group that the component resides in. If the component is no longer in the flow, the group id will not be set.
        id:
          type: string
          description: The event uuid.
        inputContentAvailable:
          type: boolean
          description: Whether the input content is still available.
        inputContentClaimContainer:
          type: string
          description: The container in which the input content claim lives.
        inputContentClaimFileSize:
          type: string
          description: The file size of the input content claim formatted.
        inputContentClaimFileSizeBytes:
          type: integer
          format: int64
          description: The file size of the intput content claim in bytes.
        inputContentClaimIdentifier:
          type: string
          description: The identifier of the input content claim.
        inputContentClaimOffset:
          type: integer
          format: int64
          description: The offset into the input content claim where the FlowFiles content begins.
        inputContentClaimSection:
          type: string
          description: The section in which the input content claim lives.
        lineageDuration:
          type: integer
          format: int64
          description: The duration since the lineage began, in milliseconds.
        outputContentAvailable:
          type: boolean
          description: Whether the output content is still available.
        outputContentClaimContainer:
          type: string
          description: The container in which the output content claim lives.
        outputContentClaimFileSize:
          type: string
          description: The file size of the output content claim formatted.
        outputContentClaimFileSizeBytes:
          type: integer
          format: int64
          description: The file size of the output content claim in bytes.
        outputContentClaimIdentifier:
          type: string
          description: The identifier of the output content claim.
        outputContentClaimOffset:
          type: integer
          format: int64
          description: The offset into the output content claim where the FlowFiles content begins.
        outputContentClaimSection:
          type: string
          description: The section in which the output content claim lives.
        parentUuids:
          type: array
          description: The parent uuids for the event.
          items:
            type: string
            description: The parent uuids for the event.
        relationship:
          type: string
          description: The relationship to which the flowfile was routed if the event is of type ROUTE.
        replayAvailable:
          type: boolean
          description: Whether or not replay is available.
        replayExplanation:
          type: string
          description: Explanation as to why replay is unavailable.
        sourceConnectionIdentifier:
          type: string
          description: The identifier of the queue/connection from which the flowfile was pulled to generate this event. May be null if the queue/connection is unknown or the flowfile was generated from this event.
        sourceSystemFlowFileId:
          type: string
          description: The source system flowfile id.
        transitUri:
          type: string
          description: The source/destination system uri if the event was a RECEIVE/SEND.
    LineageResultsDTO:
      type: object
      description: The results of the lineage query.
      properties:
        errors:
          type: array
          description: Any errors that occurred while generating the lineage.
          items:
            type: string
            description: Any errors that occurred while generating the lineage.
          uniqueItems: true
        links:
          type: array
          description: The links between the nodes in the lineage.
          items:
            $ref: '#/components/schemas/ProvenanceLinkDTO'
        nodes:
          type: array
          description: The nodes in the lineage.
          items:
            $ref: '#/components/schemas/ProvenanceNodeDTO'
    ProvenanceResultsDTO:
      type: object
      description: The provenance results.
      properties:
        errors:
          type: array
          description: Any errors that occurred while performing the provenance request.
          items:
            type: string
            description: Any errors that occurred while performing the provenance request.
          uniqueItems: true
        generated:
          type: string
          description: Then the search was performed.
        oldestEvent:
          type: string
          description: The oldest event available in the provenance repository.
        provenanceEvents:
          type: array
          description: The provenance events that matched the search criteria.
          items:
            $ref: '#/components/schemas/ProvenanceEventDTO'
        timeOffset:
          type: integer
          format: int32
          description: The time offset of the server that's used for event time.
        total:
          type: string
          description: The total number of results formatted.
        totalCount:
          type: integer
          format: int64
          description: The total number of results.
    ProvenanceEntity:
      type: object
      properties:
        provenance:
          $ref: '#/components/schemas/ProvenanceDTO'
      xml:
        name: provenanceEntity
    ProvenanceSearchValueDTO:
      type: object
      description: The search terms used to perform the search.
      properties:
        inverse:
          type: boolean
          description: Query for all except for search value.
        value:
          type: string
          description: The search value.
    AttributeDTO:
      type: object
      description: The attributes of the flowfile for the event.
      properties:
        name:
          type: string
          description: The attribute name.
        previousValue:
          type: string
          description: The value of the attribute before the event took place.
        value:
          type: string
          description: The attribute value.
    ProvenanceLinkDTO:
      type: object
      description: The links between the nodes in the lineage.
      properties:
        flowFileUuid:
          type: string
          description: The flowfile uuid that traversed the link.
        millis:
          type: integer
          format: int64
          description: The timestamp of this link in milliseconds.
        sourceId:
          type: string
          description: The source node id of the link.
        targetId:
          type: string
          description: The target node id of the link.
        timestamp:
          type: string
          description: The timestamp of the link (based on the destination).
    ProvenanceRequestDTO:
      type: object
      description: The provenance request.
      properties:
        clusterNodeId:
          type: string
          description: The id of the node in the cluster where this provenance originated.
        endDate:
          type: string
          description: The latest event time to include in the query.
        incrementalResults:
          type: boolean
          description: Whether or not incremental results are returned. If false, provenance events are only returned once the query completes. This property is true by default.
        maxResults:
          type: integer
          format: int32
          description: The maximum number of results to include.
        maximumFileSize:
          type: string
          description: The maximum file size to include in the query.
        minimumFileSize:
          type: string
          description: The minimum file size to include in the query.
        searchTerms:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ProvenanceSearchValueDTO'
          description: The search terms used to perform the search.
        startDate:
          type: string
          description: The earliest event time to include in the query.
        summarize:
          type: boolean
          description: Whether or not to summarize provenance events returned. This property is false by default.
    LineageRequestDTO:
      type: object
      description: The initial lineage result.
      properties:
        clusterNodeId:
          type: string
          description: The id of the node where this lineage originated if clustered.
        eventId:
          type: integer
          format: int64
          description: 'The event id that was used to generate this lineage, if applicable.

            The event id is allowed for any type of lineageRequestType.

            If the lineageRequestType is FLOWFILE and the flowfile uuid is also included in the request, the event id will be ignored.

            '
        lineageRequestType:
          type: string
          description: The type of lineage request. PARENTS will return the lineage for the FlowFiles that are parents of the specified event. CHILDREN will return the lineage for the FlowFiles that are children of the specified event. FLOWFILE will return the lineage for the specified flowfile.
          enum:
          - PARENTS
          - CHILDREN
          - FLOWFILE
        uuid:
          type: string
          description: The flowfile uuid that was used to generate the lineage. The flowfile uuid is only allowed when the lineageRequestType is FLOWFILE and will take precedence over event id.
    ProvenanceOptionsDTO:
      type: object
      properties:
        searchableFields:
          type: array
          description: The available searchable field for the NiFi.
          items:
            $ref: '#/components/schemas/ProvenanceSearchableFieldDTO'
    ProvenanceSearchableFieldDTO:
      type: object
      description: The available searchable field for the NiFi.
      properties:
        field:
          type: string
          description: The searchable field.
        id:
          type: string
          description: The id of the searchable field.
        label:
          type: string
          description: The label for the searchable field.
        type:
          type: string
          description: The type of the searchable field.
    ProvenanceNodeDTO:
      type: object
      description: The nodes in the lineage.
      properties:
        childUuids:
          type: array
          description: The uuid of the children FlowFiles of the provenance event.
          items:
            type: string
            description: The uuid of the children FlowFiles of the provenance event.
        clusterNodeIdentifier:
          type: string
          description: The identifier of the node that this event/flowfile originated from.
        componentType:
          type: string
          description: If the type is EVENT, this is the type of the component that generated the event.
        eventType:
          type: string
          description: If the type is EVENT, this is the type of event.
        flowFileUuid:
          type: string
          description: The uuid of the flowfile associated with the provenance event.
        id:
          type: string
          description: The id of the node.
        millis:
          type: integer
          format: int64
          description: The timestamp of the node in milliseconds.
        parentUuids:
          type: array
          description: The uuid of the parent FlowFiles of the provenance event.
          items:
            type: string
            description: The uuid of the parent FlowFiles of the provenance event.
        timestamp:
          type: string
          description: The timestamp of the node formatted.
        type:
          type: string
          description: The type of the node.
          enum:
          - FLOWFILE
          - EVENT
    LineageEntity:
      type: object
      properties:
        lineage:
          $ref: '#/components/schemas/LineageDTO'
      xml:
        name: lineageEntity
  securitySchemes:
    CookieSecureAuthorizationBearer:
      description: JSON Web Token authentication with session cookie
      in: cookie
      name: __Secure-Authorization-Bearer
      type: apiKey
    HTTPBearerJWT:
      bearerFormat: JWT
      description: HTTP Bearer authentication with JSON Web Token
      scheme: Bearer
      type: http
x-provenance:
  method: harvested
  publisher: Apache NiFi
  source: https://nifi.apache.org/nifi-docs/swagger.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)