Clarifeye Pipeline Runs API

openapi: 3.2.0
info:
  title: Clarifeye Platform Agent Settings Pipeline Runs API
  description: 'REST API for the Clarifeye Platform - Document intelligence and AI-powered analysis.


    ## Authentication

    All endpoints require authentication. Include the Authorization header in every request using either format:

    - `Authorization: Token <token_key>`

    - `Authorization: Bearer <token_key>`


    ## Impersonation


    Certain endpoints support user impersonation for creating or listing data on behalf of other users.

    This is useful for integrating external systems that need to attribute actions to specific users.


    **Header:** `X-Impersonate-Email`


    **Required Permission:** `CAN_IMPERSONATE_OTHER_USERS` (contact Clarifeye to enable this permission)


    **Behavior:**

    - If the header is provided and the impersonator has the required permission, the action is performed as the target user

    - If the target user is not found, the request proceeds as the original authenticated user

    - If the target user does not have access to the project, the request proceeds as the original authenticated user

    - If the impersonator lacks the `CAN_IMPERSONATE_OTHER_USERS` permission, the header is ignored

    '
  version: 1.0.0
  contact:
    name: Clarifeye Support
servers:
- url: https://eu.app.clarifeye.ai/api/v1
  description: EU
- url: https://us.app.clarifeye.ai/api/v1
  description: US
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: Pipeline Runs
  description: Inspect pipeline runs queued by extraction flows or other pipeline triggers — list runs and fetch the details/status of a single run
paths:
  /projects/{project_id}/pipeline-runs/:
    get:
      tags:
      - Pipeline Runs
      summary: List pipeline runs
      description: 'List all pipeline runs in the project, ordered by creation date (most

        recent first). Use this to discover the `id` of a run returned by an

        extraction flow `run-sync` / `publish` call, or to monitor recent

        activity.


        The list response uses a lightweight serializer that omits the very

        large `chunk_ids` / `document_ids` arrays and truncates `raw_logs` to

        the most recent entries. Fetch a single run via the detail endpoint

        to get the full payload.

        '
      operationId: listPipelineRuns
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: status
        in: query
        description: Filter pipeline runs by status (e.g. `pending`, `running`, `completed`, `failed`).
        schema:
          $ref: '#/components/schemas/PipelineRunStatus'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/PipelineRunListItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/pipeline-runs/{pipeline_run_id}/:
    get:
      tags:
      - Pipeline Runs
      summary: Get pipeline run details and status
      description: 'Retrieve the full details of a single pipeline run, including its

        current `status`, the list of executed steps with their per-step

        status, and the aggregated `raw_logs` produced during execution.


        Poll this endpoint to track the progress of a run started via an

        extraction flow `run-sync` or `publish` call. A run is in a terminal

        state when `status` is one of `completed`, `completed_with_warnings`,

        `failed`, or `aborted`.

        '
      operationId: getPipelineRun
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/PipelineRunId'
      responses:
        '200':
          description: Pipeline run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineRun'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/pipeline-runs/{pipeline_run_id}/abort/:
    post:
      tags:
      - Pipeline Runs
      summary: Abort a pipeline run
      description: 'Cancel a pipeline run that is `pending` or `running`. The run and any

        of its non-terminal steps transition to `aborted`.


        Aborting an already-terminal run (`completed`, `completed_with_warnings`,

        `failed`, or `aborted`) is a no-op.

        '
      operationId: abortPipelineRun
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/PipelineRunId'
      responses:
        '200':
          description: Abort accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: aborted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PipelineRunStep:
      type: object
      description: One step within a pipeline run's DAG.
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        step:
          type: string
          description: The pipeline step type (parsing, chunking, tag-extraction, etc.).
        name:
          type:
          - string
          - 'null'
          description: Human-readable name of the step within the DAG.
        status:
          $ref: '#/components/schemas/PipelineRunStatus'
        inputs:
          type: object
          description: Map of input table name → resolved table version UUID.
          additionalProperties:
            type:
            - string
            - 'null'
            format: uuid
        outputs:
          type: object
          description: Map of output table name → resolved table version UUID.
          additionalProperties:
            type:
            - string
            - 'null'
            format: uuid
        warnings:
          description: Warnings emitted by the step, when any.
        depends_on:
          type: array
          items:
            type: string
          description: Names of the steps this step depends on.
        params:
          type: object
          description: Step-specific parameters used at execution time.
        tag_extractor_id:
          type:
          - string
          - 'null'
          format: uuid
        object_extractor_id:
          type:
          - string
          - 'null'
          format: uuid
        chunks_extractor_id:
          type:
          - string
          - 'null'
          format: uuid
    PipelineRunStatus:
      type: string
      description: 'Lifecycle status of a pipeline run or step:

        - `pending` — queued, not yet started

        - `running` — currently executing

        - `completed` — finished successfully

        - `completed_with_warnings` — finished, but some steps emitted warnings

        - `failed` — terminated with an error

        - `aborted` — cancelled via the `abort` action

        '
      enum:
      - pending
      - running
      - completed
      - completed_with_warnings
      - failed
      - aborted
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
    PipelineRun:
      type: object
      description: Full pipeline run payload returned by the detail endpoint.
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/PipelineRunStatus'
        project:
          type: string
          format: uuid
        pipeline_name:
          type: string
        mode:
          type: string
          description: Run mode (e.g. `recreate-all`, `recreate-single`, `upsert-single`, `upsert-all`).
        celery_task_id:
          type: string
        user:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the user who triggered the run.
        tables:
          type:
          - object
          - 'null'
          description: Map of table name → table version UUID for the run.
        steps:
          type: array
          items:
            $ref: '#/components/schemas/PipelineRunStep'
        document_ids:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          description: UUIDs of documents this run targets.
        chunk_ids:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          description: UUIDs of chunks this run targets.
        raw_logs:
          type: string
          description: Concatenated logs produced during execution.
    PipelineRunListItem:
      type: object
      description: 'Lightweight pipeline run representation returned by the list endpoint.

        Excludes the large `chunk_ids` / `document_ids` arrays and truncates

        `raw_logs` to the most recent entries. Use the detail endpoint to get

        the full payload.

        '
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/PipelineRunStatus'
        project:
          type: string
          format: uuid
        pipeline_name:
          type: string
        mode:
          type: string
          description: Run mode (e.g. `recreate-all`, `recreate-single`, `upsert-single`, `upsert-all`).
        celery_task_id:
          type: string
        user:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the user who triggered the run.
        tables:
          type:
          - object
          - 'null'
          description: Map of table name → table version UUID for the run.
        steps:
          type: array
          items:
            $ref: '#/components/schemas/PipelineRunStep'
        document_count:
          type: integer
          description: Number of documents this run targets.
        chunk_count:
          type: integer
          description: Number of chunks this run targets.
        raw_logs:
          type: string
          description: Truncated tail of run logs (most recent entries only).
    PaginatedResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of results
        next:
          type:
          - string
          - 'null'
          format: uri
          description: URL to next page of results
        previous:
          type:
          - string
          - 'null'
          format: uri
          description: URL to previous page of results
        results:
          type: array
          items: {}
  responses:
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: You do not have permission to perform this action.
    Unauthorized:
      description: Unauthorized - missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Authentication credentials were not provided.
    NotFound:
      description: Not found - resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found.
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: UUID of the project
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      description: Maximum number of results per page
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
    PipelineRunId:
      name: pipeline_run_id
      in: path
      required: true
      description: UUID of the pipeline run
      schema:
        type: string
        format: uuid
    Offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
        minimum: 0
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use Authorization: Bearer <token>'
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Authorization: Token <token>'