Clarifeye Design System Templates API

openapi: 3.2.0
info:
  title: Clarifeye Platform API — Full API Documentation Design…
  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: Design System Templates
  description: Reference/example files attached to a design template.
paths:
  /projects/{project_id}/local-documents/import-to-design-template/:
    post:
      tags:
      - Design System Templates
      summary: Attach conversation files to a design template
      description: 'Copy conversation files (`LocalDocument`s attached to a coach conversation

        or an agent session) onto a design template as reference files. **Admin

        only.**


        Agent-generated files are allowed — attaching a generated shell docx/pptx

        is the point of the flow. A file whose name

        matches an existing reference file on the template replaces it. Unreadable

        files are skipped and reported rather than failing the batch. At most 20

        files per call. Used by the Work-with-Clara/MCP

        `import_files_to_design_template` tool.'
      operationId: importLocalDocumentsToDesignTemplate
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - local_document_ids
              - template_id
              properties:
                local_document_ids:
                  type: array
                  maxItems: 20
                  items:
                    type: string
                    format: uuid
                  description: LocalDocument UUIDs to attach (uploaded or generated).
                template_id:
                  type: string
                  format: uuid
                  description: The design template to attach the files to.
      responses:
        '201':
          description: 'Import completed (skipped files reported per item). A 201 does not mean every

            file landed: when all of them are skipped, `imported_count` is 0 and every id

            appears in `skipped`, so clients must read `skipped` rather than treating any

            2xx as a full success.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  imported_count:
                    type: integer
                  files:
                    type: array
                    items:
                      $ref: '#/components/schemas/DesignTemplateFile'
                  skipped:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
                        reason:
                          type: string
        '400':
          description: Empty/invalid ids, over-limit batch, or unknown template_id
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No matching local documents in this project
  /projects/{project_id}/design-template-files/:
    get:
      tags:
      - Design System Templates
      summary: List design template files
      description: 'List the project''s design template reference files (paginated). Optionally

        filter to a single template via `template_id`. Requires project view permission.'
      operationId: listDesignTemplateFiles
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - name: template_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Filter results to files attached to this design template.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/DesignTemplateFile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Design System Templates
      summary: Upload a design template file
      description: 'Upload a reference/example file and attach it to a design template. A file

        whose name matches an existing reference file on the template replaces it.

        Requires project-admin permission.'
      operationId: uploadDesignTemplateFile
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - template_id
              - file
              properties:
                template_id:
                  type: string
                  format: uuid
                  description: The design template to attach this file to.
                file:
                  type: string
                  format: binary
                  description: The file to upload.
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignTemplateFile'
        '400':
          description: Bad request - no file 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}/design-template-files/{file_id}/:
    delete:
      tags:
      - Design System Templates
      summary: Delete a design template file
      description: 'Delete a design template reference file from the project, removing it from

        storage. Requires project-admin permission.'
      operationId: deleteDesignTemplateFile
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: file_id
        in: path
        required: true
        description: UUID of the design template file
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: File 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
  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.
  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: {}
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
    DesignTemplateFile:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        template_id:
          type: string
          format: uuid
          description: Soft reference to the matching entry's id in the project's design_templates.
        name:
          type: string
        content_type:
          type:
          - string
          - 'null'
          readOnly: true
        signed_url:
          type:
          - string
          - 'null'
          format: uri
          readOnly: true
          description: Signed storage (GCS/S3) URL for browser/UI download and for the generation agent to fetch.
        created_at:
          type: string
          format: date-time
          readOnly: true
  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)