Clarifeye Extraction Flows API

openapi: 3.2.0
info:
  title: Clarifeye Platform API — Full API Documentation Extraction…
  description: 'Complete REST API reference for the Clarifeye Platform.


    Documents every endpoint exposed by the platform — the public surface plus

    the advanced surface: pipeline customization (extraction flows, pipeline

    runs, warehouse tables, document tag/metadata configuration), the pre-MCP

    AI surface (agent settings, playground conversations, conversation-scoped

    feedback views, notifications), and the impersonation header. New AI

    integrations should consume knowledge via MCP rather than the

    conversation/agent-settings endpoints documented here.


    ## Authentication

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

    - `Authorization: Token `

    - `Authorization: Bearer `


    ## Service accounts and API keys

    Integrations authenticate with an **API key** of a **service account**:

    - `Authorization: Bearer ` (keys start with `cfk_`)


    A service account is an ordinary member (role `member`) of one organization that cannot log

    in. Organization admins create it and mint its keys on the organization''s *Service

    accounts* page (`/organizations/{id}/service-accounts/`, `/organization-api-keys/`), and

    give it access to knowledge stores with ordinary store permissions. A key is valid on every

    endpoint and acts as its service account: it reaches exactly the stores, with exactly the

    rights, the account was given. An account can hold several keys (each with its own name,

    optional expiry and revocation), so a key can be rotated without changing identity.


    A refused key answers **403** with one of: `Invalid API key.`, `API key revoked.`,

    `API key expired.`, `API key disabled.` (the service account is disabled).


    Any valid key may also call `POST /organizations/{id}/provision-user/` and

    `POST /organizations/{id}/deprovision-user/` for its own organization (the `{id}` in the

    path must be the key''s organization). The email domains these may pre-create accounts for

    are configured by Clarifeye on the organization (`allowed_provisioning_domains`).


    ## 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` (for a person, contact Clarifeye to enable it; org admins grant it to a service account on the organization''s Service accounts page)


    **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


    **With an API key** the request fails instead (**403**) whenever impersonation cannot

    happen: missing permission, unknown target, target without access to the store, target that

    is itself a service account, or an endpoint outside a store. A key never silently acts as

    its own service account when impersonation was asked for.'
  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: Extraction Flows
  description: Manage extraction flows (auto-sync DAGs) — list, run, inspect statistics, update, and publish
paths:
  /projects/{project_id}/extraction-flows/:
    get:
      tags:
      - Extraction Flows
      summary: List extraction flows
      description: List all extraction flows for the project, ordered by most recently updated.
      operationId: listExtractionFlows
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExtractionFlow'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/extraction-flows/{flow_id}/:
    patch:
      tags:
      - Extraction Flows
      summary: Update an extraction flow
      description: 'Partially update an extraction flow. Common uses are switching the

        **publish mode** and editing the **DAG** (adding, modifying or removing

        nodes).


        **Publish modes:**

        - `auto_publish` — Each successful flow run automatically publishes the

        extracted data. No separate publish step

        is required.

        - `manual_publish` — Flow runs only compute and persist extracted data in

        the warehouse. Publishing to downstream indexes must be triggered

        explicitly via the `publish` action. Use this when you want to review

        the results of a run before exposing them to search / agents.


        **Editing the DAG:** Send the full updated `dag` object — the backend

        replaces the stored DAG on every PATCH. There is no node-level patch

        endpoint. When removing a node, also strip its name from any downstream

        `depends_on` arrays. `inputs` and `outputs` may be sent empty; the

        backend resolves them automatically.'
      operationId: updateExtractionFlow
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/FlowId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Human-readable name of the flow
                publish_mode:
                  type: string
                  enum:
                  - auto_publish
                  - manual_publish
                  description: 'Controls whether extracted data is pushed to downstream indexes

                    automatically after each run (`auto_publish`) or only on an

                    explicit `publish` call (`manual_publish`).

                    '
                dag:
                  $ref: '#/components/schemas/ExtractionFlowDag'
            examples:
              togglePublishMode:
                summary: Switch publish mode only
                value:
                  publish_mode: manual_publish
              addNode:
                summary: Add a TagExtractor node to the DAG
                description: 'The frontend sends the entire updated `dag` (full replacement) on

                  every node edit. Here a `TagExtractor` node is appended downstream

                  of `chunks_node`. `inputs` / `outputs` are left empty — the backend

                  fills them via `resolve_dag_tables()`.

                  '
                value:
                  dag:
                    name: extraction_flow
                    nodes:
                    - node_name: parsing_node
                      extractor: ParsingExtractor
                      acceptable_versions:
                      - v1
                      processing_version: v1
                      inputs: {}
                      outputs:
                        parsed_documents: parsed_documents_v1
                    - node_name: chunks_node
                      extractor: ChunksExtractor
                      acceptable_versions:
                      - v1
                      processing_version: v1
                      inputs:
                        parsed_documents: parsed_documents_v1
                      outputs:
                        chunks: chunks_v1
                      depends_on:
                      - parsing_node
                    - node_name: tag_extractor
                      extractor: TagExtractor
                      acceptable_versions:
                      - v2
                      processing_version: v2
                      inputs: {}
                      outputs: {}
                      depends_on:
                      - chunks_node
              editNode:
                summary: Bump a node's processing_version
                description: 'Even when only one node changes, send the full DAG. Here

                  `tag_extractor` is upgraded from `v2` to `v3` (and `v3` is added

                  to `acceptable_versions`).

                  '
                value:
                  dag:
                    name: extraction_flow
                    nodes:
                    - node_name: parsing_node
                      extractor: ParsingExtractor
                      acceptable_versions:
                      - v1
                      processing_version: v1
                      inputs: {}
                      outputs:
                        parsed_documents: parsed_documents_v1
                    - node_name: chunks_node
                      extractor: ChunksExtractor
                      acceptable_versions:
                      - v1
                      processing_version: v1
                      inputs:
                        parsed_documents: parsed_documents_v1
                      outputs:
                        chunks: chunks_v1
                      depends_on:
                      - parsing_node
                    - node_name: tag_extractor
                      extractor: TagExtractor
                      acceptable_versions:
                      - v2
                      - v3
                      processing_version: v3
                      inputs: {}
                      outputs: {}
                      depends_on:
                      - chunks_node
              removeNode:
                summary: Remove a node from the DAG
                description: 'Send the DAG without the removed node. The backend replaces the

                  stored DAG verbatim, so callers must also strip the removed

                  node''s name from any downstream `depends_on` arrays before

                  sending.

                  '
                value:
                  dag:
                    name: extraction_flow
                    nodes:
                    - node_name: parsing_node
                      extractor: ParsingExtractor
                      acceptable_versions:
                      - v1
                      processing_version: v1
                      inputs: {}
                      outputs:
                        parsed_documents: parsed_documents_v1
                    - node_name: chunks_node
                      extractor: ChunksExtractor
                      acceptable_versions:
                      - v1
                      processing_version: v1
                      inputs:
                        parsed_documents: parsed_documents_v1
                      outputs:
                        chunks: chunks_v1
                      depends_on:
                      - parsing_node
      responses:
        '200':
          description: Flow updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionFlow'
        '400':
          description: Invalid payload (e.g. malformed DAG or unknown publish_mode)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/extraction-flows/{flow_id}/run-sync/:
    post:
      tags:
      - Extraction Flows
      summary: Run an extraction flow
      description: 'Queue a pipeline run that executes the flow''s DAG across the given

        documents (or all project documents if `document_ids` is omitted).


        Returns the `pipeline_run_id` you can poll to track progress.'
      operationId: runExtractionFlow
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/FlowId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                document_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: 'Optional list of document UUIDs to run the flow on. If omitted

                    or empty, the flow runs against all documents in the project.

                    '
            example:
              document_ids:
              - 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Sync started
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Sync started.
                  pipeline_run_id:
                    type: string
                    format: uuid
        '400':
          description: Flow DAG is empty, inconsistent, or document_ids are invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/extraction-flows/{flow_id}/node-stats/:
    post:
      tags:
      - Extraction Flows
      summary: Get extraction flow statistics
      description: 'Dry-run cache simulation of the flow — returns, per DAG node, how many

        inputs would be reused from cache vs. recomputed, without actually

        executing any extraction. Useful to preview the cost/impact of a run.'
      operationId: getExtractionFlowStatistics
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/FlowId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                document_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: 'Optional list of document UUIDs to scope the simulation to.

                    When omitted, statistics are computed over all documents in

                    the project.

                    '
            example:
              document_ids:
              - 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Per-node statistics
          content:
            application/json:
              schema:
                type: object
                description: 'Map of DAG node names to their cache/recompute statistics.

                  '
                additionalProperties:
                  type: object
        '400':
          description: Flow DAG is empty, inconsistent, or document_ids are invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/extraction-flows/{flow_id}/publish/:
    post:
      tags:
      - Extraction Flows
      summary: Publish an extraction flow
      description: 'Queue a pipeline run that publishes previously-extracted data to the

        downstream indexes without re-running extraction.


        > **Only valid for flows whose `publish_mode` is `manual_publish`.**

        > For `auto_publish` flows, publishing happens automatically at the end

        > of each `run-sync`, so calling this endpoint is unnecessary.'
      operationId: publishExtractionFlow
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/FlowId'
      responses:
        '200':
          description: Publish started
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Publish started.
                  pipeline_run_id:
                    type: string
                    format: uuid
        '400':
          description: Flow DAG is empty or inconsistent
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: UUID of the project
      schema:
        type: string
        format: uuid
    FlowId:
      name: flow_id
      in: path
      required: true
      description: UUID of the extraction flow
      schema:
        type: string
        format: uuid
  schemas:
    ExtractionFlowPublishMode:
      type: string
      enum:
      - auto_publish
      - manual_publish
      description: '- `auto_publish` — runs automatically push extracted data to downstream indexes.

        - `manual_publish` — publishing is triggered explicitly via the `publish` action.

        '
    ExtractionFlowDagNode:
      type: object
      description: 'A single node in an extraction flow''s DAG. Each node binds an extractor

        class + version to a position in the pipeline. Node names must be unique

        within a DAG; the editor auto-numbers collisions (e.g. `tag_extractor`,

        `tag_extractor_1`).

        '
      required:
      - node_name
      - extractor
      - acceptable_versions
      - processing_version
      - inputs
      - outputs
      properties:
        node_name:
          type: string
          description: Unique identifier of the node within its DAG.
          example: tag_extractor
        extractor:
          type: string
          description: 'Extractor class. Known values include `ParsingExtractor`,

            `BlocksExtractor`, `ChunksExtractor`, `TagExtractor`,

            `ObjectExtractor`, `DocumentTagExtractor`, `DocumentFilterExtractor`,

            `ChunkTagFilterExtractor`.

            '
          example: TagExtractor
        extractor_id:
          type: string
          format: uuid
          description: ID of the extractor instance configured in the project. Optional on input.
        acceptable_versions:
          type: array
          items:
            type: string
          description: Extractor version IDs accepted for cache reuse.
        processing_version:
          type: string
          description: Extractor version used for new computations. Must appear in `acceptable_versions`.
        inputs:
          type: object
          additionalProperties:
            type: string
          description: 'Map of input slot name to upstream table reference. Send as `{}` on

            create / edit — the backend fills it via `resolve_dag_tables()`.

            '
        outputs:
          type: object
          additionalProperties:
            type: string
          description: 'Map of output slot name to produced table reference. Send as `{}` on

            create / edit — the backend fills it.

            '
        depends_on:
          type: array
          items:
            type: string
          description: 'Names of upstream nodes this node depends on. Each entry must match

            another node''s `node_name` in the same DAG.

            '
        filter_items_type:
          type: string
          description: Only set for `DocumentFilterExtractor` / `ChunkTagFilterExtractor` nodes.
        params:
          type: object
          description: Free-form extractor parameters. Optional; usually populated by the backend from the extractor version.
    ExtractionFlowDag:
      type: object
      description: 'DAG describing the extractor pipeline. PATCH replaces the stored DAG

        verbatim — there is no node-level patch endpoint.

        '
      required:
      - name
      - nodes
      properties:
        name:
          type: string
          example: extraction_flow
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/ExtractionFlowDagNode'
    ExtractionFlow:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        publish_mode:
          $ref: '#/components/schemas/ExtractionFlowPublishMode'
        dag:
          $ref: '#/components/schemas/ExtractionFlowDag'
        tpuf_namespaces:
          type: object
          description: Per-namespace-type TurboPuffer namespace mapping populated on publish.
        last_pushed_to_tpuf:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
  responses:
    NotFound:
      description: Not found - resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found.
    Unauthorized:
      description: Unauthorized - missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Authentication credentials were not provided.
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: You do not have permission to perform this action.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use `Authorization: Bearer <token>`. The token is either a user token / OAuth access

        token, or a service-account API key (`cfk_...`). A key is valid on every endpoint and

        acts as its service account, an organization member with per-store permissions.

        Refused keys answer 403 with `Invalid API key.`, `API key revoked.`,

        `API key expired.` or `API key disabled.`.

        '
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Authorization: Token <token>'
x-tagGroups:
- name: Extractors
  tags:
  - Object Extractors
  - Tag Extractors
  - Chunks Extractors
  - Parsing Extractors
  - Document Filter Extractors
  - Chunk Tag Filter Extractors
  - Document Tag Extractors
  - Tag Alerts Extractors
  - Object Alerts Extractors
  - Imported Object Extractors
x-provenance:
  method: harvested
  publisher: Clarifeye
  source: https://docs.clarifeye.ai/api-reference/openapi-full.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)