Clarifeye Object Extractors API

openapi: 3.2.0
info:
  title: Clarifeye Platform API — Full API Documentation Object…
  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: Object Extractors
  description: 'Extract structured data (instances of a Pydantic model) from chunks or

    blocks of documents. Update auto-creates a new `ObjectExtractorVersion`

    when version-bearing fields change.'
paths:
  /projects/{project_id}/object-extractors/:
    get:
      tags:
      - Object Extractors
      summary: List object extractors
      description: List all `ObjectExtractor` rows in the project, newest first.
      operationId: listObjectExtractors
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $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/ObjectExtractor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Object Extractors
      summary: Create object extractor
      description: 'Create an `ObjectExtractor`. A first `ObjectExtractorVersion` is

        created automatically and marked as default. Pass `import_mode: true`

        to skip auto-version creation (bulk imports only).


        Required field: `name`.'
      operationId: createObjectExtractor
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectExtractor'
            example:
              name: Contract clauses
              brief: Extract obligations and effective dates from contracts.
              llm_model: gpt-4o
              extractable_pydantic_class: "from pydantic import BaseModel\nfrom typing import Optional\n\nclass ContractClause(BaseModel):\n    clause_type: str\n    text: str\n    effective_date: Optional[str] = None\n"
              extraction_prompt: Extract every distinct contractual obligation as a separate ContractClause object.
              document_ids: []
              add_anchoring_object: true
              extract_single_object: false
              compute_alerts: false
              extraction_mode: standard
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectExtractor'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /projects/{project_id}/object-extractors/{extractor_id}/:
    get:
      tags:
      - Object Extractors
      summary: Retrieve object extractor
      operationId: getObjectExtractor
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ExtractorId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectExtractor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Object Extractors
      summary: Update object extractor (auto-creates new version)
      description: 'Partial update of an `ObjectExtractor`. If any **version-bearing** field

        differs from the latest version, a new `ObjectExtractorVersion` row is

        created automatically. Version-bearing fields:

        `extractable_pydantic_class`, `extraction_prompt`, `llm_model`,

        `add_anchoring_object`, `filtered_on_block_types`, `block_types`,

        `extract_single_object`, `block_grouping_config`,

        `alerts_additional_instructions`.


        Pass `set_latest_as_default: true` to promote the newly created

        version to the default in the same call.'
      operationId: updateObjectExtractor
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ExtractorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ObjectExtractor'
              - type: object
                properties:
                  set_latest_as_default:
                    type: boolean
                    writeOnly: true
                    description: When true and a new version is created by this update, mark it as the default version.
            examples:
              renameOnly:
                summary: Rename — does NOT create a new version
                value:
                  name: Contract clauses (renamed)
              promptChange:
                summary: New prompt — creates a new version and promotes it
                value:
                  extraction_prompt: Extract obligations with explicit penalty clauses, including the penalty amount and trigger condition.
                  set_latest_as_default: true
              bumpModel:
                summary: Switch LLM model — creates a new version and promotes it
                value:
                  llm_model: gpt-4o-2024-08-06
                  set_latest_as_default: true
              tightenSchema:
                summary: Update Pydantic schema — creates a new version
                value:
                  extractable_pydantic_class: "from pydantic import BaseModel, Field\nfrom typing import Optional\nfrom datetime import date\n\nclass ContractClause(BaseModel):\n    clause_type: str = Field(..., description=\"One of: obligation, termination, payment.\")\n    text: str\n    effective_date: Optional[date] = None\n    penalty_amount: Optional[float] = None\n"
                  set_latest_as_default: true
      responses:
        '200':
          description: Updated. A new version may have been created — inspect `versions[]` to confirm.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectExtractor'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Object Extractors
      summary: Delete object extractor
      description: 'Delete the `ObjectExtractor`. Related warehouse tables

        (`extracted_objects_table`, `alerts_table`) are cleaned up on cascade.'
      operationId: deleteObjectExtractor
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ExtractorId'
      responses:
        '204':
          description: Deleted
        '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
    Offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
        minimum: 0
    Limit:
      name: limit
      in: query
      description: Maximum number of results per page
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
    ExtractorId:
      name: extractor_id
      in: path
      required: true
      description: UUID of the extractor
      schema:
        type: string
        format: uuid
  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.
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Error'
            - $ref: '#/components/schemas/ValidationError'
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: You do not have permission to perform this action.
  schemas:
    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: {}
    ObjectExtractorVersion:
      type: object
      description: 'Immutable snapshot of an `ObjectExtractor`''s version-bearing configuration.

        New version rows are created automatically on PATCH when any of these

        fields differs from the latest version.

        '
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        is_default:
          type: boolean
          readOnly: true
          description: Whether this version is the default version used by `run`.
        extractable_pydantic_class:
          type: string
          description: Python source of the Pydantic model used as the extraction schema.
          example: "from pydantic import BaseModel\nfrom typing import Optional\n\nclass ContractClause(BaseModel):\n    clause_type: str\n    text: str\n    effective_date: Optional[str] = None\n"
        extraction_prompt:
          type: string
          example: Extract every distinct contractual obligation as a separate ContractClause object.
        llm_model:
          type: string
          example: gpt-4o
        add_anchoring_object:
          type: boolean
          example: true
        filtered_on_block_types:
          type:
          - boolean
          - 'null'
        block_types:
          type:
          - array
          - 'null'
          items:
            type: string
          example:
          - text
          - table
        extract_single_object:
          type: boolean
          example: false
        block_grouping_config:
          type:
          - object
          - 'null'
          description: Optional configuration controlling how blocks are grouped before extraction.
        alerts_additional_instructions:
          type:
          - string
          - 'null'
        extraction_mode:
          type:
          - string
          - 'null'
          enum:
          - standard
          - agentic
          default: standard
        agentic_config:
          type:
          - object
          - 'null'
          description: Configuration for `agentic` extraction mode.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
    ObjectExtractor:
      type: object
      description: 'Extracts structured data (instances of a Pydantic model) from chunks

        or blocks of documents.

        '
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          description: Human-readable name.
          example: Contract clauses
        brief:
          type: string
          description: Short description shown in the UI.
          example: Extract obligations and effective dates from contracts.
        llm_model:
          type: string
          example: gpt-4o
        extractable_object:
          type:
          - string
          - 'null'
          description: Display name of the object class (auto-derived from `extractable_pydantic_class` if omitted).
          example: ContractClause
        extractable_pydantic_class:
          type: string
          description: Python source of the Pydantic model used as the extraction schema.
          example: "from pydantic import BaseModel\nfrom typing import Optional\n\nclass ContractClause(BaseModel):\n    clause_type: str\n    text: str\n    effective_date: Optional[str] = None\n"
        extraction_prompt:
          type: string
          example: Extract every distinct contractual obligation as a separate ContractClause object.
        document_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Documents to extract from. Empty array means "all documents in the project".
          example:
          - b3c1d2e4-5f6a-4b7c-8d9e-0a1b2c3d4e5f
        document_ranges:
          type:
          - object
          - 'null'
          description: 'Optional per-document page-range filter (`{document_id: [start_page, end_page]}`).'
        compute_alerts:
          type: boolean
          default: false
          example: false
        add_anchoring_object:
          type: boolean
          default: false
          example: true
        filtered_on_block_types:
          type:
          - boolean
          - 'null'
        block_types:
          type:
          - array
          - 'null'
          items:
            type: string
          example:
          - text
          - table
        extract_single_object:
          type: boolean
          default: false
        block_grouping_config:
          type:
          - object
          - 'null'
        pre_execution_filter:
          type:
          - object
          - 'null'
          description: Filter applied to the source chunks/blocks before extraction runs.
        alerts_additional_instructions:
          type:
          - string
          - 'null'
        alerts_llm_model:
          type:
          - string
          - 'null'
        extraction_mode:
          type: string
          enum:
          - standard
          - agentic
          default: standard
        agentic_config:
          type:
          - object
          - 'null'
          description: Configuration for `agentic` extraction mode.
        import_mode:
          type: boolean
          writeOnly: true
          default: false
          description: Bulk-import flag. When `true`, the create endpoint skips auto-version creation.
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        prompt_generation_status:
          type:
          - string
          - 'null'
          readOnly: true
        deployed_extractable_pydantic_class:
          type:
          - string
          - 'null'
          readOnly: true
        deployed_extraction_prompt:
          type:
          - string
          - 'null'
          readOnly: true
        deployed_llm_model:
          type:
          - string
          - 'null'
          readOnly: true
        extracted_objects_table:
          type:
          - string
          - 'null'
          format: uuid
          readOnly: true
          description: ID of the warehouse `Table` where extracted objects are stored.
        alerts_table:
          type:
          - string
          - 'null'
          format: uuid
          readOnly: true
        object_name:
          type: string
          readOnly: true
        blocks_table_version_info:
          type:
          - object
          - 'null'
          readOnly: true
        chunks_table_version_info:
          type:
          - object
          - 'null'
          readOnly: true
        table_version_updates:
          type:
          - object
          - 'null'
          readOnly: true
        versions:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/ObjectExtractorVersion'
        default_version:
          allOf:
          - $ref: '#/components/schemas/ObjectExtractorVersion'
          readOnly: true
        latest_version:
          allOf:
          - $ref: '#/components/schemas/ObjectExtractorVersion'
          readOnly: true
    ValidationError:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      example:
        email:
        - This field is required.
  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)