openapi: 3.0.3
info:
  title: Clarifeye Platform Agent Settings Tables 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: Tables
  description: Perform CRUD operations on warehouse tables
paths:
  /projects/{project_id}/tables/{table_id}/data-operations/:
    post:
      tags:
      - Tables
      summary: Execute data operations
      description: 'Execute CRUD operations on table data.


        **Operations:**

        - `read`: Retrieve records with optional filtering and pagination

        - `create`: Insert new records

        - `update`: Update existing records (use `override` for full replacement)

        - `delete`: Remove records matching filters


        **Filtering:**

        Use the `filters` parameter to filter records by field values.

        Example: `{"document_id": "550e8400-e29b-41d4-a716-446655440000"}`


        **Column Selection:**

        Use the `columns` parameter to specify which fields to return in the response.

        '
      operationId: dataOperations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/TableId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataOperationRequest'
            examples:
              read:
                summary: Read with filters
                value:
                  operation: read
                  filters:
                    document_id: 550e8400-e29b-41d4-a716-446655440000
                  columns:
                  - id
                  - content
                  - document_id
                  limit: 50
                  offset: 0
              create:
                summary: Create records
                value:
                  operation: create
                  data:
                  - field1: value1
                    field2: value2
              update:
                summary: Update records
                value:
                  operation: update
                  filters:
                    id: 550e8400-e29b-41d4-a716-446655440000
                  data:
                  - field1: updated_value
                  override: false
              delete:
                summary: Delete by filter
                value:
                  operation: delete
                  filters:
                    document_id: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Operation executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataOperationResponse'
        '400':
          description: Invalid operation or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataOperationErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataOperationErrorResponse'
components:
  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.
  schemas:
    DataOperationResponse:
      type: object
      description: Response from a data operation
      properties:
        data:
          type: array
          description: Array of result records (for read operations)
          items:
            type: object
            additionalProperties: true
        count:
          type: integer
          description: Total number of affected/returned records
        success:
          type: boolean
          description: Whether the operation completed successfully
    DataOperationRequest:
      type: object
      required:
      - operation
      properties:
        operation:
          $ref: '#/components/schemas/DataOperationType'
        data:
          type: array
          description: Array of records for create/update operations
          items:
            type: object
            additionalProperties: true
        filters:
          type: object
          description: 'Dictionary of field-value pairs to filter records.

            Example: `{"document_id": "550e8400-e29b-41d4-a716-446655440000"}`

            '
          additionalProperties: true
        columns:
          type: array
          description: List of column names to include in the response
          items:
            type: string
          example:
          - id
          - content
          - document_id
        override:
          type: boolean
          description: For update operations, whether to fully replace records
          default: false
        table_version_id:
          type: string
          format: uuid
          description: Optional UUID to target a specific table version
        limit:
          type: integer
          description: Maximum number of records to return (for read operations)
          default: 100
        offset:
          type: integer
          description: Number of records to skip for pagination (for read operations)
          default: 0
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
    DataOperationType:
      type: string
      enum:
      - read
      - create
      - update
      - delete
      description: 'Type of data operation:

        - `read`: Retrieve records with optional filtering

        - `create`: Insert new records

        - `update`: Update existing records

        - `delete`: Remove records

        '
    DataOperationErrorResponse:
      type: object
      description: Error response from a data operation
      properties:
        errors:
          type: array
          description: Array of error messages
          items:
            type: string
        error:
          type: string
          description: Single error message
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: UUID of the project
      schema:
        type: string
        format: uuid
    TableId:
      name: table_id
      in: path
      required: true
      description: UUID of the table
      schema:
        type: string
        format: uuid
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use Authorization: Bearer <token>'
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Authorization: Token <token>'