openapi: 3.0.3
info:
  title: Clarifeye Platform Agent Settings Documents 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: Documents
  description: Manage documents within a project
paths:
  /projects/{project_id}/documents/bulk-upload/:
    post:
      tags:
      - Documents
      summary: Bulk upload documents
      description: Upload multiple documents at once. Optionally skip the automatic parsing pipeline.
      operationId: bulkUploadDocuments
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - files
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: One or more files to upload
                skip_parsing:
                  type: string
                  enum:
                  - 'true'
                  - 'false'
                  default: 'false'
                  description: Set to "true" to skip automatic parsing pipeline
      responses:
        '201':
          description: Documents uploaded successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Document'
        '400':
          description: Bad request - no files uploaded or invalid file format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /projects/{project_id}/documents/{document_id}/:
    delete:
      tags:
      - Documents
      summary: Delete document
      description: 'Delete a document from the project. Deletion is performed asynchronously -

        the document is marked as "deleting" and removed in the background.

        '
      operationId: deleteDocument
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocumentId'
      responses:
        '204':
          description: Document deletion initiated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/documents/get-without-file/:
    get:
      tags:
      - Documents
      summary: List documents without file data
      description: Retrieve document metadata without file URLs for faster response times.
      operationId: listDocumentsWithoutFile
      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/DocumentMinimal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /projects/{project_id}/documents/filter-by-tag/:
    post:
      tags:
      - Documents
      summary: Filter documents by tag values
      description: 'Retrieve documents that match one or more tag values (case-insensitive).

        Pass tag values as a JSON array to avoid delimiter issues with values containing commas.

        '
      operationId: filterDocumentsByTag
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tag_values
              properties:
                tag_values:
                  type: array
                  items:
                    type: string
                  description: List of tag values to filter by (OR logic, case-insensitive).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/DocumentMinimal'
        '400':
          description: Missing or invalid tag_values array
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /projects/{project_id}/documents/filter-by-metadata/:
    post:
      tags:
      - Documents
      summary: Filter documents by metadata values
      description: 'Retrieve documents whose metadata contains one or more of the given values (case-insensitive, OR logic).


        Document metadata is stored as a list of `[key, value]` pairs. This endpoint matches against the

        **value** part of each pair. For example, if a document has metadata `[["category", "Finance"]]`,

        passing `metadata_values: ["finance"]` will match it.


        > **Note:** This endpoint requires documents to have metadata set. See the metadata management

        > endpoints below to add metadata to documents.

        '
      operationId: filterDocumentsByMetadata
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - metadata_values
              properties:
                metadata_values:
                  type: array
                  items:
                    type: string
                  description: List of metadata values to filter by (OR logic, case-insensitive).
            example:
              metadata_values:
              - Finance
              - Legal
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/DocumentMinimal'
        '400':
          description: Missing or invalid metadata_values array
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /projects/{project_id}/available-document-tags/:
    get:
      tags:
      - Documents
      summary: List available document tags
      description: 'Retrieve all available document tag names and their possible values for the project.


        Values are aggregated from both the tag extractor configuration (predefined possible values)

        and actual tag data already extracted from documents. Results are deduplicated and sorted.


        Document tags are **LLM-inferred** by tag extractors during pipeline runs,

        whereas document metadata is **user-entered** (supplied at upload time or edited

        via the metadata endpoints).

        '
      operationId: getAvailableDocumentTags
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
                description: 'Map of tag names to their available values.

                  '
              example:
                document_type:
                - Contract
                - Invoice
                - Report
                language:
                - English
                - French
                - German
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/available-document-metadata/:
    get:
      tags:
      - Documents
      summary: List available document metadata
      description: 'Retrieve all metadata keys and their distinct values across all active documents in the project.


        This is useful for building filter UIs or understanding what metadata has been applied to documents.


        Document metadata is **user-entered** (supplied at upload time or edited via the metadata endpoints),

        whereas document tags are **LLM-inferred** by tag extractors during pipeline runs.


        > **Note:** Document metadata requires the project to use the **auto-sync** data versioning option.

        '
      operationId: getAvailableDocumentMetadata
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
                description: 'Map of metadata keys to their distinct values (sorted).

                  '
              example:
                tag:
                - Finance
                - Legal
                source_path:
                - /path/to/document.pdf
                - /path/to/document.docx
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/document-tags-by-document/:
    get:
      tags:
      - Documents
      summary: Get document tags grouped by document
      description: 'Retrieve all document tags for the project, grouped by document ID.

        Optionally filter by specific document IDs.


        Each tag includes its name, value, and origin information (which table/row it came from).

        '
      operationId: getDocumentTagsByDocument
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: document_ids
        in: query
        required: false
        description: Comma-separated list of document UUIDs to filter by. If omitted, returns tags for all documents.
        schema:
          type: string
        example: 550e8400-e29b-41d4-a716-446655440000,6ba7b810-9dad-11d1-80b4-00c04fd430c8
      - name: include_deleted_rows
        in: query
        required: false
        description: Whether to include soft-deleted tag rows. Defaults to false.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    tags:
                      type: array
                      items:
                        type: object
                        properties:
                          tag_name:
                            type: string
                          tag_value:
                            type: string
                          origin:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: Row ID
                                table:
                                  type: string
                                  format: uuid
                                  description: Table ID
                                table_version_id:
                                  type: string
                                  format: uuid
                                  description: Table version ID
                description: 'Map of document IDs to their tags with origin information.

                  '
              example:
                550e8400-e29b-41d4-a716-446655440000:
                  tags:
                  - tag_name: document_type
                    tag_value: Contract
                    origin:
                    - id: row-1
                      table: table-uuid
                      table_version_id: version-uuid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/documents/{document_id}/metadata-add/:
    post:
      tags:
      - Documents
      summary: Add metadata to a document
      description: 'Add a key-value metadata pair to a document. The pair is appended to the document''s

        existing metadata list.


        Metadata is stored as a list of `[key, value]` string pairs. A document can have

        multiple values for the same key.


        > **Requires** the project to use the **auto-sync** data versioning option.

        '
      operationId: addDocumentMetadata
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataKeyValue'
            example:
              key: category
              value: Finance
      responses:
        '200':
          description: Metadata added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          description: Invalid request body
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/documents/{document_id}/metadata-remove-pair/:
    post:
      tags:
      - Documents
      summary: Remove a specific metadata pair
      description: 'Remove a specific key-value pair from a document''s metadata. Both key and value

        must match exactly for the pair to be removed.


        > **Requires** the project to use the **auto-sync** data versioning option.

        '
      operationId: removeDocumentMetadataPair
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataKeyValue'
            example:
              key: category
              value: Finance
      responses:
        '200':
          description: Operation completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed:
                    type: boolean
                    description: Whether the pair was found and removed
                  document:
                    $ref: '#/components/schemas/Document'
        '400':
          description: Invalid request body
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/documents/{document_id}/metadata-remove-key/:
    post:
      tags:
      - Documents
      summary: Remove all metadata pairs for a key
      description: 'Remove all metadata pairs matching the given key from a document, regardless

        of their values.


        > **Requires** the project to use the **auto-sync** data versioning option.

        '
      operationId: removeDocumentMetadataKey
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              properties:
                key:
                  type: string
                  description: The metadata key to remove
            example:
              key: category
      responses:
        '200':
          description: Operation completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed_count:
                    type: integer
                    description: Number of pairs removed
                  document:
                    $ref: '#/components/schemas/Document'
        '400':
          description: Invalid request body
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/documents/{document_id}/metadata-values/:
    get:
      tags:
      - Documents
      summary: Get metadata values for a key
      description: 'Retrieve all values associated with a given metadata key on a document.


        > **Requires** the project to use the **auto-sync** data versioning option.

        '
      operationId: getDocumentMetadataValues
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocumentId'
      - name: key
        in: query
        required: true
        description: The metadata key to retrieve values for
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
                    description: The requested metadata key
                  values:
                    type: array
                    items:
                      type: string
                    description: All values for the given key
              example:
                key: category
                values:
                - Finance
                - Legal
        '400':
          description: Missing query parameter 'key'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/documents/indexing-status/:
    get:
      tags:
      - Documents
      summary: Get document indexing status
      description: 'Returns the indexing status for each `(document, extractor node)` pair in the project.

        Callers poll this endpoint until documents reach `active` (queryable by AI) or `deleted`.


        **States:**

        | Value | Meaning |

        |---|---|

        | `created` | Document saved, processing not yet started |

        | `indexing` | Processing pipeline running |

        | `ready_to_publish` | Pipeline done, waiting for publish |

        | `active` | Published to search backends — queryable by AI |

        | `failed` | Document could not be parsed; will not be retried automatically |

        | `pending_delete` | Delete requested, blocking new pipeline steps |

        | `deleting` | Warehouse rows being cleared |

        | `deleted` | Fully removed from warehouse and search indexes |

        '
      operationId: getDocumentIndexingStatus
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: document_ids
        in: query
        required: false
        description: 'Comma-separated list of document UUIDs to filter the response.

          When omitted, returns statuses for all documents in the project.

          '
        schema:
          type: string
        example: 550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001
      responses:
        '200':
          description: Indexing statuses for the requested documents
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    document_id:
                      type: string
                      format: uuid
                    extractor_type:
                      type: string
                      description: Extractor node type (e.g. "TagExtractor", "ObjectExtractor")
                    extractor_id:
                      type: string
                      format: uuid
                    extractor_version_id:
                      type: string
                      format: uuid
                    status:
                      type: string
                      enum:
                      - created
                      - indexing
                      - ready_to_publish
                      - active
                      - failed
                      - pending_delete
                      - deleting
                      - deleted
              example:
              - document_id: 550e8400-e29b-41d4-a716-446655440000
                extractor_type: TagExtractor
                extractor_id: 660e8400-e29b-41d4-a716-446655440001
                extractor_version_id: 770e8400-e29b-41d4-a716-446655440002
                status: active
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of results per page
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
    DocumentId:
      name: document_id
      in: path
      required: true
      description: UUID of the document
      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
    ProjectId:
      name: project_id
      in: path
      required: true
      description: UUID of the project
      schema:
        type: string
        format: uuid
  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.
  schemas:
    MetadataKeyValue:
      type: object
      required:
      - key
      - value
      properties:
        key:
          type: string
          description: Metadata key
        value:
          type: string
          description: Metadata value
    DocumentMinimal:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Document filename
        content_type:
          type: string
          description: MIME type of the document
        page_count:
          type: integer
          nullable: true
          description: Number of pages in the document
        file_size:
          type: integer
          nullable: true
          description: File size in bytes
        metadata:
          type: array
          description: 'List of key-value metadata pairs. Each element is a two-element array `[key, value]`.

            '
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
        status:
          type: string
          enum:
          - active
          - deleting
          - deleted
          description: Document deletion status
    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Document filename
        file:
          type: string
          format: uri
          description: URL to the document file
        content_type:
          type: string
          description: MIME type of the document
          example: application/pdf
        computed_pdf_file:
          type: string
          format: uri
          nullable: true
          description: URL to generated PDF version (if applicable)
        source:
          type: string
          enum:
          - upload
          - connector
          description: Origin of the document
        source_metadata:
          type: object
          description: Metadata about the document source
        page_count:
          type: integer
          nullable: true
          description: Number of pages in the document
        file_size:
          type: integer
          nullable: true
          description: File size in bytes
        metadata:
          type: array
          description: 'List of key-value metadata pairs. Each element is a two-element array `[key, value]`.

            Requires the project to use the **auto-sync** data versioning option.

            '
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
          example:
          - - category
            - Finance
          - - region
            - EMEA
        status:
          type: string
          enum:
          - active
          - deleting
          - deleted
          description: Document deletion status
    PaginatedResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of results
        next:
          type: string
          format: uri
          nullable: true
          description: URL to next page of results
        previous:
          type: string
          format: uri
          nullable: true
          description: URL to previous page of results
        results:
          type: array
          items: {}
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use Authorization: Bearer <token>'
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Authorization: Token <token>'