> ## Documentation Index > Fetch the complete documentation index at: https://docs.clarifeye.ai/llms.txt > Use this file to discover all available pages before exploring further. # Submit feedback > Submit feedback. The simplest form is direct feedback about content: just the feedback text and optional `context.additional_details`, with no conversation attached. Feedback can also be linked to a playground conversation message, or submitted by an agent through MCP. **Impersonation:** - When using impersonation, the feedback is submitted as the impersonated user ## Feedback Types | Type | is_positive Value | Description | |------|-------------------|-------------| | Thumbs up | `true` | Positive feedback | | Thumbs down | `false` | Negative feedback | | Neutral | `null` | Neutral or no sentiment | ## Query ID (conversation feedback only) The `query_id` identifies a specific user query and all related responses. It can be obtained from: - The streaming response (each message contains `query_id`) - The `streaming_completed` event's `chat_history` - The conversation retrieval endpoint ## OpenAPI ````yaml /api-reference/openapi-full.yaml post /projects/{project_id}/feedbacks/ openapi: 3.0.3 info: title: Clarifeye Platform API — Full API Documentation 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 ` ## Organization API Key Authentication The user-provisioning endpoints authenticate with an **org-scoped API key** instead of a user token: - `Authorization: Api-Key ` The key is minted internally by Clarifeye (not self-service) and is scoped to a single organization — it can only act on the organization whose UUID matches the `{id}` in the request path. The email domains a key may pre-create accounts for are configured by Clarifeye on the organization (`allowed_provisioning_domains`). Once you have a key and your domains are set, call `POST /organizations/{id}/provision-user/` to pre-create users and `POST /organizations/{id}/deprovision-user/` to remove them. ## 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: Users description: Manage users within a project - name: Invitations description: Manage project invitations - name: Documents description: Manage documents within a project - name: Agent Settings description: Manage AI agent configurations - name: Conversations description: Create and interact with AI-powered conversations - name: Interviews description: Assign and review structured interview conversations - name: Feedback description: >- Submit and review feedback — standalone (content-only), agent-submitted (MCP), or linked to a conversation message - name: Tools description: Execute configured AI tools with custom parameters - name: Tables description: Perform CRUD operations on warehouse tables - name: Notifications description: Manage project-scoped notifications for users - name: Extraction Flows description: >- Manage extraction flows (auto-sync DAGs) — list, run, inspect statistics, update, and publish - 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. - name: Tag Extractors description: | Apply hierarchical metadata tags to chunks or documents using an LLM. Update auto-creates a new `TagExtractorVersion` when version-bearing fields change. - name: Chunks Extractors description: | Segment parsed documents into chunks for downstream processing. Update auto-creates a new `ChunksExtractorVersion` when version-bearing fields change. - name: Parsing Extractors description: | Convert source documents to text blocks via the parsing pipeline. Update auto-creates a new `ParsingExtractorVersion` when version-bearing fields change. - name: Document Filter Extractors description: | Restrict a downstream pipeline branch to documents matching a filter. Update auto-creates a new version when the filter changes. - name: Chunk Tag Filter Extractors description: | Restrict a downstream pipeline branch to chunks carrying specific tags. Update auto-creates a new version when the filter changes. - name: Document Tag Extractors description: | Apply a flat set of metadata tags to each document. Update auto-creates a new version when version-bearing fields change. - name: Tag Alerts Extractors description: | Run LLM-based alerts over already-extracted tag rows. Update auto-creates a new version when version-bearing fields change. - name: Object Alerts Extractors description: > Run LLM-based alerts over already-extracted object rows. Update auto-creates a new version when version-bearing fields change. - name: Imported Object Extractors description: | Hold objects imported from an external system (rather than extracted by an LLM). Useful for hydrating the warehouse with data produced outside the platform. - name: Pipeline Runs description: >- Inspect pipeline runs queued by extraction flows or other pipeline triggers — list runs and fetch the details/status of a single run - name: User Provisioning description: > Pre-create and de-provision org users via an org-scoped API key (`Authorization: Api-Key `). The organization is resolved from the key. - name: Organization API Keys description: > Superuser management of org-scoped provisioning API keys. Minting and revoking are superuser-only; org admins can list/retrieve/reveal their own org's keys. - name: Design System Templates description: Reference/example files attached to a design template. paths: /projects/{project_id}/feedbacks/: post: tags: - Feedback summary: Submit feedback description: > Submit feedback. The simplest form is direct feedback about content: just the feedback text and optional `context.additional_details`, with no conversation attached. Feedback can also be linked to a playground conversation message, or submitted by an agent through MCP. **Impersonation:** - When using impersonation, the feedback is submitted as the impersonated user ## Feedback Types | Type | is_positive Value | Description | |------|-------------------|-------------| | Thumbs up | `true` | Positive feedback | | Thumbs down | `false` | Negative feedback | | Neutral | `null` | Neutral or no sentiment | ## Query ID (conversation feedback only) The `query_id` identifies a specific user query and all related responses. It can be obtained from: - The streaming response (each message contains `query_id`) - The `streaming_completed` event's `chat_history` - The conversation retrieval endpoint operationId: submitFeedback parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/ImpersonateEmail' requestBody: required: true content: application/json: schema: type: object required: - context properties: feedback: type: string description: Text comment (can be empty for quick feedback) example: We need to cover the EU refund rules in the knowledge base context: anyOf: - title: Direct feedback description: |- Feedback about content itself, not linked to a conversation. Just the feedback text plus optional additional details. Agents submitting through MCP set source=MCP and type=direct_feedback; plain API callers can omit both. type: object additionalProperties: true properties: additional_details: type: string description: |- Optional extra context provided alongside the feedback. Displayed in the review UI. Do not include user_query for this mode. source: type: string enum: - MCP description: Only set when submitted by an agent through MCP type: type: string enum: - direct_feedback - title: Interaction feedback (MCP) type: object additionalProperties: true required: - source properties: source: type: string enum: - MCP type: type: string description: >- Feedback type (e.g. user_dissatisfaction, missing_playbook) example: user_dissatisfaction user_query: type: string description: >- The original user request the agent was answering (verbatim) — not the corrective/feedback message. example: Generate document X - title: Conversation feedback type: object required: - conversation_id - query_id - source properties: conversation_id: type: string format: uuid description: ID of the conversation query_id: type: integer description: Query ID of the message to provide feedback on example: 0 source: type: string enum: - PlaygroundConversation description: Source of the feedback is_positive: type: boolean nullable: true description: | - `true`: Positive feedback (thumbs up) - `false`: Negative feedback (thumbs down) - `null`: Neutral feedback example: true examples: direct_feedback: summary: >- Feedback with additional details (not linked to a conversation) value: feedback: We need to cover the EU refund rules in the knowledge base is_positive: false context: additional_details: >- Several customer calls last week asked about EU refunds and we had nothing to point them to. conversation_feedback: summary: Feedback on a playground conversation message value: feedback: This answer was helpful and accurate is_positive: true context: source: PlaygroundConversation conversation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 query_id: 0 responses: '201': description: Feedback submitted successfully content: application/json: schema: $ref: '#/components/schemas/Feedback' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: parameters: 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 schemas: Feedback: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time given_by: type: object description: User who submitted the feedback properties: id: type: string format: uuid email: type: string format: email status: $ref: '#/components/schemas/FeedbackStatus' feedback: type: string description: Feedback text comment context: type: object additionalProperties: true description: |- Free-form context, echoed back as submitted at creation. Conversation feedback carries conversation_id/query_id/source; MCP interaction feedback carries user_query; direct feedback may carry additional_details. properties: conversation_id: type: string format: uuid deprecated: true description: Use the top-level `conversation` field instead query_id: type: integer description: >- Query ID of the message the feedback is about (conversation feedback) source: type: string description: PlaygroundConversation, MCP, or absent for direct API feedback user_query: type: string description: >- The original user request the agent was answering (MCP interaction feedback) additional_details: type: string description: Extra context provided alongside the feedback (direct feedback) is_positive: type: boolean nullable: true description: | - `true`: Positive feedback - `false`: Negative feedback - `null`: Neutral user_message: type: string description: The user message that was responded to (computed field) conversation_title: type: string description: Title of the conversation (computed field) suggested_action_type: type: string nullable: true description: Auto-generated suggested action type suggested_action_data: type: object description: Auto-generated suggested action data FeedbackStatus: type: string enum: - to_review - reviewed description: | - `to_review`: Feedback pending review (default) - `reviewed`: Feedback has been reviewed Error: type: object properties: error: type: string description: Error message example: error: User not found ValidationError: type: object additionalProperties: type: array items: type: string example: email: - This field is required. responses: BadRequest: description: Bad request - invalid parameters or request body content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' 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. securitySchemes: BearerAuth: type: http scheme: bearer description: 'Use Authorization: Bearer ' TokenAuth: type: apiKey in: header name: Authorization description: 'Use Authorization: Token ' ````