Clarifeye Conversations API

openapi: 3.2.0
info:
  title: Clarifeye Conversations API
  version: 1.0.0
  contact:
    name: Clarifeye Support
  description: 'Operations tagged Conversations across 2 of this provider''s published API definitions: clarifeye-backoffice-openapi-original.yaml, clarifeye-openapi-original.yaml. Each path carries the servers of the definition it was published in.'
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: Conversations
  description: Create and interact with AI-powered conversations
paths:
  /projects/{project_id}/playground-conversations/:
    get:
      tags:
      - Conversations
      summary: List conversations
      description: 'Retrieve all conversations for a project with optional filtering.


        **Access Control:**

        - Admins see all conversations (including shared ones)

        - Regular users see only conversations they created (including their own shared ones)

        - Shared conversations from other users are not shown in the list but are accessible via direct URL


        **Impersonation:**

        - When using impersonation, returns conversations created by the impersonated user


        **Filtering:**

        - Tags filtering uses OR logic (matches any of the provided tags)

        - Text filtering uses AND logic (combined with tag filters)'
      operationId: listConversations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      - name: tags
        in: query
        description: Filter by tags (OR logic). Can be specified multiple times or comma-separated.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        example:
        - analysis
        - review
      - name: no_tags
        in: query
        description: Set to "true" to filter for conversations with no tags
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: text
        in: query
        description: Search text within chat history (case-insensitive)
        schema:
          type: string
      - name: include_archived
        in: query
        description: Set to "true" to include archived conversations in results. Defaults to false (active conversations only).
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - $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/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Conversations
      summary: Create conversation
      description: 'Create a new AI-powered conversation.


        **Impersonation:**

        - When using impersonation, the conversation is created as the impersonated user'
      operationId: createConversation
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_settings
              properties:
                name:
                  type: string
                  description: Conversation name (auto-generated if not provided)
                  example: Analysis Session
                type:
                  type: string
                  default: playground
                  description: Conversation type
                agent_settings:
                  type: string
                  format: uuid
                  description: ID of the agent settings to use
                tags:
                  type: array
                  items:
                    type: string
                  description: Tags for organizing conversations
                  example:
                  - analysis
                  - review
                conversation_instructions:
                  type: string
                  description: Custom instructions for this conversation
                  example: Focus on financial data extraction
      responses:
        '201':
          description: Conversation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/playground-conversations/{conversation_id}/:
    get:
      tags:
      - Conversations
      summary: Get conversation
      description: 'Retrieve a conversation with its complete chat history.


        **Access Control:**

        - Admins can access any conversation

        - Regular users can access their own conversations

        - All project members can access shared conversations via direct URL'
      operationId: getConversation
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      - name: include_archived
        in: query
        description: Set to "true" to allow retrieving an archived conversation. Defaults to false.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Conversations
      summary: Archive conversation
      description: 'Soft-archive a conversation. The conversation is hidden from default list/get endpoints

        but is preserved in the database along with all linked feedback.


        To permanently delete an archived conversation, use the `permanent_delete` action.

        To restore an archived conversation, use the `unarchive` action.


        **Access Control:**

        - Admins can archive any conversation

        - Regular users can only archive conversations they created


        **Impersonation:**

        - When using impersonation, the ownership check is performed against the impersonated user'
      operationId: archiveConversation
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '204':
          description: Conversation archived successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - user does not own this conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/playground-conversations/{conversation_id}/unarchive/:
    post:
      tags:
      - Conversations
      summary: Unarchive conversation
      description: 'Restore a previously archived conversation back to active status.


        **Access Control:**

        - Admins can unarchive any conversation

        - Regular users can only unarchive conversations they created'
      operationId: unarchiveConversation
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '204':
          description: Conversation unarchived successfully
        '400':
          description: Conversation is not archived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/playground-conversations/{conversation_id}/permanent_delete/:
    post:
      tags:
      - Conversations
      summary: Permanently delete conversation
      description: 'Permanently delete an archived conversation and all its associated feedbacks.

        This action is irreversible.


        The conversation must be archived first (via the DELETE endpoint) before it can be permanently deleted.


        **Access Control:**

        - Superusers only, or project members with `CAN_PERFORM_ADMIN_ACTIONS` permission'
      operationId: permanentDeleteConversation
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      responses:
        '204':
          description: Conversation permanently deleted
        '400':
          description: Conversation is not archived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - admin permission required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/playground-conversations/{conversation_id}/send_message_stream/:
    post:
      tags:
      - Conversations
      summary: Send message (streaming)
      description: 'Send a message and receive a streaming response using Server-Sent Events (SSE).


        The response is a stream of newline-delimited JSON events. Use this endpoint for both

        initial messages and follow-up messages - conversation context is automatically preserved.


        **Access Control:**

        - For shared conversations, only the creator or admins can send messages

        - Other project members can view shared conversations but cannot send messages


        **Impersonation:**

        - When using impersonation, the message is sent as the impersonated user


        ## Streaming Event Types


        | Type | Description |

        |------|-------------|

        | `streaming_in_progress` | Intermediate event during response generation |

        | `streaming_error` | Error occurred during streaming |

        | `streaming_completed` | Final event with complete chat history |


        ## Payload Types (within streaming_in_progress)


        | Payload Type | Description |

        |--------------|-------------|

        | `start_token_streaming` | Stream is starting |

        | `token_streaming` | Text token being streamed |

        | `tool_call_request` | Tool is being invoked |

        | `tool_call` | Tool execution results |

        | `reasoning` | Reasoning step |'
      operationId: sendMessageStream
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
                  description: The user message to send
                  example: What information do you have about product pricing?
      responses:
        '200':
          description: Server-Sent Events stream
          content:
            text/event-stream:
              schema:
                type: string
              examples:
                streaming:
                  summary: Example streaming response
                  value: 'data: {"type_streaming": "streaming_in_progress", "payload": {"type": "start_token_streaming", "content": ""}}


                    data: {"type_streaming": "streaming_in_progress", "payload": {"type": "token_streaming", "content": "The"}}


                    data: {"type_streaming": "streaming_in_progress", "payload": {"type": "token_streaming", "content": "The document"}}


                    data: {"type_streaming": "streaming_in_progress", "payload": {"type": "tool_call", "tool_type": "semantic_chunks", "results": [...]}}


                    data: {"type_streaming": "streaming_completed", "payload": {"conversation_id": "uuid", "chat_history": [...]}}

                    '
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/playground-conversations/all-tags/:
    get:
      tags:
      - Conversations
      summary: Get all conversation tags
      description: 'Retrieve all unique tags used across conversations in the project.


        **Access Control:**

        - Admins see tags from all conversations

        - Regular users see only tags from conversations they created


        **Impersonation:**

        - When using impersonation, returns tags from conversations created by the impersonated user'
      operationId: getAllConversationTags
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      type: string
                    description: List of unique tags sorted alphabetically
                    example:
                    - analysis
                    - important
                    - review
                  count:
                    type: integer
                    description: Total number of unique tags
                    example: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/playground-conversations/{conversation_id}/share/:
    post:
      tags:
      - Conversations
      summary: Share conversation
      description: 'Share a conversation with all workspace members.


        When shared:

        - The conversation becomes accessible to all project members via direct URL

        - The conversation is hidden from the conversation list (to reduce clutter)

        - Only the creator and admins can send messages (read-only for others)


        **Access Control:**

        - Only the conversation creator or project admins can share a conversation'
      operationId: shareConversation
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      responses:
        '200':
          description: Conversation shared successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  is_shared:
                    type: boolean
                    example: true
        '400':
          description: Conversation is already shared
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Permission denied - only creator or admin can share
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/playground-conversations/{conversation_id}/unshare/:
    post:
      tags:
      - Conversations
      summary: Unshare conversation
      description: 'Remove sharing from a conversation.


        When unshared:

        - The conversation returns to the creator''s conversation list

        - Other project members lose access to the conversation


        **Access Control:**

        - Only the conversation creator or project admins can unshare a conversation'
      operationId: unshareConversation
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      responses:
        '200':
          description: Conversation unshared successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  is_shared:
                    type: boolean
                    example: false
        '400':
          description: Conversation is not shared
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Permission denied - only creator or admin can unshare
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
components:
  schemas:
    ChatMessage:
      type: object
      description: 'A message in the conversation. The `query_id` groups all messages from a single

        user interaction (user message, assistant response, tool calls).

        '
      properties:
        role:
          type: string
          enum:
          - user
          - assistant
        content:
          type: string
        type:
          type: string
          enum:
          - message
          - tool_call
          - reasoning_flow
        query_id:
          type: integer
          description: 'Unique identifier for this query. All messages from one interaction share the same query_id.

            Use this value when submitting feedback on a specific message.

            '
        user_id:
          type: string
          format: uuid
        used_tokens_input:
          type: integer
        used_tokens_output:
          type: integer
        timestamp:
          type: string
          format: date-time
        tool_type:
          type: string
          description: Type of tool (only for tool_call messages)
        input_parameters:
          type: object
          description: Tool input parameters (only for tool_call messages)
        results:
          type: array
          items: {}
          description: Tool results (only for tool_call messages)
    ValidationError:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      example:
        email:
        - This field is required.
    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: {}
    Conversation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
        created_by:
          type: string
          format: uuid
          description: ID of the user who created the conversation
        chat_history:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        agent_settings:
          type: string
          format: uuid
        agent_settings_name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        message_count:
          type: integer
        tool_call_count:
          type: integer
        tokens:
          type: object
          properties:
            input:
              type: integer
            output:
              type: integer
            total:
              type: integer
        tags:
          type: array
          items:
            type: string
        conversation_instructions:
          type:
          - string
          - 'null'
        is_shared:
          type: boolean
          description: Whether the conversation is shared with all workspace members
          default: false
        can_send_messages:
          type: boolean
          description: 'Whether the current user can send messages to this conversation.

            For shared conversations, only the creator and admins can send messages.

            '
        is_archived:
          type: boolean
          description: Whether the conversation has been soft-archived
          default: false
        archived_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the conversation was archived, null if not archived
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
    ChatMessage_2:
      type: object
      description: 'A message in the conversation. The `query_id` groups all messages from a

        single user interaction (user message, assistant response, tool calls).

        '
      properties:
        role:
          type: string
          enum:
          - user
          - assistant
        content:
          type: string
        type:
          type: string
          enum:
          - message
          - tool_call
          - reasoning_flow
        query_id:
          type: integer
        timestamp:
          type: string
          format: date-time
        tool_type:
          type: string
          description: Type of tool (only for tool_call messages).
        input_parameters:
          type: object
          description: Tool input parameters (only for tool_call messages).
        results:
          type: array
          items: {}
          description: Tool results (only for tool_call messages).
    Conversation_2:
      type: object
      description: A conversation with its complete chat history.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
        created_by:
          type: string
          format: uuid
        chat_history:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage_2'
        agent_settings:
          type:
          - string
          - 'null'
          format: uuid
        agent_settings_name:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string
        is_shared:
          type: boolean
        is_archived:
          type: boolean
        archived_at:
          type:
          - string
          - 'null'
          format: date-time
  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of results per page
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
    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
    ImpersonateEmail:
      name: X-Impersonate-Email
      in: header
      required: false
      description: 'Email of the user to impersonate. Requires `CAN_IMPERSONATE_OTHER_USERS` permission.

        If the target user is not found or does not have access to the project, the request

        proceeds as the authenticated user. Contact Clarifeye to enable this permission.

        '
      schema:
        type: string
        format: email
    ConversationId:
      name: conversation_id
      in: path
      required: true
      description: UUID of the conversation
      schema:
        type: string
        format: uuid
  responses:
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Error'
            - $ref: '#/components/schemas/ValidationError'
    NotFound:
      description: Not found - resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found.
    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.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use Authorization: Bearer <token>'
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Authorization: Token <token>'
x-refined-from:
- clarifeye-backoffice-openapi-original.yaml
- clarifeye-openapi-original.yaml