# Get conversation Source: https://docs.clarifeye.ai/api-reference/conversations/get-conversation /api-reference/openapi-public.yaml get /projects/{project_id}/playground-conversations/{conversation_id}/ Retrieve a conversation with its complete chat history. # Bulk upload documents Source: https://docs.clarifeye.ai/api-reference/documents/bulk-upload-documents /api-reference/openapi-public.yaml post /projects/{project_id}/documents/bulk-upload/ Upload multiple documents at once. Optionally skip the automatic parsing pipeline. Per-file metadata can be attached at upload time via the `files_metadata` field so documents arrive with their metadata already set (no follow-up `metadata-add` calls needed). Documents are queued for processing asynchronously — no pipeline is spawned inline. Poll `/documents/indexing-status/` to track progress. # Delete document Source: https://docs.clarifeye.ai/api-reference/documents/delete-document /api-reference/openapi-public.yaml delete /projects/{project_id}/documents/{document_id}/ Delete a document from the project. Deletion is always asynchronous. The document is queued for deletion. All associated warehouse data, search indexes, and graph nodes are removed asynchronously. Poll `/documents/indexing-status/` to confirm the document reaches `deleted`. # Filter documents by metadata values Source: https://docs.clarifeye.ai/api-reference/documents/filter-documents-by-metadata-values /api-reference/openapi-public.yaml post /projects/{project_id}/documents/filter-by-metadata/ 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. # Filter documents by tag values Source: https://docs.clarifeye.ai/api-reference/documents/filter-documents-by-tag-values /api-reference/openapi-public.yaml post /projects/{project_id}/documents/filter-by-tag/ 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. # Get document indexing status Source: https://docs.clarifeye.ai/api-reference/documents/get-document-indexing-status /api-reference/openapi-public.yaml get /projects/{project_id}/documents/indexing-status/ 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 | # List documents without file data Source: https://docs.clarifeye.ai/api-reference/documents/list-documents-without-file-data /api-reference/openapi-public.yaml get /projects/{project_id}/documents/get-without-file/ Retrieve document metadata without file URLs for faster response times. # Create and assign interviews Source: https://docs.clarifeye.ai/api-reference/interviews/create-and-assign-interviews /api-reference/openapi-public.yaml post /projects/{project_id}/interviews/assign/ Create and assign one interview per assignee. **Admin only.** Provide existing project members via `assignee_ids` and/or new people to invite via `invite_emails` (at least one is required). Invitees are added as non-admin Contributors. A separate interview is created for each assignee and the response is the list of created interviews. `write_scope` defaults to `local`. A `global` write scope requires every assignee to already be a project admin and cannot be combined with `invite_emails`. `campaign_id` / `campaign_name` group the created interviews under an interview campaign (e.g. a workshop wave). `campaign_id` picks an existing campaign of the project; `campaign_name` reuses the project's campaign with that name (case-insensitive) or creates it. # Import an external interview transcript Source: https://docs.clarifeye.ai/api-reference/interviews/import-an-external-interview-transcript /api-reference/openapi-public.yaml post /projects/{project_id}/interviews/import-transcript/ Import the transcript of an interview recorded outside the platform (e.g. a Granola/Teams/Zoom export). **Admin only.** Creates a read-only interview (type "imported-interview") and enqueues an async parse that turns the raw text into speaker-labeled `chat_history` messages plus inferred metadata. The response returns immediately with `import_info.import_status = "parsing"`; poll the interview detail endpoint until it is "ready" (`status` becomes "completed") before reading the transcript. All metadata fields are optional — anything omitted is inferred from the transcript; importer-supplied values always win. To import several transcripts, call this endpoint once per transcript — each import becomes its own interview and parses independently. # List interview campaigns Source: https://docs.clarifeye.ai/api-reference/interviews/list-interview-campaigns /api-reference/openapi-public.yaml get /projects/{project_id}/interview-campaigns/ List the project's interview campaigns (named groups of interviews, e.g. a workshop wave or rollout round), newest first. Any project member can read. Campaigns are created lazily — by sending `campaign_name` on the assign endpoint — so there are no create/rename/delete endpoints. Use a campaign's `id` with the interviews list `campaign` filter to read its interviews. # List interviews Source: https://docs.clarifeye.ai/api-reference/interviews/list-interviews /api-reference/openapi-public.yaml get /projects/{project_id}/interviews/ Retrieve interviews for a project. - Admins see all interviews in the project. - Other members see only interviews assigned to them or that they created. Results are ordered newest first, with interviews of the same campaign kept contiguous so clients can render campaign groups across pages. # Retrieve interview content Source: https://docs.clarifeye.ai/api-reference/interviews/retrieve-interview-content /api-reference/openapi-public.yaml get /projects/{project_id}/interviews/{interview_id}/ Retrieve a single interview with its full content, including the complete `chat_history` transcript and `chat_memory`. Non-admins can only retrieve interviews assigned to them or that they created; admins can retrieve any interview in the project. # Cancel invitation Source: https://docs.clarifeye.ai/api-reference/invitations/cancel-invitation /api-reference/openapi-public.yaml delete /projects/{project_id}/invites/{invite_id}/ Cancel a pending invitation. Only pending invitations can be cancelled. # Invite user to project Source: https://docs.clarifeye.ai/api-reference/invitations/invite-user-to-project /api-reference/openapi-public.yaml post /projects/{project_id}/invites/invite/ Invite a user to join the project. - For new users (not registered): Creates a pending invite and sends an email. - For existing users: Automatically accepts the invite and sends a notification. # List invitations Source: https://docs.clarifeye.ai/api-reference/invitations/list-invitations /api-reference/openapi-public.yaml get /projects/{project_id}/invites/ Retrieve all invitations for a project with optional filtering by status. # List signals Source: https://docs.clarifeye.ai/api-reference/signals/list-signals /api-reference/openapi-public.yaml get /projects/{project_id}/signals/ Retrieve all signals for a project with optional filtering. **Access Control:** - Admins see all signals in the project - Regular users see only signals they submitted **Sorting:** - Results are ordered by most recently updated first (`updated_at` field) **Note:** For grouped views by conversation, use `/projects/{project_id}/signals/grouped_by_conversation/` # Submit a signal Source: https://docs.clarifeye.ai/api-reference/signals/submit-a-signal /api-reference/openapi-public.yaml post /projects/{project_id}/signals/ Submit a signal about the project's content: the signal text itself, plus optional `context.additional_details` with extra context for the reviewer. The signal shows up in the review UI for domain experts. ## Signal Types | Type | is_positive Value | Description | |------|-------------------|-------------| | Thumbs up | `true` | Positive signal | | Thumbs down | `false` | Negative signal | | Neutral | `null` | Neutral or no sentiment | # Update signal status Source: https://docs.clarifeye.ai/api-reference/signals/update-signal-status /api-reference/openapi-public.yaml patch /projects/{project_id}/signals/{signal_id}/ Mark a signal as reviewed or update other fields. **Access Control:** - Admins can update any signal - Regular users can only update signals they submitted # Get tool parameters schema Source: https://docs.clarifeye.ai/api-reference/tools/get-tool-parameters-schema /api-reference/openapi-public.yaml get /projects/{project_id}/tools/{tool_id}/parameters/ Return the JSON schema describing the parameters accepted by [`runTool`](#operation/runTool) for this tool. The schema is a list of parameter specs (`id`, `type`, `description`, `required`, and an optional `default`). The exact list depends on the tool's `tool_type` and configuration — for example a retrieval tool configured with `auto_include` tags exposes an extra `included_tags` parameter. Use the `id` of each entry as the key in the JSON body sent to [`runTool`](#operation/runTool). # List tools Source: https://docs.clarifeye.ai/api-reference/tools/list-tools /api-reference/openapi-public.yaml get /projects/{project_id}/tools/ List all tools available to the project, including tools owned by the project (`category: local`) and tools imported from other projects (`category: imported`). Use the returned `id` together with [`getToolParameters`](#operation/getToolParameters) to discover the request body schema for a given tool, then call [`runTool`](#operation/runTool) to execute it. # Run a tool Source: https://docs.clarifeye.ai/api-reference/tools/run-a-tool /api-reference/openapi-public.yaml post /projects/{project_id}/tools/{tool_id}/run/ Execute a configured tool with provided parameters. The request body varies based on the tool type. Call [`getToolParameters`](#operation/getToolParameters) first to discover the exact parameter schema for a given tool — most retrieval tools accept `query` and `top_k`, but other tool types (e.g. `document_retrieval`) expect different fields. # List project users Source: https://docs.clarifeye.ai/api-reference/users/list-project-users /api-reference/openapi-public.yaml get /projects/{project_id}/users/ Retrieve all users with access to a project. # Remove user by email Source: https://docs.clarifeye.ai/api-reference/users/remove-user-by-email /api-reference/openapi-public.yaml post /projects/{project_id}/users/remove-by-email/ Remove a user from the project using their email address. Users cannot remove themselves. # Update user permissions Source: https://docs.clarifeye.ai/api-reference/users/update-user-permissions /api-reference/openapi-public.yaml patch /projects/{project_id}/users/{permission_id}/ Update a user's permissions on the project. # List agent settings Source: https://docs.clarifeye.ai/backoffice/agent-settings/list-agent-settings /api-reference/openapi-full.yaml get /projects/{project_id}/agent-settings/ Retrieve all agent settings (AI agent configurations) for a project. Results are ordered by most recently updated first. # Create a custom artifact Source: https://docs.clarifeye.ai/backoffice/artifacts/create-a-custom-artifact /api-reference/openapi-full.yaml post /projects/{project_id}/artifacts/ Create a custom artifact (`semantic_type` is always `custom`; predefined artifacts are seeded by the platform). The slug must be unique within the project. An initial empty version is published automatically. Requires admin permission. # Delete an artifact Source: https://docs.clarifeye.ai/backoffice/artifacts/delete-an-artifact /api-reference/openapi-full.yaml delete /projects/{project_id}/artifacts/{slug}/ Delete an artifact and its versions. Rejected when the artifact's delete preconditions are not met (see `can_delete` on the summary). Requires admin permission. # Export the artifact catalog Source: https://docs.clarifeye.ai/backoffice/artifacts/export-the-artifact-catalog /api-reference/openapi-full.yaml get /projects/{project_id}/artifacts/export-catalog/ Export the full artifact catalog — artifact metadata, complete version history (payloads included), and snapshot settings — for migration to another project. Requires view permission. # Import an artifact catalog Source: https://docs.clarifeye.ai/backoffice/artifacts/import-an-artifact-catalog /api-reference/openapi-full.yaml post /projects/{project_id}/artifacts/import-catalog/ Import a full catalog (same shape as the export) into a project whose catalog is still empty — the import is rejected if the project already has catalog rows. Only `in_scope_latest` snapshots are supported. Requires admin permission. # List artifact versions Source: https://docs.clarifeye.ai/backoffice/artifacts/list-artifact-versions /api-reference/openapi-full.yaml get /projects/{project_id}/artifacts/{slug}/versions/ List all versions of an artifact, newest first, payloads included. Not paginated. Requires view permission. # List artifacts in the catalog Source: https://docs.clarifeye.ai/backoffice/artifacts/list-artifacts-in-the-catalog /api-reference/openapi-full.yaml get /projects/{project_id}/artifacts/ List the project's artifact catalog (paginated). In-scope artifacts sort before out-of-scope ones, then by `display_order` and `slug`. Requires view permission. # Publish a new artifact version Source: https://docs.clarifeye.ai/backoffice/artifacts/publish-a-new-artifact-version /api-reference/openapi-full.yaml post /projects/{project_id}/artifacts/{slug}/versions/ Publish a new head version with the given payload. The payload shape depends on the artifact's `technical_type` — string for `markdown` / `bpmn_xml`, object for `mental_map`, array for `playbook_list` / `design_template_list`. Requires admin permission. # Read the cohesion guide Source: https://docs.clarifeye.ai/backoffice/artifacts/read-the-cohesion-guide /api-reference/openapi-full.yaml get /projects/{project_id}/artifacts/cohesion-guide/ Read the default artifact snapshot's cross-artifact cohesion guide. `default_cohesion_guide` carries the platform default text so clients can preview what `mode=default` resolves to. Requires view permission. # Remove an artifact from scope Source: https://docs.clarifeye.ai/backoffice/artifacts/remove-an-artifact-from-scope /api-reference/openapi-full.yaml post /projects/{project_id}/artifacts/{slug}/remove-from-scope/ Take the artifact out of the knowledge-store scope (it stays in the catalog and keeps its history). The brief artifact cannot be removed from scope. Requires admin permission. # Restore an artifact to scope Source: https://docs.clarifeye.ai/backoffice/artifacts/restore-an-artifact-to-scope /api-reference/openapi-full.yaml post /projects/{project_id}/artifacts/{slug}/restore-to-scope/ Put an out-of-scope artifact back in scope. Requires admin permission. # Retrieve an artifact Source: https://docs.clarifeye.ai/backoffice/artifacts/retrieve-an-artifact /api-reference/openapi-full.yaml get /projects/{project_id}/artifacts/{slug}/ Retrieve one artifact with its definitions and the payload of the selected version (head by default; pass `version` to read an older one). Requires view permission. # Retrieve an artifact version Source: https://docs.clarifeye.ai/backoffice/artifacts/retrieve-an-artifact-version /api-reference/openapi-full.yaml get /projects/{project_id}/artifacts/{slug}/versions/{version_number}/ Retrieve one version of an artifact by number. Requires view permission. # Update a custom artifact Source: https://docs.clarifeye.ai/backoffice/artifacts/update-a-custom-artifact /api-reference/openapi-full.yaml patch /projects/{project_id}/artifacts/{slug}/ Update a custom artifact's metadata (title, group, definitions). Only fields present in the request are touched. Predefined artifacts cannot be edited. Requires admin permission. # Update the cohesion guide Source: https://docs.clarifeye.ai/backoffice/artifacts/update-the-cohesion-guide /api-reference/openapi-full.yaml patch /projects/{project_id}/artifacts/cohesion-guide/ Update the default snapshot's cohesion guide. When `cohesion_guide_mode` is `default`, `cohesion_guide_text` is cleared server-side. Requires admin permission. # Create chunk tag filter extractor Source: https://docs.clarifeye.ai/backoffice/chunk-tag-filter-extractors/create-chunk-tag-filter-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/chunk-tag-filter-extractors/ Create a `ChunkTagFilterExtractor` — restricts a downstream pipeline branch to chunks carrying specific tags. # Delete chunk tag filter extractor Source: https://docs.clarifeye.ai/backoffice/chunk-tag-filter-extractors/delete-chunk-tag-filter-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/chunk-tag-filter-extractors/{extractor_id}/ # List chunk tag filter extractors Source: https://docs.clarifeye.ai/backoffice/chunk-tag-filter-extractors/list-chunk-tag-filter-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/chunk-tag-filter-extractors/ # Retrieve chunk tag filter extractor Source: https://docs.clarifeye.ai/backoffice/chunk-tag-filter-extractors/retrieve-chunk-tag-filter-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/chunk-tag-filter-extractors/{extractor_id}/ # Update chunk tag filter extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/chunk-tag-filter-extractors/update-chunk-tag-filter-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/chunk-tag-filter-extractors/{extractor_id}/ Partial update. Version-bearing field: `filter`. Pass `set_latest_as_default: true` to promote the new version. # Create chunks extractor Source: https://docs.clarifeye.ai/backoffice/chunks-extractors/create-chunks-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/chunks-extractors/ Create a `ChunksExtractor`. A first `ChunksExtractorVersion` is created automatically and marked as default. # Delete chunks extractor Source: https://docs.clarifeye.ai/backoffice/chunks-extractors/delete-chunks-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/chunks-extractors/{extractor_id}/ Delete the `ChunksExtractor`. The related `extracted_chunks_table` is cleaned up on cascade. # List chunks extractors Source: https://docs.clarifeye.ai/backoffice/chunks-extractors/list-chunks-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/chunks-extractors/ # Retrieve chunks extractor Source: https://docs.clarifeye.ai/backoffice/chunks-extractors/retrieve-chunks-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/chunks-extractors/{extractor_id}/ # Update chunks extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/chunks-extractors/update-chunks-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/chunks-extractors/{extractor_id}/ Partial update. Version-bearing fields: `maximum_chunk_size`, `minimum_chunk_size`, `page_as_separator`, `title_section_separator_mode`, `excluded_block_types`, `chunking_mode`. Pass `set_latest_as_default: true` to promote the new version. # Get a single chunk by id (version-agnostic) Source: https://docs.clarifeye.ai/backoffice/chunks/get-a-single-chunk-by-id-version-agnostic /api-reference/openapi-full.yaml get /projects/{project_id}/chunks/{chunk_id}/ Fetch one chunk row by its id, independent of which extractor version produced it. Chunk ids are random UUIDs (unique within the chunk table), so the lookup is unambiguous and does not require the extractor version. Used by the standalone reference viewer (`//reference/`) so a citation still resolves even when the chunk was created by an old / non-default extractor version. # Back office concepts Source: https://docs.clarifeye.ai/backoffice/concepts The extraction flow, extractors, agent settings, and tools — for technical users who customize Clarifeye. This page is for technical users — developers, integrators, and admins — who want to interact with Clarifeye beyond what the standard knowledge-store UI exposes. The back office is built around the **extraction flow** — the pipeline that turns raw documents into searchable content. A flow chains the operations applied to each input (parsing, chunking, chunk tags, document tags, object extraction) and writes each step's output to its own table. Every extractor output is versioned, so historical rows for a given extractor version remain queryable through the `extractor-table-retrieval` endpoint as the flow evolves. Once a flow runs in production, **tools** retrieve from those tables — search on chunks, search on objects, or templated Cypher queries for more advanced lookups. **Agent settings** then assemble those tools with the knowledge curated by domain experts (project brief, knowledge schema, tag hierarchies) into the agent that answers questions. For new AI-client integrations, prefer [MCP](/guides/mcp). The back office is the place to customize the pipeline or maintain integrations that predate MCP. # Dry-run count of what an import would do Source: https://docs.clarifeye.ai/backoffice/connectors/dry-run-count-of-what-an-import-would-do /api-reference/openapi-full.yaml post /projects/{project_id}/connections/{connection_id}/import-preview/ Enumerates provider metadata (no downloads) for the given folder/file selection and diffs it against already-imported documents. An empty selection falls back to the connection's stored selection. Enumeration is budgeted (item, request, and wall-clock caps): when `truncated` is true, `to_create`/`to_update` are partial lower bounds and `to_delete` is null (a partial enumeration cannot prove a file was removed). # Archive conversation Source: https://docs.clarifeye.ai/backoffice/conversations/archive-conversation /api-reference/openapi-full.yaml delete /projects/{project_id}/playground-conversations/{conversation_id}/ 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 # Create conversation Source: https://docs.clarifeye.ai/backoffice/conversations/create-conversation /api-reference/openapi-full.yaml post /projects/{project_id}/playground-conversations/ Create a new AI-powered conversation. **Impersonation:** - When using impersonation, the conversation is created as the impersonated user # Get all conversation tags Source: https://docs.clarifeye.ai/backoffice/conversations/get-all-conversation-tags /api-reference/openapi-full.yaml get /projects/{project_id}/playground-conversations/all-tags/ 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 # Get conversation Source: https://docs.clarifeye.ai/backoffice/conversations/get-conversation /api-reference/openapi-full.yaml get /projects/{project_id}/playground-conversations/{conversation_id}/ 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 # List conversations Source: https://docs.clarifeye.ai/backoffice/conversations/list-conversations /api-reference/openapi-full.yaml get /projects/{project_id}/playground-conversations/ 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) # Permanently delete conversation Source: https://docs.clarifeye.ai/backoffice/conversations/permanently-delete-conversation /api-reference/openapi-full.yaml post /projects/{project_id}/playground-conversations/{conversation_id}/permanent_delete/ 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 # Poll turn status Source: https://docs.clarifeye.ai/backoffice/conversations/poll-turn-status /api-reference/openapi-full.yaml get /projects/{project_id}/playground-conversations/{conversation_id}/poll/ Return the in-flight turn state for a conversation: the current `turn_status`, the accumulated message-level `turn_events` buffer, and `updated_at`. Clients poll this every few seconds after `send_message` returns `202` and re-render from the returned events. A `RUNNING` turn whose `updated_at` has gone stale is transitioned to `failed` on read. # Retrieve conversation feedback Source: https://docs.clarifeye.ai/backoffice/conversations/retrieve-conversation-feedback /api-reference/openapi-full.yaml get /projects/{project_id}/playground-conversations/{conversation_id}/retrieve-feedback/ List all feedback (including text content) attached to a conversation. This is the only endpoint that returns other users' feedback content on shared conversations — the project-level `/feedbacks/` list stays scoped to the caller's own feedback for non-admins. **Access Control:** - Admins can read feedback of any conversation - Other members can read feedback of their own conversations or of shared conversations - Supports impersonation: visibility is evaluated for the impersonated user # Send message (async) Source: https://docs.clarifeye.ai/backoffice/conversations/send-message-async /api-reference/openapi-full.yaml post /projects/{project_id}/playground-conversations/{conversation_id}/send_message/ Enqueue a chat turn and return `202 Accepted`. The turn runs in a background Celery task; poll the `poll` endpoint for progress and the final result. This replaces the former SSE `send_message_stream` endpoint. Use this endpoint for both initial 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 # Share conversation Source: https://docs.clarifeye.ai/backoffice/conversations/share-conversation /api-reference/openapi-full.yaml post /projects/{project_id}/playground-conversations/{conversation_id}/share/ 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 # Unarchive conversation Source: https://docs.clarifeye.ai/backoffice/conversations/unarchive-conversation /api-reference/openapi-full.yaml post /projects/{project_id}/playground-conversations/{conversation_id}/unarchive/ Restore a previously archived conversation back to active status. **Access Control:** - Admins can unarchive any conversation - Regular users can only unarchive conversations they created # Unshare conversation Source: https://docs.clarifeye.ai/backoffice/conversations/unshare-conversation /api-reference/openapi-full.yaml post /projects/{project_id}/playground-conversations/{conversation_id}/unshare/ 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 # Delete a design template file Source: https://docs.clarifeye.ai/backoffice/design-system-templates/delete-a-design-template-file /api-reference/openapi-full.yaml delete /projects/{project_id}/design-template-files/{file_id}/ Delete a design template reference file from the project, removing it from storage. Requires project-admin permission. # List design template files Source: https://docs.clarifeye.ai/backoffice/design-system-templates/list-design-template-files /api-reference/openapi-full.yaml get /projects/{project_id}/design-template-files/ List the project's design template reference files (paginated). Optionally filter to a single template via `template_id`. Requires project view permission. # Upload a design template file Source: https://docs.clarifeye.ai/backoffice/design-system-templates/upload-a-design-template-file /api-reference/openapi-full.yaml post /projects/{project_id}/design-template-files/ Upload a reference/example file and attach it to a design template. Requires project-admin permission. # Create document filter extractor Source: https://docs.clarifeye.ai/backoffice/document-filter-extractors/create-document-filter-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/document-filter-extractors/ Create a `DocumentFilterExtractor` — restricts a downstream pipeline branch to documents matching the configured filter. # Delete document filter extractor Source: https://docs.clarifeye.ai/backoffice/document-filter-extractors/delete-document-filter-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/document-filter-extractors/{extractor_id}/ # List document filter extractors Source: https://docs.clarifeye.ai/backoffice/document-filter-extractors/list-document-filter-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/document-filter-extractors/ # Retrieve document filter extractor Source: https://docs.clarifeye.ai/backoffice/document-filter-extractors/retrieve-document-filter-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/document-filter-extractors/{extractor_id}/ # Update document filter extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/document-filter-extractors/update-document-filter-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/document-filter-extractors/{extractor_id}/ Partial update. Version-bearing field: `filter`. Pass `set_latest_as_default: true` to promote the new version. # Create document tag extractor Source: https://docs.clarifeye.ai/backoffice/document-tag-extractors/create-document-tag-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/document-tag-extractors/ Create a `DocumentTagExtractor` — applies a flat set of metadata tags to each document. # Delete document tag extractor Source: https://docs.clarifeye.ai/backoffice/document-tag-extractors/delete-document-tag-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/document-tag-extractors/{extractor_id}/ Delete the `DocumentTagExtractor`. The related `extracted_document_tags_table` is cleaned up on cascade. # List document tag extractors Source: https://docs.clarifeye.ai/backoffice/document-tag-extractors/list-document-tag-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/document-tag-extractors/ # Retrieve document tag extractor Source: https://docs.clarifeye.ai/backoffice/document-tag-extractors/retrieve-document-tag-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/document-tag-extractors/{extractor_id}/ # Update document tag extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/document-tag-extractors/update-document-tag-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/document-tag-extractors/{extractor_id}/ Partial update. Version-bearing fields: `tags`, `llm_model`. Pass `set_latest_as_default: true` to promote the new version. # Add metadata to a document Source: https://docs.clarifeye.ai/backoffice/documents/add-metadata-to-a-document /api-reference/openapi-full.yaml post /projects/{project_id}/documents/{document_id}/metadata-add/ Add metadata to a document. Accepts **either** a single `{key, value}` pair **or** a list of `{key, value}` pairs in one request. Each 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. # Bulk upload documents Source: https://docs.clarifeye.ai/backoffice/documents/bulk-upload-documents /api-reference/openapi-full.yaml post /projects/{project_id}/documents/bulk-upload/ Upload multiple documents at once. Optionally skip the automatic parsing pipeline. Per-file metadata can be attached at upload time via the `files_metadata` field so documents arrive with their metadata already set (no follow-up `metadata-add` calls needed). # Create a document collection Source: https://docs.clarifeye.ai/backoffice/documents/create-a-document-collection /api-reference/openapi-full.yaml post /projects/{project_id}/document-collections/ Create a collection. The `slug` is derived server-side from `name` (deduplicated per project) and cannot be set by the client. Requires admin permissions. # Delete a document collection Source: https://docs.clarifeye.ai/backoffice/documents/delete-a-document-collection /api-reference/openapi-full.yaml delete /projects/{project_id}/document-collections/{collection_id}/ Delete the collection row. Linked documents keep their metadata and fall back to the virtual "Default" bucket. Requires admin permissions. # Delete document Source: https://docs.clarifeye.ai/backoffice/documents/delete-document /api-reference/openapi-full.yaml delete /projects/{project_id}/documents/{document_id}/ Delete a document from the project. Deletion is performed asynchronously - the document is marked as "deleting" and removed in the background. # Filter documents by metadata values Source: https://docs.clarifeye.ai/backoffice/documents/filter-documents-by-metadata-values /api-reference/openapi-full.yaml post /projects/{project_id}/documents/filter-by-metadata/ 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. # Filter documents by tag values Source: https://docs.clarifeye.ai/backoffice/documents/filter-documents-by-tag-values /api-reference/openapi-full.yaml post /projects/{project_id}/documents/filter-by-tag/ 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. # Get document tags grouped by document Source: https://docs.clarifeye.ai/backoffice/documents/get-document-tags-grouped-by-document /api-reference/openapi-full.yaml get /projects/{project_id}/document-tags-by-document/ 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). # Get metadata values for a key Source: https://docs.clarifeye.ai/backoffice/documents/get-metadata-values-for-a-key /api-reference/openapi-full.yaml get /projects/{project_id}/documents/{document_id}/metadata-values/ Retrieve all values associated with a given metadata key on a document. # List available document metadata Source: https://docs.clarifeye.ai/backoffice/documents/list-available-document-metadata /api-reference/openapi-full.yaml get /projects/{project_id}/available-document-metadata/ 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. # List available document tags Source: https://docs.clarifeye.ai/backoffice/documents/list-available-document-tags /api-reference/openapi-full.yaml get /projects/{project_id}/available-document-tags/ 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). # List document collections Source: https://docs.clarifeye.ai/backoffice/documents/list-document-collections /api-reference/openapi-full.yaml get /projects/{project_id}/document-collections/ List the project's document collections. Available to all project members. # List documents Source: https://docs.clarifeye.ai/backoffice/documents/list-documents /api-reference/openapi-full.yaml get /projects/{project_id}/documents/ List a project's documents (paginated). Supports text search, status filtering, and filtering by collection. # List documents without file data Source: https://docs.clarifeye.ai/backoffice/documents/list-documents-without-file-data /api-reference/openapi-full.yaml get /projects/{project_id}/documents/get-without-file/ Retrieve document metadata without file URLs for faster response times. # Move a document to a collection Source: https://docs.clarifeye.ai/backoffice/documents/move-a-document-to-a-collection /api-reference/openapi-full.yaml post /projects/{project_id}/documents/{document_id}/set-collection/ Move a document into a collection, or out to "Default". Sets the `collection` foreign key and swaps the mirrored `["tag", slug]` pair so retrieval/extraction filters follow the move. Requires project admin permission. # Move multiple documents to a collection Source: https://docs.clarifeye.ai/backoffice/documents/move-multiple-documents-to-a-collection /api-reference/openapi-full.yaml post /projects/{project_id}/documents/bulk-set-collection/ Move up to 200 active documents into a collection, or out to "Default", in one request. Sets the `collection` foreign key and swaps the mirrored `["tag", slug]` pair on each document so retrieval/extraction filters follow the move. Requires project admin permission. # Remove a specific metadata pair Source: https://docs.clarifeye.ai/backoffice/documents/remove-a-specific-metadata-pair /api-reference/openapi-full.yaml post /projects/{project_id}/documents/{document_id}/metadata-remove-pair/ Remove a specific key-value pair from a document's metadata. Both key and value must match exactly for the pair to be removed. # Remove all metadata pairs for a key Source: https://docs.clarifeye.ai/backoffice/documents/remove-all-metadata-pairs-for-a-key /api-reference/openapi-full.yaml post /projects/{project_id}/documents/{document_id}/metadata-remove-key/ Remove all metadata pairs matching the given key from a document, regardless of their values. # Rename a document collection Source: https://docs.clarifeye.ai/backoffice/documents/rename-a-document-collection /api-reference/openapi-full.yaml patch /projects/{project_id}/document-collections/{collection_id}/ Update the collection's `name`. The `slug` is immutable. Requires admin permissions. # Retrieve a document collection Source: https://docs.clarifeye.ai/backoffice/documents/retrieve-a-document-collection /api-reference/openapi-full.yaml get /projects/{project_id}/document-collections/{collection_id}/ # Begin an external MCP OAuth connection Source: https://docs.clarifeye.ai/backoffice/external-mcp/begin-an-external-mcp-oauth-connection /api-reference/openapi-full.yaml post /users/me/mcp-connections/initiate/ Starts the OAuth authorization-code flow for an enabled OAuth MCP server the user can access. Returns the authorization URL for the frontend to open in a popup. Rate limited. # Current user's connection status per enabled server Source: https://docs.clarifeye.ai/backoffice/external-mcp/current-users-connection-status-per-enabled-server /api-reference/openapi-full.yaml get /projects/{project_id}/mcp-servers/connection-status/ Drives the connect banner and empty-state connector prompt. Separate from the job-execution poll path. # List a knowledge store's external MCP servers Source: https://docs.clarifeye.ai/backoffice/external-mcp/list-a-knowledge-stores-external-mcp-servers /api-reference/openapi-full.yaml get /projects/{project_id}/mcp-servers/ Project members can read; only project admins can create/edit. # List my external MCP connections Source: https://docs.clarifeye.ai/backoffice/external-mcp/list-my-external-mcp-connections /api-reference/openapi-full.yaml get /users/me/mcp-connections/ The current user's OAuth connections to external MCP servers, one per distinct server URL, grouped across all knowledge stores the user belongs to. Never returns tokens or client secrets. # Re-authorize an existing MCP connection Source: https://docs.clarifeye.ai/backoffice/external-mcp/re-authorize-an-existing-mcp-connection /api-reference/openapi-full.yaml post /users/me/mcp-connections/{id}/reconnect/ # Re-sync an MCP server's tool catalog (admin) Source: https://docs.clarifeye.ai/backoffice/external-mcp/re-sync-an-mcp-servers-tool-catalog-admin /api-reference/openapi-full.yaml post /projects/{project_id}/mcp-servers/{id}/sync_tools/ Re-fetches the server's tools using the admin's own credential (OAuth) or the shared API key. Newly discovered tools start disabled; removed tools drop out of the allowlist. Rate limited. # Register an external MCP server (admin) Source: https://docs.clarifeye.ai/backoffice/external-mcp/register-an-external-mcp-server-admin /api-reference/openapi-full.yaml post /projects/{project_id}/mcp-servers/ Creates a server and synchronously syncs its tool catalog (all tools start disabled). ``url`` and ``auth_mode`` are immutable after creation. The ``oauth_client_secret`` is write-only. API keys are per-user (set on the account endpoint), never on the server. # Remove an external MCP server (admin) Source: https://docs.clarifeye.ai/backoffice/external-mcp/remove-an-external-mcp-server-admin /api-reference/openapi-full.yaml delete /projects/{project_id}/mcp-servers/{id}/ # Revoke an external MCP connection Source: https://docs.clarifeye.ai/backoffice/external-mcp/revoke-an-external-mcp-connection /api-reference/openapi-full.yaml post /users/me/mcp-connections/{id}/revoke/ Best-effort remote token revocation, removes the Anthropic vault credential, and marks the connection revoked. # Set the current user's API key for an api_key MCP server Source: https://docs.clarifeye.ai/backoffice/external-mcp/set-the-current-users-api-key-for-an-api_key-mcp-server /api-reference/openapi-full.yaml post /users/me/mcp-connections/set-api-key/ Stores the user's own API key for an enabled api_key server in one of their knowledge stores (encrypted at rest) and pushes it to their vault. Credentials are per-user; there is no shared store-level key. # Update an external MCP server (admin) Source: https://docs.clarifeye.ai/backoffice/external-mcp/update-an-external-mcp-server-admin /api-reference/openapi-full.yaml patch /projects/{project_id}/mcp-servers/{id}/ Edit name, enable/disable, tool allowlist, or rotate the OAuth client secret. ``url`` and ``auth_mode`` are immutable. # Get extraction flow statistics Source: https://docs.clarifeye.ai/backoffice/extraction-flows/get-extraction-flow-statistics /api-reference/openapi-full.yaml post /projects/{project_id}/extraction-flows/{flow_id}/node-stats/ Dry-run cache simulation of the flow — returns, per DAG node, how many inputs would be reused from cache vs. recomputed, without actually executing any extraction. Useful to preview the cost/impact of a run. # List extraction flows Source: https://docs.clarifeye.ai/backoffice/extraction-flows/list-extraction-flows /api-reference/openapi-full.yaml get /projects/{project_id}/extraction-flows/ List all extraction flows for the project, ordered by most recently updated. # Publish an extraction flow Source: https://docs.clarifeye.ai/backoffice/extraction-flows/publish-an-extraction-flow /api-reference/openapi-full.yaml post /projects/{project_id}/extraction-flows/{flow_id}/publish/ Queue a pipeline run that publishes previously-extracted data to the downstream indexes without re-running extraction. > **Only valid for flows whose `publish_mode` is `manual_publish`.** > For `auto_publish` flows, publishing happens automatically at the end > of each `run-sync`, so calling this endpoint is unnecessary. # Run an extraction flow Source: https://docs.clarifeye.ai/backoffice/extraction-flows/run-an-extraction-flow /api-reference/openapi-full.yaml post /projects/{project_id}/extraction-flows/{flow_id}/run-sync/ Queue a pipeline run that executes the flow's DAG across the given documents (or all project documents if `document_ids` is omitted). Returns the `pipeline_run_id` you can poll to track progress. # Update an extraction flow Source: https://docs.clarifeye.ai/backoffice/extraction-flows/update-an-extraction-flow /api-reference/openapi-full.yaml patch /projects/{project_id}/extraction-flows/{flow_id}/ Partially update an extraction flow. Common uses are switching the **publish mode** and editing the **DAG** (adding, modifying or removing nodes). **Publish modes:** - `auto_publish` — Each successful flow run automatically publishes the extracted data. No separate publish step is required. - `manual_publish` — Flow runs only compute and persist extracted data in the warehouse. Publishing to downstream indexes must be triggered explicitly via the `publish` action. Use this when you want to review the results of a run before exposing them to search / agents. **Editing the DAG:** Send the full updated `dag` object — the backend replaces the stored DAG on every PATCH. There is no node-level patch endpoint. When removing a node, also strip its name from any downstream `depends_on` arrays. `inputs` and `outputs` may be sent empty; the backend resolves them automatically. # Delete feedback Source: https://docs.clarifeye.ai/backoffice/feedback/delete-feedback /api-reference/openapi-full.yaml delete /projects/{project_id}/feedbacks/{feedback_id}/ Remove feedback. **Access Control:** - Admins can delete any feedback - Regular users can only delete feedback they submitted **Impersonation:** - When using impersonation, the ownership check is performed against the impersonated user - This allows deleting feedback submitted by the impersonated user # Get feedback counts by status Source: https://docs.clarifeye.ai/backoffice/feedback/get-feedback-counts-by-status /api-reference/openapi-full.yaml get /projects/{project_id}/feedbacks/counts/ Retrieve comprehensive counts of feedbacks split by status, conversation grouping, and ungrouped feedbacks. **Access Control:** - Admins see counts for all feedback in the project - Regular users see counts only for feedback they submitted **Impersonation:** - When using impersonation, returns counts for feedback submitted by the impersonated user # Get feedbacks grouped by conversation Source: https://docs.clarifeye.ai/backoffice/feedback/get-feedbacks-grouped-by-conversation /api-reference/openapi-full.yaml get /projects/{project_id}/feedbacks/grouped_by_conversation/ Retrieve feedbacks grouped by their associated playground conversation with unified pagination and sorting. **Access Control:** - Admins see all feedback in the project - Regular users see only feedback they submitted **Grouping Logic:** - Feedbacks are grouped by their `conversation` field (FK to PlaygroundConversation) - Conversation groups and ungrouped feedbacks are returned in a single flat array - Ungrouped feedbacks appear as single-item groups with `conversation_id: null` - Each group includes status counts and all associated feedbacks **Pagination:** - Paginates across the unified list of conversation groups and ungrouped feedbacks - Use `limit` and `offset` parameters to page through results - The `count` field reflects the total number of displayable groups (conversations + ungrouped) **Status Filtering:** - `status=to_review`: Groups with ANY unreviewed feedback - `status=reviewed`: Groups where ALL feedbacks are reviewed - No status filter: All groups **Sorting:** - All groups are sorted together by the most recent feedback update time - With `status=to_review`: Sorted by the most recent "to_review" feedback update - With `status=reviewed`: Sorted by the most recent "reviewed" feedback update - Without status filter: Sorted by the most recent feedback update (any status) - Feedbacks within each group are ordered by most recently updated first **Impersonation:** - When using impersonation, returns feedback submitted by the impersonated user # List feedback Source: https://docs.clarifeye.ai/backoffice/feedback/list-feedback /api-reference/openapi-full.yaml get /projects/{project_id}/feedbacks/ Retrieve all feedback for a project with optional filtering. **Access Control:** - Admins see all feedback in the project - Regular users see only feedback they submitted **Impersonation:** - When using impersonation, returns feedback submitted by the impersonated user **Sorting:** - Results are ordered by most recently updated first (`updated_at` field) **Note:** For grouped views by conversation, use `/projects/{project_id}/feedbacks/grouped_by_conversation/` # Mark all feedbacks in a conversation as reviewed Source: https://docs.clarifeye.ai/backoffice/feedback/mark-all-feedbacks-in-a-conversation-as-reviewed /api-reference/openapi-full.yaml post /projects/{project_id}/feedbacks/mark_conversation_reviewed/ Update the status of all feedbacks associated with a specific conversation to "reviewed". **Access Control:** - Admins can update all feedbacks in the project - Regular users can only update feedback they submitted **Impersonation:** - When using impersonation, only updates feedback submitted by the impersonated user # Submit feedback Source: https://docs.clarifeye.ai/backoffice/feedback/submit-feedback /api-reference/openapi-full.yaml post /projects/{project_id}/feedbacks/ 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 # Update feedback status Source: https://docs.clarifeye.ai/backoffice/feedback/update-feedback-status /api-reference/openapi-full.yaml patch /projects/{project_id}/feedbacks/{feedback_id}/ Mark feedback as reviewed or update other fields. **Access Control:** - Admins can update any feedback - Regular users can only update feedback they submitted **Impersonation:** - When using impersonation, the ownership check is performed against the impersonated user - This allows updating feedback submitted by the impersonated user # Create imported object extractor Source: https://docs.clarifeye.ai/backoffice/imported-object-extractors/create-imported-object-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/imported-object-extractors/ Create an `ImportedObjectExtractor` — holds objects imported from an external system (rather than extracted by an LLM). # Delete imported object extractor Source: https://docs.clarifeye.ai/backoffice/imported-object-extractors/delete-imported-object-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/imported-object-extractors/{extractor_id}/ Delete the `ImportedObjectExtractor`. The related `imported_objects_table` is cleaned up on cascade. # List imported object extractors Source: https://docs.clarifeye.ai/backoffice/imported-object-extractors/list-imported-object-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/imported-object-extractors/ # Retrieve imported object extractor Source: https://docs.clarifeye.ai/backoffice/imported-object-extractors/retrieve-imported-object-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/imported-object-extractors/{extractor_id}/ # Update imported object extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/imported-object-extractors/update-imported-object-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/imported-object-extractors/{extractor_id}/ Partial update. Version-bearing field: `extractable_pydantic_class`. Pass `set_latest_as_default: true` to promote the new version. # Create an interview draft Source: https://docs.clarifeye.ai/backoffice/interviews/create-an-interview-draft /api-reference/openapi-full.yaml post /projects/{project_id}/interview-drafts/ Save a draft of an interview assignment. **Admin only.** A draft holds the whole assignment payload but creates no interviews and sends nothing — it only becomes real interviews when a human sends it via the assign endpoint (passing `draft_id`). Validation is deliberately permissive: every field is optional, recipients may be stale, and the schedule may be in the past — the real rules apply at send time. This is the endpoint LLM tools use, precisely because it cannot trigger email. When a `topic` is provided, a short title is generated from it and returned as `name` (regenerated whenever the topic changes on update). # Create and assign interviews Source: https://docs.clarifeye.ai/backoffice/interviews/create-and-assign-interviews /api-reference/openapi-full.yaml post /projects/{project_id}/interviews/assign/ Create and assign one interview per assignee. **Admin only.** Provide existing project members via `assignee_ids` and/or new people to invite via `invite_emails` (at least one is required). Invitees are added as non-admin Contributors. A separate interview is created for each assignee and the response is the list of created interviews. `write_scope` defaults to `local`. A `global` write scope requires every assignee to already be a project admin and cannot be combined with `invite_emails`. `scheduled_send_at` delays only the invitation email — interviews are created and visible in-app immediately. `reminders` configures automatic chase emails that run until the interview is completed, the cap is reached, or an admin stops them. `draft_id` marks this send as consuming a saved interview draft: the draft is deleted in the same transaction, and its stored title is reused when the sent topic still matches the draft's. `interview_type: "guided-interview"` creates guided (multi-topic deep-dive) conversations structured by `topics` — an ordered list of `{title, description, skill_id}` seeded as conversation-scoped topics at send time (at least one is required). With a `draft_id`, the draft's type is authoritative (immutable), while payload `topics` override the draft's saved list — the form may hold unsaved edits at send time. Guided sends reject `questions`: the topics structure the conversation, so must-cover points belong in the `topic` (focus) text. `campaign_id` / `campaign_name` group the created interviews under an interview campaign (e.g. a workshop wave). `campaign_id` picks an existing campaign; `campaign_name` reuses the project's campaign with that name (case-insensitive) or creates it. When both are absent the send falls back to the consumed draft's saved campaign; an explicit `campaign_id: null` clears a drafted campaign. # Delete an interview draft Source: https://docs.clarifeye.ai/backoffice/interviews/delete-an-interview-draft /api-reference/openapi-full.yaml delete /projects/{project_id}/interview-drafts/{draft_id}/ Discard a saved draft. **Admin only.** Nothing was sent, so deleting a draft has no side effects. Sending a draft (assign with `draft_id`) deletes it automatically. # Download all interview files as a zip Source: https://docs.clarifeye.ai/backoffice/interviews/download-all-interview-files-as-a-zip /api-reference/openapi-full.yaml get /projects/{project_id}/coach-conversations/{coach_conversation_id}/local-documents/download-all/ Download every file uploaded during the interview as a single zip archive (entries ordered by upload time; duplicate filenames are suffixed). Non-admins can only download files from interviews assigned to them or that they created. Returns 404 when the interview has no files. # Duplicate an interview as a draft Source: https://docs.clarifeye.ai/backoffice/interviews/duplicate-an-interview-as-a-draft /api-reference/openapi-full.yaml post /projects/{project_id}/interviews/{interview_id}/duplicate-as-draft/ Duplicate one interview into a fresh, unsent draft. **Admin only.** The draft copies the interview's content and send settings (focus topic, questions or guided topics, write scope, focused mode, language, custom message, reminder settings, campaign); recipients, transcript, schedule, and lifecycle state are not copied — pick recipients on the draft and send it via the assign endpoint. Nothing is sent by this call. Only standard and guided interviews can be duplicated — imported transcripts return 400. # Duplicate an interview draft Source: https://docs.clarifeye.ai/backoffice/interviews/duplicate-an-interview-draft /api-reference/openapi-full.yaml post /projects/{project_id}/interview-drafts/{draft_id}/clone/ Duplicate a saved draft verbatim into a new draft. **Admin only.** Every field is copied as-is — including recipients, schedule, reminder settings, and campaign; the name is copied rather than regenerated since the topic is identical. Nothing is sent by this call. # Import an external interview transcript Source: https://docs.clarifeye.ai/backoffice/interviews/import-an-external-interview-transcript /api-reference/openapi-full.yaml post /projects/{project_id}/interviews/import-transcript/ Import the transcript of an interview recorded outside the platform (e.g. a Granola/Teams/Zoom export). **Admin only.** Creates a read-only interview (type "imported-interview") holding the raw text and enqueues an async parse that turns it into speaker-labeled `chat_history` messages (each carrying a `speaker` name) plus inferred metadata. The response returns immediately with `import_info.import_status = "parsing"`; poll the interview detail endpoint until it is "ready" (`status` becomes "completed") before reading the transcript. All metadata fields are optional — anything omitted is inferred from the transcript; importer-supplied values always win. # List assignable users Source: https://docs.clarifeye.ai/backoffice/interviews/list-assignable-users /api-reference/openapi-full.yaml get /projects/{project_id}/interviews/assignable-users/ List project members who can be assigned an interview (tech/contributor profiles and pending tech/contributor invites), flagging admins. **Admin only.** # List interview campaigns Source: https://docs.clarifeye.ai/backoffice/interviews/list-interview-campaigns /api-reference/openapi-full.yaml get /projects/{project_id}/interview-campaigns/ List the project's interview campaigns with their progress aggregates, most recently created first. **Admin only** — the response covers every interview in each campaign, including ones the caller cannot otherwise see. Campaigns are created lazily by passing `campaign_name` when drafting or assigning interviews; there is no create endpoint. To list the interviews of one campaign, filter the conversations list with `?campaign=` (or `?campaign=none` for the interviews that belong to no campaign). # List interview drafts Source: https://docs.clarifeye.ai/backoffice/interviews/list-interview-drafts /api-reference/openapi-full.yaml get /projects/{project_id}/interview-drafts/ List the project's saved-but-unsent interview drafts, most recently updated first. **Admin only** (like everything pre-send). # List interviews Source: https://docs.clarifeye.ai/backoffice/interviews/list-interviews /api-reference/openapi-full.yaml get /projects/{project_id}/interviews/ Retrieve interviews for a project. - Admins see all interviews in the project. - Other members see only interviews assigned to them or that they created. Results are ordered newest first, with interviews of the same campaign kept contiguous (a campaign sorts by its own creation date, a campaign-less interview by its own) — which is what lets clients render collapsible campaign groups across pages. # Remind every unfinished interview in a campaign Source: https://docs.clarifeye.ai/backoffice/interviews/remind-every-unfinished-interview-in-a-campaign /api-reference/openapi-full.yaml post /projects/{project_id}/interview-campaigns/{campaign_id}/remind-all/ Send a reminder (or a "finish your interview" nudge for in-progress ones) to the assignee of each unfinished interview in the campaign. **Admin only.** Ineligible interviews are skipped rather than failing the batch: completed interviews, imported transcripts, interviews with no assignee, interviews assigned to the caller, and interviews whose scheduled invitation has not been sent yet (use the interview's send-now action for those). # Rename an interview campaign Source: https://docs.clarifeye.ai/backoffice/interviews/rename-an-interview-campaign /api-reference/openapi-full.yaml patch /projects/{project_id}/interview-campaigns/{campaign_id}/ Rename a campaign. **Admin only.** `name` is the only writable field — campaigns cannot be created or deleted through the API. Names are unique per project, case-insensitively; a clash returns 400. # Retrieve an interview campaign Source: https://docs.clarifeye.ai/backoffice/interviews/retrieve-an-interview-campaign /api-reference/openapi-full.yaml get /projects/{project_id}/interview-campaigns/{campaign_id}/ Retrieve one campaign with its progress aggregates. **Admin only.** # Retrieve an interview draft Source: https://docs.clarifeye.ai/backoffice/interviews/retrieve-an-interview-draft /api-reference/openapi-full.yaml get /projects/{project_id}/interview-drafts/{draft_id}/ Retrieve one saved draft. **Admin only.** # Retrieve interview content Source: https://docs.clarifeye.ai/backoffice/interviews/retrieve-interview-content /api-reference/openapi-full.yaml get /projects/{project_id}/interviews/{interview_id}/ Retrieve a single interview with its full content, including the complete `chat_history` transcript and `chat_memory`. Non-admins can only retrieve interviews assigned to them or that they created; admins can retrieve any interview in the project. # Retry a failed transcript import Source: https://docs.clarifeye.ai/backoffice/interviews/retry-a-failed-transcript-import /api-reference/openapi-full.yaml post /projects/{project_id}/interviews/{interview_id}/retry-import/ Re-run the async parse of an imported transcript. **Admin only.** Allowed when the import failed, or when it has been stuck in "parsing" long enough (~15 minutes) that the worker evidently died. Returns 400 for other states and for non-imported interviews. # Send a scheduled invitation now Source: https://docs.clarifeye.ai/backoffice/interviews/send-a-scheduled-invitation-now /api-reference/openapi-full.yaml post /projects/{project_id}/interviews/{interview_id}/send-now/ Send a scheduled-but-unsent interview invitation immediately, skipping the remaining wait on `scheduled_send_at`, and start the reminder clock. **Admin or assigner only.** Returns 400 when the interview is not an interview, has already been started, or its invitation was already sent. # Stop automatic reminders Source: https://docs.clarifeye.ai/backoffice/interviews/stop-automatic-reminders /api-reference/openapi-full.yaml post /projects/{project_id}/interviews/{interview_id}/stop-reminders/ Permanently stop automatic reminder emails for one interview. **Admin or assigner only.** Manual reminders stay available; reminders also stop on completion or deletion. Returns 400 when the interview has no reminder schedule. # Update an interview Source: https://docs.clarifeye.ai/backoffice/interviews/update-an-interview /api-reference/openapi-full.yaml patch /projects/{project_id}/interviews/{interview_id}/ Partially update an interview's writable fields — most usefully `name` (rename) and `campaign_id` (move the interview to another campaign of the project, or null to remove it from its campaign, so past interviews can be re-bucketed retroactively). Lifecycle and transcript fields are read-only. # Update an interview draft Source: https://docs.clarifeye.ai/backoffice/interviews/update-an-interview-draft /api-reference/openapi-full.yaml patch /projects/{project_id}/interview-drafts/{draft_id}/ Partially update a saved draft. **Admin only.** Changing the topic regenerates the draft's `name`; clearing it clears the name. # Cancel invitation Source: https://docs.clarifeye.ai/backoffice/invitations/cancel-invitation /api-reference/openapi-full.yaml delete /projects/{project_id}/invites/{invite_id}/ Cancel a pending invitation. Only pending invitations can be cancelled. # Invite user to project Source: https://docs.clarifeye.ai/backoffice/invitations/invite-user-to-project /api-reference/openapi-full.yaml post /projects/{project_id}/invites/invite/ Invite a user to join the project. - For new users (not registered): Creates a pending invite and sends an email. - For existing users: Automatically accepts the invite and sends a notification. # List invitations Source: https://docs.clarifeye.ai/backoffice/invitations/list-invitations /api-reference/openapi-full.yaml get /projects/{project_id}/invites/ Retrieve all invitations for a project with optional filtering by status. # Delete a notification Source: https://docs.clarifeye.ai/backoffice/notifications/delete-a-notification /api-reference/openapi-full.yaml delete /projects/{project_id}/notifications/{notification_id}/ Delete a single notification for the effective user. **Impersonation:** When using the `X-Impersonate-Email` header, deletes the notification for the target user. # Delete all read notifications Source: https://docs.clarifeye.ai/backoffice/notifications/delete-all-read-notifications /api-reference/openapi-full.yaml post /projects/{project_id}/notifications/delete-read/ Delete all read project notifications for the effective user. **Impersonation:** When using the `X-Impersonate-Email` header, deletes all read notifications for the target user. # List project notifications Source: https://docs.clarifeye.ai/backoffice/notifications/list-project-notifications /api-reference/openapi-full.yaml get /projects/{project_id}/notifications/ List notifications for the effective user (authenticated user or impersonated user). **Filtering:** - Only PROJECT-scoped notifications are returned (not account-level) - Returns all unread notifications plus read notifications from the last 7 days - Optionally filter by status using the `status` query parameter **Impersonation:** When using the `X-Impersonate-Email` header, returns notifications for the target user instead of the authenticated user. # Mark all notifications as read Source: https://docs.clarifeye.ai/backoffice/notifications/mark-all-notifications-as-read /api-reference/openapi-full.yaml post /projects/{project_id}/notifications/mark-all-as-read/ Mark all unread project notifications as read for the effective user. **Impersonation:** When using the `X-Impersonate-Email` header, marks all notifications as read for the target user. # Mark notification as read Source: https://docs.clarifeye.ai/backoffice/notifications/mark-notification-as-read /api-reference/openapi-full.yaml post /projects/{project_id}/notifications/{notification_id}/mark-as-read/ Mark a single notification as read for the effective user. **Impersonation:** When using the `X-Impersonate-Email` header, marks the notification as read for the target user. # Mark notification as unread Source: https://docs.clarifeye.ai/backoffice/notifications/mark-notification-as-unread /api-reference/openapi-full.yaml post /projects/{project_id}/notifications/{notification_id}/mark-as-unread/ Mark a single notification as unread for the effective user. **Impersonation:** When using the `X-Impersonate-Email` header, marks the notification as unread for the target user. # Retrieve a notification Source: https://docs.clarifeye.ai/backoffice/notifications/retrieve-a-notification /api-reference/openapi-full.yaml get /projects/{project_id}/notifications/{notification_id}/ Retrieve details of a single notification for the effective user. **Impersonation:** When using the `X-Impersonate-Email` header, retrieves the notification for the target user. # Create object alerts extractor Source: https://docs.clarifeye.ai/backoffice/object-alerts-extractors/create-object-alerts-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/object-alerts-extractors/ Create an `ObjectAlertsExtractor` — runs LLM-based alerts over already-extracted object rows. # Delete object alerts extractor Source: https://docs.clarifeye.ai/backoffice/object-alerts-extractors/delete-object-alerts-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/object-alerts-extractors/{extractor_id}/ Delete the `ObjectAlertsExtractor`. The related `alerts_table` is cleaned up on cascade. # List object alerts extractors Source: https://docs.clarifeye.ai/backoffice/object-alerts-extractors/list-object-alerts-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/object-alerts-extractors/ # Retrieve object alerts extractor Source: https://docs.clarifeye.ai/backoffice/object-alerts-extractors/retrieve-object-alerts-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/object-alerts-extractors/{extractor_id}/ # Update object alerts extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/object-alerts-extractors/update-object-alerts-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/object-alerts-extractors/{extractor_id}/ Partial update. Version-bearing fields: `instructions`, `llm_model`. Pass `set_latest_as_default: true` to promote the new version. # Create object extractor Source: https://docs.clarifeye.ai/backoffice/object-extractors/create-object-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/object-extractors/ Create an `ObjectExtractor`. A first `ObjectExtractorVersion` is created automatically and marked as default. Pass `import_mode: true` to skip auto-version creation (bulk imports only). Required field: `name`. # Delete object extractor Source: https://docs.clarifeye.ai/backoffice/object-extractors/delete-object-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/object-extractors/{extractor_id}/ Delete the `ObjectExtractor`. Related warehouse tables (`extracted_objects_table`, `alerts_table`) are cleaned up on cascade. # List object extractors Source: https://docs.clarifeye.ai/backoffice/object-extractors/list-object-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/object-extractors/ List all `ObjectExtractor` rows in the project, newest first. # Retrieve object extractor Source: https://docs.clarifeye.ai/backoffice/object-extractors/retrieve-object-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/object-extractors/{extractor_id}/ # Update object extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/object-extractors/update-object-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/object-extractors/{extractor_id}/ Partial update of an `ObjectExtractor`. If any **version-bearing** field differs from the latest version, a new `ObjectExtractorVersion` row is created automatically. Version-bearing fields: `extractable_pydantic_class`, `extraction_prompt`, `llm_model`, `add_anchoring_object`, `filtered_on_block_types`, `block_types`, `extract_single_object`, `block_grouping_config`, `alerts_additional_instructions`. Pass `set_latest_as_default: true` to promote the newly created version to the default in the same call. # Delete an API key (superuser only) Source: https://docs.clarifeye.ai/backoffice/organization-api-keys/delete-an-api-key-superuser-only /api-reference/openapi-full.yaml delete /organization-api-keys/{id}/ Permanently deletes the key; it immediately stops authenticating. # Download the full secret (superuser or org admin) Source: https://docs.clarifeye.ai/backoffice/organization-api-keys/download-the-full-secret-superuser-or-org-admin /api-reference/openapi-full.yaml get /organization-api-keys/{id}/reveal/ # List API keys (superuser → all; org admin → own org's keys) Source: https://docs.clarifeye.ai/backoffice/organization-api-keys/list-api-keys-superuser-→-all;-org-admin-→-own-orgs-keys /api-reference/openapi-full.yaml get /organization-api-keys/ # Mint an API key (superuser only) Source: https://docs.clarifeye.ai/backoffice/organization-api-keys/mint-an-api-key-superuser-only /api-reference/openapi-full.yaml post /organization-api-keys/ The full `api_key` is returned ONCE in this response. # Retrieve API key metadata (superuser or org admin) Source: https://docs.clarifeye.ai/backoffice/organization-api-keys/retrieve-api-key-metadata-superuser-or-org-admin /api-reference/openapi-full.yaml get /organization-api-keys/{id}/ # Create parsing extractor Source: https://docs.clarifeye.ai/backoffice/parsing-extractors/create-parsing-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/parsing-extractors/ Create a `ParsingExtractor`. A first version is created automatically and marked as default. # Delete parsing extractor Source: https://docs.clarifeye.ai/backoffice/parsing-extractors/delete-parsing-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/parsing-extractors/{extractor_id}/ Delete the `ParsingExtractor`. Related warehouse tables (`extracted_parsed_documents_table`, `extracted_blocks_table`) are cleaned up on cascade. # List parsing extractors Source: https://docs.clarifeye.ai/backoffice/parsing-extractors/list-parsing-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/parsing-extractors/ # Retrieve parsing extractor Source: https://docs.clarifeye.ai/backoffice/parsing-extractors/retrieve-parsing-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/parsing-extractors/{extractor_id}/ # Update parsing extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/parsing-extractors/update-parsing-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/parsing-extractors/{extractor_id}/ Partial update. Version-bearing fields: `reducto_parsing_options`, `llm_model`, `use_fast_parsing_for_pdfs`. Pass `set_latest_as_default: true` to promote the new version. # Abort a pipeline run Source: https://docs.clarifeye.ai/backoffice/pipeline-runs/abort-a-pipeline-run /api-reference/openapi-full.yaml post /projects/{project_id}/pipeline-runs/{pipeline_run_id}/abort/ Cancel a pipeline run that is `pending` or `running`. The run and any of its non-terminal steps transition to `aborted`. Aborting an already-terminal run (`completed`, `completed_with_warnings`, `failed`, or `aborted`) is a no-op. # Get pipeline run details and status Source: https://docs.clarifeye.ai/backoffice/pipeline-runs/get-pipeline-run-details-and-status /api-reference/openapi-full.yaml get /projects/{project_id}/pipeline-runs/{pipeline_run_id}/ Retrieve the full details of a single pipeline run, including its current `status`, the list of executed steps with their per-step status, and the aggregated `raw_logs` produced during execution. Poll this endpoint to track the progress of a run started via an extraction flow `run-sync` or `publish` call. A run is in a terminal state when `status` is one of `completed`, `completed_with_warnings`, `failed`, or `aborted`. # List pipeline runs Source: https://docs.clarifeye.ai/backoffice/pipeline-runs/list-pipeline-runs /api-reference/openapi-full.yaml get /projects/{project_id}/pipeline-runs/ List all pipeline runs in the project, ordered by creation date (most recent first). Use this to discover the `id` of a run returned by an extraction flow `run-sync` / `publish` call, or to monitor recent activity. The list response uses a lightweight serializer that omits the very large `chunk_ids` / `document_ids` arrays and truncates `raw_logs` to the most recent entries. Fetch a single run via the detail endpoint to get the full payload. # Get warehouse tags and object schema Source: https://docs.clarifeye.ai/backoffice/projects/get-warehouse-tags-and-object-schema /api-reference/openapi-full.yaml get /projects/{project_id}/library-tags-objects/ Returns markdown sections `tag_hierarchies`, `document_tags`, and `knowledge_graph_objects` for retrieval filtering. # Home dashboard summary Source: https://docs.clarifeye.ai/backoffice/projects/home-dashboard-summary /api-reference/openapi-full.yaml get /projects/{project_id}/home-summary/ Everything the Standard-interface Home dashboard needs in one call: document count and last-added timestamp, plus the caller's open (pending or in-progress) interviews. For project admins the response additionally includes the team's pending interviews and the count of feedbacks awaiting review; these fields are omitted entirely for non-admin members. Available to all project members. # List knowledge artifact catalog Source: https://docs.clarifeye.ai/backoffice/projects/list-knowledge-artifact-catalog /api-reference/openapi-full.yaml get /projects/{project_id}/list-knowledge/ Catalog overview for a knowledge store: `cohesion_guide`, `document_count` (number of active documents in the library), plus `artifacts[]` (one row per in-scope artifact with slug, title, semantic_type, technical_type, group, purpose, and either full LIST `content` or a LIST `content_overview` summary). Knowledge Store tags/objects are served separately by `library-tags-objects`. # List knowledge changelog entries Source: https://docs.clarifeye.ai/backoffice/projects/list-knowledge-changelog-entries /api-reference/openapi-full.yaml get /projects/{project_id}/knowledge-changelog/ List the project's knowledge changelog entries, most recent first. Each entry records a change to the project's knowledge (artifact edits, API ontology/playbook changes, document uploads/syncs). Read-only. Admin-only: the feed aggregates edits by all project members, so it requires CAN_PERFORM_ADMIN_ACTIONS. # Read or edit a design_template_list catalog artifact Source: https://docs.clarifeye.ai/backoffice/projects/read-or-edit-a-design_template_list-catalog-artifact /api-reference/openapi-full.yaml post /projects/{project_id}/read-write-design-template-list-artifact/ Invoke the design_template_list artifact tool. Body must include `slug` plus tool kwargs (`action=list|get|upsert|delete`, …). Reads require view permission; writes require admin. # Read or edit a markdown catalog artifact Source: https://docs.clarifeye.ai/backoffice/projects/read-or-edit-a-markdown-catalog-artifact /api-reference/openapi-full.yaml post /projects/{project_id}/read-write-markdown-artifact/ Invoke the markdown artifact tool. Body must include `slug` (in-scope markdown artifact) plus tool kwargs (`action=get|edit`, …). Reads require view permission; writes require admin. # Read or edit a mental_map catalog artifact Source: https://docs.clarifeye.ai/backoffice/projects/read-or-edit-a-mental_map-catalog-artifact /api-reference/openapi-full.yaml post /projects/{project_id}/read-write-mental-map-artifact/ Invoke the mental_map artifact tool. Body must include `slug` plus tool kwargs (`action=get`, `changes`, …). Reads require view permission; writes require admin. # Read or edit a playbook_list catalog artifact Source: https://docs.clarifeye.ai/backoffice/projects/read-or-edit-a-playbook_list-catalog-artifact /api-reference/openapi-full.yaml post /projects/{project_id}/read-write-playbook-list-artifact/ Invoke the playbook_list artifact tool. Body must include `slug` plus tool kwargs (`action=list|get`, `identifier`, `changes`, …). Reads require view permission; writes require admin. # Read extractor output rows Source: https://docs.clarifeye.ai/backoffice/tables/read-extractor-output-rows /api-reference/openapi-full.yaml post /projects/{project_id}/tables/{table_id}/extractor-table-retrieval/ Read-only retrieval of rows produced by a specific `ExtractorVersion`, joining the warehouse table with `HydrationComputation` records. **What it returns:** rows from `{table_id}` whose `computation_hash` belongs to a `HydrationComputation` with the given `extractor_version_id` (and matching `lineage`, when provided). By default only rows still considered "live" (`deleted IS NULL` on the physical table and the hydration computation not soft-deleted) are returned. **Write operations are not supported** by this endpoint. **Filtering:** Keys are column names with optional Django-style lookups (`__in`, `__gte`, `__lte`, `__isnull`). The frontend-only key `processing_options`, if present, is ignored server-side. **Lineage:** Optional list of `{node_id, computation_hash}` entries that narrows results to a specific upstream computation path in the extraction-flow DAG. Omit to retrieve all rows produced by the extractor version. **Permissions:** `CAN_VIEW_DATA` on the project. # Create tag alerts extractor Source: https://docs.clarifeye.ai/backoffice/tag-alerts-extractors/create-tag-alerts-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/tag-alerts-extractors/ Create a `TagAlertsExtractor` — runs LLM-based alerts over already-extracted tag rows. # Delete tag alerts extractor Source: https://docs.clarifeye.ai/backoffice/tag-alerts-extractors/delete-tag-alerts-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/tag-alerts-extractors/{extractor_id}/ Delete the `TagAlertsExtractor`. The related `alerts_tags_table` is cleaned up on cascade. # List tag alerts extractors Source: https://docs.clarifeye.ai/backoffice/tag-alerts-extractors/list-tag-alerts-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/tag-alerts-extractors/ # Retrieve tag alerts extractor Source: https://docs.clarifeye.ai/backoffice/tag-alerts-extractors/retrieve-tag-alerts-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/tag-alerts-extractors/{extractor_id}/ # Update tag alerts extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/tag-alerts-extractors/update-tag-alerts-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/tag-alerts-extractors/{extractor_id}/ Partial update. Version-bearing fields: `instructions`, `llm_model`. Pass `set_latest_as_default: true` to promote the new version. # Create tag extractor Source: https://docs.clarifeye.ai/backoffice/tag-extractors/create-tag-extractor /api-reference/openapi-full.yaml post /projects/{project_id}/tag-extractors/ Create a `TagExtractor`. A first `TagExtractorVersion` is created automatically and marked as default. Required field: `name`. The `tagging_tree` body is validated against a schema by the backend — `id`, `label`, and `children` keys must be present at every node (children may be empty). # Delete tag extractor Source: https://docs.clarifeye.ai/backoffice/tag-extractors/delete-tag-extractor /api-reference/openapi-full.yaml delete /projects/{project_id}/tag-extractors/{extractor_id}/ Delete the `TagExtractor`. Related warehouse tables (`extracted_tags_table`, `alerts_tags_table`) are cleaned up on cascade. # List tag extractors Source: https://docs.clarifeye.ai/backoffice/tag-extractors/list-tag-extractors /api-reference/openapi-full.yaml get /projects/{project_id}/tag-extractors/ # Retrieve tag extractor Source: https://docs.clarifeye.ai/backoffice/tag-extractors/retrieve-tag-extractor /api-reference/openapi-full.yaml get /projects/{project_id}/tag-extractors/{extractor_id}/ # Update tag extractor (auto-creates new version) Source: https://docs.clarifeye.ai/backoffice/tag-extractors/update-tag-extractor-auto-creates-new-version /api-reference/openapi-full.yaml patch /projects/{project_id}/tag-extractors/{extractor_id}/ Partial update. Version-bearing fields (changing any creates a new `TagExtractorVersion`): `tagging_tree`, `extraction_prompt`, `llm_model`, `enforce_single_tag`, `alerts_additional_instructions`. Pass `set_latest_as_default: true` to promote the new version. # Get tool parameters schema Source: https://docs.clarifeye.ai/backoffice/tools/get-tool-parameters-schema /api-reference/openapi-full.yaml get /projects/{project_id}/tools/{tool_id}/parameters/ Return the JSON schema describing the parameters accepted by [`runTool`](#operation/runTool) for this tool. The schema is a list of parameter specs (`id`, `type`, `description`, `required`, and an optional `default`). The exact list depends on the tool's `tool_type` and configuration — for example a retrieval tool configured with `auto_include` tags exposes an extra `included_tags` parameter. Use the `id` of each entry as the key in the JSON body sent to [`runTool`](#operation/runTool). # List tools Source: https://docs.clarifeye.ai/backoffice/tools/list-tools /api-reference/openapi-full.yaml get /projects/{project_id}/tools/ List all tools available to the project, including tools owned by the project (`category: local`) and tools imported from other projects (`category: imported`). Use the returned `id` together with [`getToolParameters`](#operation/getToolParameters) to discover the request body schema for a given tool, then call [`runTool`](#operation/runTool) to execute it. # Run a tool Source: https://docs.clarifeye.ai/backoffice/tools/run-a-tool /api-reference/openapi-full.yaml post /projects/{project_id}/tools/{tool_id}/run/ Execute a configured tool with provided parameters. The request body varies based on the tool type. Call [`getToolParameters`](#operation/getToolParameters) first to discover the exact parameter schema for a given tool — most retrieval tools accept `query` and `top_k`, but other tool types (e.g. `document_retrieval`) expect different fields. # Pre-create (or re-activate) an org user Source: https://docs.clarifeye.ai/backoffice/user-provisioning/pre-create-or-re-activate-an-org-user /api-reference/openapi-full.yaml post /organizations/{id}/provision-user/ Pre-creates a user bound to this organization, with a verified primary email so a later SSO login links to it automatically. Idempotent: re-provisioning an existing member is a no-op (role/state unchanged). The email's domain must be in the org's `allowed_provisioning_domains`. The API key must belong to the organization in the path. # Read the org's allowed provisioning domains (superuser only) Source: https://docs.clarifeye.ai/backoffice/user-provisioning/read-the-orgs-allowed-provisioning-domains-superuser-only /api-reference/openapi-full.yaml get /organizations/{id}/provisioning-config/ # Remove an org user's membership Source: https://docs.clarifeye.ai/backoffice/user-provisioning/remove-an-org-users-membership /api-reference/openapi-full.yaml post /organizations/{id}/deprovision-user/ Removes the user's membership in this organization. If the user has no remaining memberships they are deactivated (blocking SSO login); otherwise their active organization is re-pointed. Returns `deprovisioned: false` if no such user. The API key must belong to the organization in the path. # Set the org's allowed provisioning domains (superuser only) Source: https://docs.clarifeye.ai/backoffice/user-provisioning/set-the-orgs-allowed-provisioning-domains-superuser-only /api-reference/openapi-full.yaml patch /organizations/{id}/provisioning-config/ # List project users Source: https://docs.clarifeye.ai/backoffice/users/list-project-users /api-reference/openapi-full.yaml get /projects/{project_id}/users/ Retrieve all users with access to a project. # Remove user by email Source: https://docs.clarifeye.ai/backoffice/users/remove-user-by-email /api-reference/openapi-full.yaml post /projects/{project_id}/users/remove-by-email/ Remove a user from the project using their email address. Users cannot remove themselves. # Update user permissions Source: https://docs.clarifeye.ai/backoffice/users/update-user-permissions /api-reference/openapi-full.yaml patch /projects/{project_id}/users/{permission_id}/ Update a user's permissions on the project. # Build & Improve Source: https://docs.clarifeye.ai/guides/build-improve Capture knowledge from your experts and keep it accurate over time. This is where a store gets its content and stays current: you capture knowledge through [interviews](#interviews), consolidate it by [working with Clara](#work-with-clara), and keep it accurate by tracking [signals](#signals). ## Interviews Interviews are the primary way knowledge gets into a store. The most valuable expertise is rarely written down, and the people who hold it rarely have time to document it. So instead of asking them to write, you create an interview on a topic and assign it to the person who knows it best. Clara conducts the conversation asynchronously and in the contributor's own language: she follows up where an answer is thin, moves on where it's solid, and lets people pause and come back whenever it suits them. The Interviews list shows what's outstanding so you can see coverage at a glance. A completed interview is raw input, not finished knowledge. Once answers come in, you consolidate them by [working with Clara](#work-with-clara). The way Clara interviews is shaped once at the organization level through shared context and reusable templates, see [Organization settings](/guides/organization-settings). ## Work with Clara **Work with Clara** is where raw input becomes consolidated knowledge. Captured knowledge is rarely clean: interviews overlap, sources disagree, and important context is missing. In a session, Clara reads new interviews and sources against the current artifacts, surfaces contradictions and gaps rather than guessing, and proposes concrete edits to your [artifacts](/guides/knowledge#artifacts). You steer every change; Clara handles the analysis and the mechanical work. Come here whenever new input needs consolidating, a process has changed, or [signals](#signals) have piled up and you want to fold them in. **Work with Clara vs Task.** Work with Clara *changes* the knowledge (adjusting how you answer an RFP after a policy shift). [Task](/guides/use) *uses* it as it stands today to produce an output (actually filling the RFP). ## Signals A store is only useful while it stays accurate, and accuracy decays. **Signals** are how it keeps up: a signal is anything that should prompt an update, a correction, a gap, drift, or new context worth capturing. A signal can come from anyone, anywhere, the moment they notice the knowledge is out of date or incomplete: from an AI client using the [Clarifeye skill](/guides/mcp), from a [Task](/guides/use), from inside Clarifeye, or from an expert who simply knows a policy changed. They all land in one place so nothing is lost. Signals are an input, not the change itself. Take them into [Work with Clara](#work-with-clara) to turn each one into a concrete update to your [artifacts](/guides/knowledge#artifacts) or [sources](/guides/knowledge#sources); when closing a gap needs fresh expertise, a signal can trigger a new interview. Keeping the store current is the most important ongoing job, so encourage everyone to leave a signal whenever something looks off. # Compliance & Certifications Source: https://docs.clarifeye.ai/guides/compliance Our security standards and compliance certifications ## Security Standards ### SOC 2 Compliance We are SOC 2 compliant. Our latest SOC 2 type II report is available upon request. We uphold rigorous standards to ensure: * Security: Protection against unauthorized access * Availability: System reliability and availability * Processing Integrity: Accurate, timely processing * Confidentiality: Information designated as confidential is protected * Privacy: Personal information is collected, used, retained, disclosed, and disposed of properly ## Infrastructure Security ### Cloud Infrastructure * AWS & GCP Security Standards * Regular security assessments * Automated security monitoring ### Network Security * Access Controls * Multi-factor authentication * Role-based access control ## Security Measures ### Data Security #### Storage * Encrypted storage * Data isolation * Retention policies #### Transfer * Secure API endpoints * Certificate management * Traffic monitoring # Core concepts Source: https://docs.clarifeye.ai/guides/core-concepts The handful of ideas that run through everything else in Clarifeye. Clarifeye captures business knowledge in a structured form and exposes it to AI. Once you know these concepts, the rest of the docs read quickly. ## Organization and knowledge store Clarifeye has two layers. **Organization** is your company's top-level account. Billing, plan, org-wide settings (SSO, security), shared organization context, and interview templates live here, so finance and admin only manage one contract. See [Organization settings](/guides/organization-settings). **Knowledge store** is the working unit inside an organization: one self-contained body of expertise for a team, product, or use case. An organization can hold several. Permissions are scoped to a knowledge store rather than the organization, so the same person can be a contributor in one store and a user in another, while billing rolls up to a single invoice. ## The three areas of a knowledge store Every knowledge store is organized the same way, following the lifecycle of the knowledge inside it. * **Build & Improve** is where knowledge is captured and kept current: **[Interviews](/guides/build-improve#interviews)**, **[Work with Clara](/guides/build-improve#work-with-clara)**, and **[Signals](/guides/build-improve#signals)**. * **Knowledge** is the knowledge itself: **[Artifacts](/guides/knowledge#artifacts)** and **[Sources](/guides/knowledge#sources)**. * **Use** is where you put the knowledge to work: **[Task](/guides/use)**. ## Clara **Clara** is Clarifeye's agent. She runs your interviews and adapts to whoever she's talking to, analyzes what comes in, and works with you to consolidate it into artifacts. Clara does the analysis and the mechanical edits, you stay in control of every change. ## Artifacts Artifacts are the consolidated, trusted representation of your expertise. A knowledge store contains a small set: * **Brief**: a structured document presenting the key elements of the domain expertise. * **Playbooks**: multi-step descriptions of how an expert approaches a specific kind of query or task. * **Mental map**: the domain's ontology, with a **glossary** of domain terms and the **domains, classes, and relations** that group concepts and link them together. * **Corpus description**: what source material the store draws on, how it's organized, and how to navigate it. * **General knowledge**: task-level context that doesn't live in any one document, the conventions and assumptions an expert just knows. See [Artifacts](/guides/knowledge#artifacts). ## Sources Sources are the raw material the store draws on, alongside interviews. They can be **uploaded documents** (PDF, docs, slides, spreadsheets) or **connected sources** pulled from Google Drive, SharePoint, and other connectors. See [Sources](/guides/knowledge#sources). ## Interviews Interviews are the primary way knowledge is captured. You create an interview for a topic and assign it to the teammate who holds that knowledge. Clara conducts it asynchronously and in the contributor's own language. See [Interviews](/guides/build-improve#interviews). ## Signals A signal is anything that should update the knowledge store: a correction, a gap, a piece of drift, or new context. Signals can come from anywhere people use the knowledge (an AI client, a task, or a manual note) and are centralized in one place so nothing is lost. Clara helps turn them into concrete updates, sometimes triggering a new interview. See [Signals](/guides/build-improve#signals). ## The Clarifeye skill and how AI consumes a store Your team installs the **Clarifeye skill** in their AI client. The skill teaches the client how to work with Clarifeye, then uses the Model Context Protocol (MCP) to discover knowledge stores, inspect their knowledge, run retrieval, and raise signals. Each knowledge store behaves like a skill the client can draw on, faithful to what was captured. See [Connect to AI clients](/guides/mcp). ## Task A task applies a knowledge store to real work at a point in time, like filling an RFP or drafting an answer that follows your process. Where **Work with Clara** changes the knowledge, **Task** uses it as it stands today. See [Task](/guides/use). # Create your knowledge store Source: https://docs.clarifeye.ai/guides/create-knowledge-store Create your first knowledge store through a guided conversation with Clara. The first step in Clarifeye is to create a knowledge store. Clara runs a short interview to understand what the store should do, then builds the initial artifacts for you. ## Start a guided session From your knowledge store list, click **Create a new knowledge store**. Clara runs a short interview, around 20 minutes, to gather your inputs and bootstrap the store. She asks about what the store should do and the knowledge it should cover, and you answer in your own words. Keep going to add context: the more you give her, the more useful the first version of the store. ## What Clara builds When you confirm, Clara uses the conversation to draft the initial [artifacts](/guides/knowledge#artifacts): a brief, playbooks, a mental map, a corpus description, and general knowledge. At the point she has enough, she exposes a **first version** of the knowledge store so you can start working with it right away. This first version is a starting point, not a finished store. It captures what Clara could infer from your conversation, and you build it up from there. ## Next steps Once your store exists, fill it with real knowledge and put it to use: * **Capture knowledge.** Create [interviews](/guides/build-improve#interviews) and assign them to the people who hold the expertise, and connect [sources](/guides/knowledge#sources) for material that's already written down. * **Consolidate.** Use [Work with Clara](/guides/build-improve#work-with-clara) to turn what comes in into trusted artifacts. * **Connect and use.** Install the [Clarifeye skill](/guides/mcp) in your AI client, or run a [Task](/guides/use) inside Clarifeye. # External MCPs Source: https://docs.clarifeye.ai/guides/external-mcps Connect external MCP servers as tools Clara can call. A knowledge store isn't limited to what you upload or interview into it. By connecting an external **[MCP](https://modelcontextprotocol.io/)** server, you give Clara access to data and actions that live in other systems. ## Why connect an external MCP There are two moments where this matters: * **[Work with Clara](/guides/build-improve#work-with-clara).** Plug in an external data source or tool so Clara can draw on it while consolidating knowledge, on top of your uploaded documents and connected sources. * **[Use](/guides/use).** In a chat or Task session, an external MCP gives Clarifeye the ability to act on your other applications, not just answer from what it knows. ## How it works External MCPs are configured at the knowledge store level, in the **Settings** tab. You need admin permission to add or edit one. To add a server, provide: * **URL** of the MCP server. * **Client ID** and **Client secret**, if the server requires them. Then choose an authentication method: * **OAuth 2.0** (recommended), the standard flow for MCP servers. * **API key**, for servers that authenticate this way instead. The knowledge store defines the MCP server once; each user then connects with their own credentials. When registering Clarifeye as an OAuth app on the external MCP server, it may ask for a callback (redirect) URL. Use `https:///api/v1/mcp-oauth/callback/`, e.g. `https://eu.app.clarifeye.ai/api/v1/mcp-oauth/callback/` or `https://us.app.clarifeye.ai/api/v1/mcp-oauth/callback/`, replacing the host with your dedicated instance URL if you have one. # Knowledge Source: https://docs.clarifeye.ai/guides/knowledge The consolidated artifacts and the sources behind them. This is the content of a store itself: the consolidated [artifacts](#artifacts) that capture your expertise, and the [sources](#sources) of raw material they're built from. ## Artifacts Artifacts are what a store actually *knows*: the clean, structured output Clara consolidates from your interviews and sources, and what AI clients draw on. You don't usually edit them by hand, you refine them through [Work with Clara](/guides/build-improve#work-with-clara). A store has a small, fixed set: * **Brief**: a structured document presenting the key elements of the domain expertise, the orientation layer that frames everything else. * **Playbooks**: multi-step descriptions of how an expert approaches a kind of query or task, so an AI client follows your method rather than improvising. One per kind of task. * **Mental map**: the domain's ontology, a **glossary** of terms plus the **domains, classes, and relations** that link them, so everyone means the same thing by the same word. * **Corpus description**: what source material the store draws on, how it's organized, and how to navigate it. * **General knowledge**: the conventions and assumptions an expert just knows, the unwritten context that doesn't live in any one document. When an AI client consumes the store through the [Clarifeye skill](/guides/mcp), these artifacts guide its answers. Keeping them accurate, through [Work with Clara](/guides/build-improve#work-with-clara) and [signals](/guides/build-improve#signals), is what keeps the store trustworthy. ## Sources Sources are the written material behind a store. Alongside [interviews](/guides/build-improve#interviews), they're the raw input Clara consolidates into artifacts: interviews capture what's in people's heads, sources capture what's already written down. They come in two kinds: * **Uploaded documents**: PDFs, docs, slides, and spreadsheets you have on hand. * **Connected sources**: content pulled from Google Drive, SharePoint, and other connectors, kept in sync as it changes. Sources aren't consumed raw, Clarifeye processes them so the knowledge inside becomes retrievable. An out-of-date source is itself a [signal](/guides/build-improve#signals) worth raising, and retiring a source that no longer applies matters as much as adding new ones. # Connect to a Light LLM Gateway Source: https://docs.clarifeye.ai/guides/llm-gateway Route Clarifeye's LLM and agentic calls through your own LiteLLM gateway, one model at a time. Gateway routing is not available on all plans. Contact us at `support@clarifeye.ai` to activate the feature and plug in your LiteLLM gateway endpoint for your organization. Instead of calling model providers (OpenAI, Anthropic, Gemini, Mistral) directly, Clarifeye can send its LLM and agentic calls through an OpenAI-compatible **LiteLLM gateway** that you or your operator control. This lets you centralize provider keys, spend, logging, and access policy in one place, while Clarifeye keeps working exactly as before. ## What can be routed Once the gateway is enabled for your instance, you opt in **per model** — there is no global switch. Any model that Clarifeye lets you name can go through the gateway, including: * The **Playground** assistant (chat, agentic tool use, and playbook execution). * **Extractors**: object extraction, tag extraction, and document-tag extraction. Models you leave unprefixed keep calling their provider directly, so you can move one extractor or one Playground agent onto the gateway without touching the rest. ## Set the model name You choose the gateway by the value you type into the **model field** — the same field where you'd normally enter a model such as `gpt-5` or `anthropic/claude-opus-4-8`. To route a model through the gateway, prefix its name with `lite-llm-gateway/`: ``` lite-llm-gateway// ``` Clarifeye strips the `lite-llm-gateway/` prefix and passes the remainder (`/`) to the gateway verbatim, so it must match a model your gateway is configured to serve. For reasoning models, add a reasoning-effort suffix after a colon (`:low`, `:medium`, `:high`), exactly as you would without the gateway: ``` lite-llm-gateway//: ``` ## Examples | Provider | Direct model name | Through the gateway | | --------- | ------------------------------ | ----------------------------------------------- | | OpenAI | `gpt-5.4` | `lite-llm-gateway/openai/gpt-5.4` | | Anthropic | `anthropic/claude-opus-4-8` | `lite-llm-gateway/anthropic/claude-opus-4-8` | | Gemini | `gemini/gemini-2.5-pro` | `lite-llm-gateway/gemini/gemini-2.5-pro` | | Mistral | `mistral/mistral-large-latest` | `lite-llm-gateway/mistral/mistral-large-latest` | With a reasoning-effort suffix: ``` lite-llm-gateway/openai/gpt-5:medium lite-llm-gateway/openai/gpt-5:high ``` Whitespace around the value is ignored, so a stray leading or trailing space won't accidentally bypass gateway routing. # Connect to AI clients Source: https://docs.clarifeye.ai/guides/mcp Bring your knowledge stores into Claude, ChatGPT, Copilot, or any custom client. Running a [Task](/guides/use) inside Clarifeye is one way to use a store. The other is to bring your knowledge into the AI client your team already works in, so they can apply it without leaving their tools. That's what the **Clarifeye skill** is for. ## The Clarifeye skill The Clarifeye skill is a small package your team installs in their AI client. It teaches the client how to work with Clarifeye: how to find your knowledge stores, read their knowledge, retrieve the right content, and raise signals when something is off. Once it's installed, the client can draw on any knowledge store the user has access to. Under the hood, the skill connects through the **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)**, the standard that lets AI clients talk to external systems. You don't have to think about MCP day to day; the skill handles it. Each knowledge store then behaves like a skill the client can call on, faithful to what was captured. ## What the client can do With the skill installed, an AI client can: * **Discover** the knowledge stores a user can access. * **Inspect** a store's knowledge: its brief, playbooks, mental map, and the rest of its [artifacts](/guides/knowledge#artifacts). * **Retrieve** the specific content needed to answer, with references back to the source. * **Raise a signal** automatically when an answer is wrong or something is missing, feeding the [signals](/guides/build-improve#signals) loop. Because answers are grounded in your artifacts and sources, the client applies your logic and can show where each answer comes from, rather than relying on generic priors. See [MCP tools](/guides/mcp-tools) for the full reference of what the skill exposes. ## Supported clients The skill works with major AI clients, including Claude, ChatGPT, and Copilot, as well as any custom client that supports MCP. Use whichever your team already works in. Connect Clarifeye to Claude.ai using connectors and skills. Connect Clarifeye to ChatGPT using apps and skills. Connect Clarifeye to Microsoft Copilot using MCP tools. For any other MCP-capable client, see [Other clients](/guides/mcp-generic). ## Getting connected Install the Clarifeye skill in your client and sign in to Clarifeye, and your accessible knowledge stores become available. From there, ask the client to use a store the way you'd brief a colleague, and it follows your captured knowledge. The examples in these guides use `eu.app.clarifeye.ai` as the server URL. If you are on the US environment or a dedicated deployment, use the URL shown in your own Deploy tab instead. You'll need at least one Clarifeye knowledge store configured and credentials for one of the supported auth flows. See [MCP authentication](/guides/mcp-authentication) for which to use when. # MCP authentication Source: https://docs.clarifeye.ai/guides/mcp-authentication Authenticate to the Clarifeye MCP server using a user token or OAuth. The Clarifeye MCP server supports two authentication flows. This page is the canonical source for token issuance UI steps — the REST API authentication page links here. ## User token Use `Authorization: Bearer ` with the token generated from your account settings. Suitable for individual or development use. ## OAuth Client ID/secret from the Deploy tab. DCR-capable clients auto-discover; for clients without DCR, paste the Client ID, Authorization URL, Token URL, Refresh URL, and Scopes manually. ## Which one should I use? ## Per-client setup * [Claude](/guides/mcp-claude) * [ChatGPT](/guides/mcp-chatgpt) * [Copilot](/guides/mcp-copilot) * [Other clients](/guides/mcp-generic) # ChatGPT Source: https://docs.clarifeye.ai/guides/mcp-chatgpt Connect Clarifeye to ChatGPT using MCP apps and skills ## Prerequisites * A Clarifeye knowledge store with your **MCP Server URL** from the **Deploy** tab ([see overview](/guides/mcp)). * A [ChatGPT Plus, Team, or Enterprise](https://chatgpt.com) account. ## Step 1: Create an app Go to [chatgpt.com/admin/ca](https://chatgpt.com/admin/ca) and click **Create**. * **Name**: `Clarifeye` * **Description**: `Interact with Clarifeye knowledge store` * **MCP Server URL**: Your MCP Server URL (e.g. `https://eu.app.clarifeye.ai/mcp`) * **Authentication**: Select **OAuth** ChatGPT registers an OAuth client automatically via Dynamic Client Registration — no Client ID or Client Secret is required. Check the **I understand and want to continue** checkbox, then click **Create**. ## Step 2: Add the skill Go to [chatgpt.com/skills](https://chatgpt.com/skills) and upload the skill. Download the skill file from the **Deploy** tab of your Clarifeye knowledge store, then upload it here. ## Step 3: Use Clarifeye in ChatGPT Type `/clarifeye` in any ChatGPT conversation to activate the Clarifeye skill. ChatGPT will connect to your knowledge store and you can start querying it, running tools, and invoking playbooks. # Claude Source: https://docs.clarifeye.ai/guides/mcp-claude Connect Clarifeye to Claude.ai using MCP connectors and skills ## Prerequisites * A Clarifeye knowledge store with your **MCP Server URL**, **Client ID**, and **Client Secret** from the **Deploy** tab ([see overview](/guides/mcp)). * A [Claude Pro, Team, or Enterprise](https://claude.ai) account. ## Step 1: Add a connector Go to [claude.ai/customize/connectors](https://claude.ai/customize/connectors) and click **Add a connector**. * **Name**: `Clarifeye` * **URL**: Your MCP Server URL (e.g. `https://eu.app.clarifeye.ai/mcp`) Click **Advanced settings** and enter: * **Client ID**: Your Client ID from the Deploy tab. * **Client Secret**: Your Client Secret from the Deploy tab. Claude.ai Add custom connector dialog showing Clarifeye configuration with name, URL, and advanced settings for Client ID and Client Secret Click **Add** to save the connector. ## Step 2: Create the skill Go to [claude.ai/customize/skills](https://claude.ai/customize/skills) and click **Upload a skill**. Download the skill file from the **Deploy** tab of your Clarifeye knowledge store, then upload it here. ## Step 3: Use Clarifeye in Claude Type `/clarifeye` in any Claude conversation to activate the Clarifeye skill. Claude will connect to your knowledge store and you can start querying it, running tools, and invoking playbooks. ## Claude Code To use Clarifeye in [Claude Code](https://claude.com/claude-code), either configure the connector in Claude Desktop (Claude Code picks up MCP servers from your Claude Desktop configuration) or add it from the command line: ```bash theme={null} claude mcp add clarifeye https://eu.app.clarifeye.ai/mcp --transport http ``` Replace the URL with your **MCP Server URL** from the Deploy tab if it differs. The first time you use the server, Claude Code prompts you to authenticate. # Microsoft Copilot Source: https://docs.clarifeye.ai/guides/mcp-copilot Connect Clarifeye to Microsoft Copilot using MCP tools ## Prerequisites * A Clarifeye knowledge store with your **MCP Server URL** from the **Deploy** tab ([see overview](/guides/mcp)). The **Advanced** setup also requires your **Client ID** and **Client Secret** from the same tab. * A [Microsoft 365 Copilot](https://www.microsoft.com/microsoft-copilot) license. ## Step 1: Set up the MCP server In Microsoft Copilot, go to **Tools** and click **Add a tool** > **MCP**. Choose one of the two setup paths below. Fill in the server details: * **MCP URL**: Your MCP Server URL (e.g. `https://eu.app.clarifeye.ai/mcp`) * **Name**: `Clarifeye` * **Description**: `Leverage the Clarifeye knowledge store` Set **Authentication** to **OAuth 2.0** and choose **Dynamic Discovery**. Copilot Studio completes the OAuth exchange automatically — no manual credentials and no redirect URLs are required. Fill in the server details: * **MCP URL**: Your MCP Server URL (e.g. `https://eu.app.clarifeye.ai/mcp`) * **Name**: `Clarifeye` * **Description**: `Leverage the Clarifeye knowledge store` Microsoft Copilot Add MCP server dialog showing server name, description, URL, and OAuth 2.0 authentication selection Set **Authentication** to **OAuth 2.0** and set the type to **Manual**. Then fill in: * **Client ID**: Your Client ID from the Deploy tab. * **Client Secret**: Your Client Secret from the Deploy tab. * **Authorization URL**: `https://eu.app.clarifeye.ai/o/authorize/` * **Token URL**: `https://eu.app.clarifeye.ai/o/token/` * **Refresh URL**: `https://eu.app.clarifeye.ai/o/token/` * **Scope**: `claudeai` Microsoft Copilot MCP server OAuth 2.0 configuration showing Client ID, Client Secret, Authorization URL, Token URL, Refresh URL, and Scope fields Copilot generates a **Redirect URL** for the MCP server. Copy it and paste it into the **Redirect URLs** field on the Deploy page you already have open in Clarifeye, then save. Saving redirect URLs requires admin permission. If you hit an error while creating the connection, close the modal, then open the MCP server again from **Tools** and edit it. Create the connection on the last step, then reuse the existing MCP server on your agent. ## Step 2: Add the Skill to the instructions On the **Deploy** tab of your Clarifeye knowledge store, use the **Copy instructions** button to copy the full Clarifeye instructions, then paste them directly into your agent's instructions in Copilot Studio. ## Step 3: Test your connection In Copilot Studio, send a test message to your agent to confirm it can reach the Clarifeye knowledge store and run tools. ## Step 4: Share and publish your agent Once the connection works, share and publish your agent in Copilot Studio so your team can use it. # Other clients Source: https://docs.clarifeye.ai/guides/mcp-generic Connect Clarifeye to any AI assistant that supports MCP. Any AI assistant that supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) can connect to Clarifeye. The setup follows two steps: add the MCP server, then add the skill. ## Prerequisites * A Clarifeye knowledge store with your **MCP Server URL**, **Client ID**, and **Client Secret** from the **Deploy** tab ([see overview](/guides/mcp)). * An AI assistant that supports MCP with OAuth 2.0 authentication. ## Step 1: Add the MCP server In your AI assistant's MCP settings, create a new server with the following details: | Field | Value | | --------------------- | ------------------------------------------------------------ | | **Server name** | `Clarifeye` | | **Server URL** | Your MCP Server URL (e.g. `https://eu.app.clarifeye.ai/mcp`) | | **Authentication** | OAuth 2.0 | | **Client ID** | Your Client ID from the Deploy tab | | **Client Secret** | Your Client Secret from the Deploy tab | | **Authorization URL** | `https://eu.app.clarifeye.ai/o/authorize/` | | **Token URL** | `https://eu.app.clarifeye.ai/o/token/` | Some platforms auto-discover the OAuth endpoints from the MCP server URL. If your platform supports this, you may only need to provide the Client ID and Client Secret. ## Step 2: Add the skill Download the skill file from the **Deploy** tab of your Clarifeye knowledge store. If your platform supports uploading a skill file, upload it directly. If your platform only supports a text prompt, open the file and paste its content into the platform's instructions field. ## Step 3: Use Clarifeye Type `/clarifeye` in a conversation to activate the skill. Your AI assistant will connect to your knowledge store and you can start querying it, running tools, and invoking playbooks. # MCP tools Source: https://docs.clarifeye.ai/guides/mcp-tools The tools the Clarifeye MCP server exposes to AI clients. The Clarifeye MCP server exposes a workflow-shaped set of tools. AI clients (Claude, ChatGPT, Copilot, custom MCP clients) call them in roughly the same order during a session to find the right knowledge store, understand what's in it, run retrievals, submit feedback, and — when acting as a contributor — review past conversations, prepare interviews, and edit knowledge store artifacts. ## How the tools fit together A typical session walks through these stages: 1. **Discover.** Call `list_knowledge_stores` to pick a knowledge store. The `id` you get is the `project_id` every other tool needs. 2. **Inspect.** Call `list_knowledge` for the artifact catalog (cohesion guide plus one row per artifact), `library_tags_objects` for tag hierarchies and object schemas, and the matching `get_*_artifact` tool to read one artifact in full. 3. **Run.** Call `list_tools` for the catalogue, `get_tool` to read the input schema of the one you want, then `run_tool` to execute. Every claim in the answer should carry an inline reference link back to the source. 4. **Feedback.** When the user complains or corrects, call `create_feedback` to push the signal into the knowledge store's feedback queue. 5. **Review.** When acting as a contributor, use `list_feedback`, `list_conversations`, and `list_interviews` to triage signals, then `get_*` to read the detail. Close the loop on addressed items with `resolve_feedback`. 6. **Interview.** Draft new interviews with `draft_interviews` (optionally grouped under a campaign), keep them current with `list_interview_drafts` and `update_interview_draft`, and bring external conversations in with `import_interview_transcript`. Sending always stays a human action. 7. **Edit.** Apply improvements directly with the `set_*_artifact` tools matching each artifact's technical type. Schemas for every tool — including parameters, types, and descriptions — are returned live by the MCP server. The entries below describe purpose and when to use each one, not the wire format. ## Discover ### `list_knowledge_stores` **Lists the knowledge stores the current token can access.** Returns `[{id, name, brief}]`. Typically the first call in a session. Pick one — its `id` is the `project_id` every other tool needs. `list_teammates` is a deprecated alias kept for existing clients ("teammates" was the former name for knowledge stores); prefer `list_knowledge_stores`. ### `whoami` **Returns information about the currently authenticated user.** Thin wrapper over the REST `users/me` endpoint. Useful for sanity-checking auth, surfacing the user's email in a session preamble, or branching behaviour by user. ## Inspect ### `list_knowledge` **Catalog overview of a knowledge store.** Returns the `cohesion_guide` (cross-artifact consistency rules) and `artifacts[]` — one row per in-scope artifact with `slug`, `title`, `semantic_type`, `technical_type`, `group`, `purpose`, and either the full `content` (e.g. markdown artifacts) or a `content_overview` summary (playbooks, mental map, design templates). `group` is the artifact's catalog section: `Foundation` for predefined artifacts, the curator's group name for custom ones, `Other` when a custom artifact is ungrouped. Use it to present the catalog the way curators organized it. Call this before drilling in. If a playbook matches the user's question, read it in full with `get_playbook_list_artifact` and follow its steps. ### `library_tags_objects` **Warehouse tags and object schema for the document library.** Returns markdown sections `tag_hierarchies`, `document_tags`, and `knowledge_graph_objects`. Use it to refine retrieval: the tags and object classes it lists are the filters the retrieval tools accept. ### `list_knowledge_changelog` **Lists the knowledge store's changelog entries, most recent first.** Returns `{count, results}`; each entry carries a human-readable `description`, structured `details`, and the acting `user_email`. Use it to see what changed recently — document uploads, artifact edits — before summarizing knowledge store activity or diagnosing a stale answer. ### `get_markdown_artifact` and friends **Read one artifact in full.** Pick the `get_*` tool matching the artifact's `technical_type` from `list_knowledge` and pass its `slug`: * `get_markdown_artifact` — markdown artifacts (e.g. `brief`, `general_knowledge`, `library_description`). * `get_playbook_list_artifact` — the playbook list (typically `playbooks`). * `get_mental_map_artifact` — the mental map. * `get_design_template_list_artifact` — design templates, including their files. * `get_bpmn_xml_artifact` — custom BPMN 2.0 process diagrams. ## Run ### `list_tools` **Brief catalogue of the knowledge store's tools.** Returns `[{id, name, tool_type}]` — intentionally minimal so the listing stays cheap. For the full metadata, including the input schema, call `get_tool` on the one you want. ### `get_tool` **Full metadata for one tool.** Returns the `input_schema` (JSON Schema), the tool type, and a description augmented with a type-specific usage guide. Always call this before `run_tool` for an unfamiliar tool — the schema is the source of truth for what arguments to pass. ### `run_tool` **Executes a tool against the knowledge store.** Takes a tool id and an input dict that matches the tool's input schema. **On failure**, returns a structured error object including `expected_input_schema` (re-fetched) and a hint to retry — no exception is raised. Use that to self-correct: re-read the schema, fix the input, call again. Not the right tool for submitting feedback — use `create_feedback`. ## Feedback ### `create_feedback` **Submits feedback to the knowledge store's feedback queue.** Takes a flat, LLM-friendly payload (`type`, `is_positive`, `user_query`, `reason`, …); the server restructures it into the backend's shape and tags the source as `MCP`. Use it whenever the user complains, corrects, or confirms — it lands as a [signal](/guides/build-improve#signals) that Contributors pick up and use to update artifacts or sources. ### `list_feedback` **Lists feedback items in a knowledge store.** Returns `{count, results}` — up to `limit` rows (default 50); raise `limit` to page further. Filter by `status` (`"to_review"`, `"reviewed"`, `"dismissed"`) and `is_positive` to focus on what matters. For triage, pass `is_positive=false` and `status="to_review"` to surface unactioned negative signals. Each row carries the linked `conversation` id and a `user_message` preview. Call `get_feedback` then `get_conversation` to deep-dive an exchange. ### `get_feedback` **Gets a single feedback item, including the linked `conversation` id.** The reviewer's note is in the `feedback` field and the end-user's message in `user_message`. Follow the returned `conversation` id with `get_conversation` to read the full transcript that produced the signal. ### `resolve_feedback` **Closes the loop on a feedback item once it has been addressed.** Pass `status="reviewed"` when you acted on it (e.g. by editing an artifact) or `status="dismissed"` for won't-fix. The artifact edit itself is the audit trail of how it was addressed. ## Review ### `list_conversations` **Lists end-user playground conversations in a knowledge store.** Returns `{count, results}` — lightweight rows with `first_user_message`, `message_count`, tags, and `feedback_count`. Returns up to `limit` rows (default 50). Use for triage — pick conversations worth reading in full, then call `get_conversation`. ### `get_conversation` **Gets a single conversation with its full `chat_history`.** Use to read the exchange a feedback refers to (follow the `conversation` id from `get_feedback`), or to inspect an end-user conversation in detail. ### `list_interviews` **Lists interviews (coach conversations) in a knowledge store.** Returns `{count, results}` — lightweight rows with `name`, `status`, `first_message_preview`, and `message_count`. Returns up to `limit` rows (default 50). Filter by `status` (`"pending"`, `"in_progress"`, `"completed"`, comma-separated for several) to narrow scope. Rows include imported external transcripts (type `"imported-interview"`); their `import_info.import_status` must be `"ready"` before the transcript is readable. Use for consensus/contradiction triage — pick interviews worth reading in full, then call `get_interview`. ### `get_interview` **Gets a single interview with its full `chat_history`.** Besides the transcript, the response carries the interview's setup: `interview_focus` (`{topic, questions}` — what the interviewing agent was briefed on) and, for guided interviews, `topics` (the ordered agenda, each `{title, description, status, skill_id}`; empty for other types). Use it to read the full exchange for analysis, understand what an interview was meant to cover, or reuse its setup when drafting a similar one. Imported transcripts carry a per-message `speaker` name. A merged label like "Them" or several names means the export did not attribute those lines to one person — never present merged-speaker statements as one named individual's words. ## Interview Drafting tools never send anything: a draft only becomes real interviews when a human reviews and sends it from the interviews page. Always end a drafting exchange by handing the user the returned `draft_edit_url` and telling them to review and send. ### `draft_interviews` **Drafts (but never sends) an interview for a set of recipients.** Two kinds: a single-topic `interview` (5–10 minutes, the default) opens on the `focus` and lets the interviewer ask follow-ups — optionally seeded with specific `questions` (max 10). A `guided-interview` walks an ordered `topics` agenda (max 12, each `{title, description}`) at roughly 5–10 minutes per topic — pick it only for broad, structured coverage, and agree the topic list with the human first. Recipients can be existing members or new email addresses; new addresses are only invited to the store if the human sends the draft. `language` pins the interview to an ISO language code when the human asks for one. `campaign_name` groups the interview under an interview campaign (e.g. a workshop wave or rollout round) — it reuses the project's existing campaign with that name (case-insensitive) or creates it; only set it when the human names a campaign or clearly groups several interviews together. Each call creates a fresh draft — to change an existing one, use `update_interview_draft` instead of re-drafting. ### `list_interview_drafts` **Lists saved, unsent interview drafts in a knowledge store.** Returns `{count, results}`, newest-edited first; each row carries the draft's `topic`, `questions`, `topics` (guided drafts), recipients, settings, and a `draft_edit_url`. Check it before drafting a new interview to avoid near-duplicates, or when the human asks what's pending. For sent or completed interviews use `list_interviews` instead. ### `update_interview_draft` **Updates one saved draft in place — still never sends anything.** Prefer it over `draft_interviews` when the human wants changes to an existing draft. Only the fields you pass change; the draft's interview type is immutable. `focus`, `questions` (single-topic drafts), `topics` (guided drafts), recipients, `custom_message`, and `language` can all be replaced. `campaign_name` moves the draft to that campaign (creating it if needed); pass an empty string to remove the draft from its campaign. ### `import_interview_transcript` **Imports the transcript of an interview that happened outside the platform** (a Granola, Teams, or Zoom export, meeting notes with speaker turns, …). Creates a read-only imported interview; parsing into speaker-labeled turns runs in the background (`import_info.import_status` goes from `"parsing"` to `"ready"`). Pass the transcript text verbatim — never summarize, trim, or reformat it — and call the tool once per transcript. `title`, `participants`, and `interview_date` are optional; anything omitted is inferred during parsing. ## Edit Writes require admin permission on the knowledge store. Each artifact type has a matching `set_*` tool — pick it by the artifact's `technical_type` from `list_knowledge`, and always read the current content with the matching `get_*` tool before writing. Pass a `change_summary` stating what changed and why, and cite the interview or feedback evidence behind the change. ### `set_markdown_artifact` **Edits a markdown artifact** (brief, general knowledge, library description, custom markdown artifacts). Takes an `op` — replace the whole text, replace a line range, or replace a matched text occurrence — plus `new_text`. ### `set_playbook_list_artifact` **Edits the playbook list.** Takes an `identifier` (the playbook), a `change_summary`, and an ordered `changes` list. Apply changes in order — add steps before the links that reference them. Failed individual changes are skipped and reported per-change without aborting the rest. ### `set_mental_map_artifact` **Edits the mental map.** Takes a `change_summary` and an ordered `changes` list over domains, classes, and relations. Add domains and classes before the relations that reference them; deleting a domain or class also removes dependent entities. ### `set_design_template_list_artifact` **Creates, updates, or deletes a design template**, including its attached files. ### `set_bpmn_xml_artifact` **Edits a BPMN process-diagram artifact** through structured changes — agents never submit raw XML. # Organization settings Source: https://docs.clarifeye.ai/guides/organization-settings The organization-level layer that shapes every knowledge store beneath it. Your **organization** is the top-level account that holds all your knowledge stores. A few things are set once here and apply across every store, so you configure them in one place instead of repeating yourself store by store. ## Organization context Organization context is shared background about your company that every store can draw on: who you are, how you talk, and the assumptions that hold true across the whole organization. Setting it here means Clara starts every interview and every store already knowing the basics, rather than rediscovering them each time. ## Interview templates Interview templates are reusable structures for the [interviews](/guides/build-improve#interviews) Clara runs. A template captures the shape of a recurring kind of interview, the themes to cover and the house style to follow, so interviews stay consistent across topics, contributors, and stores. Set a template up once and the interviews you create inherit it, while Clara still adapts the actual conversation to each person. This is the customization layer for interviews. Individual interviews don't carry their own configuration; they draw on the organization's context and templates. ## Account, billing, and access The organization is also where account-level settings live: * **Billing and plan**, rolled up so you get a single invoice across all your stores. * **Security and SSO**, configured once for everyone in the organization. See [SSO](/guides/sso). * **Members and access**, managed at the organization level, with permissions then scoped per knowledge store so the same person can be a contributor in one store and a user in another. See [User management](/guides/user-management). # Other Security Settings Source: https://docs.clarifeye.ai/guides/other-security Other security settings in Clarifeye Other security settings are not available on all plans. Please contact us at `support@clarifeye.ai` to enable it for your organization. Clarifeye offers additional security settings to protect your data and organization. ## IP Allowlisting IP Allowlisting allows you to restrict access to your Clarifeye instance to specific IP addresses. # Quickstart Source: https://docs.clarifeye.ai/guides/quickstart Go from an empty knowledge store to one your team can use through an AI client. This walkthrough takes you through the full loop once. Each step links to a detailed guide if you want to go deeper. Sign in to Clarifeye and click **Create a new knowledge store**. Clara runs a short interview, around 20 minutes, to gather your inputs, then builds a first version of your artifacts from your answers. See [Create your knowledge store](/guides/create-knowledge-store) for the full flow. Open **Interviews** and create interviews for the topics your store needs to cover. Assign each one to the teammate who holds that knowledge. Clara runs each interview asynchronously and adapts to the person it's talking to, so contributors can answer in their own words and their own language, whenever it suits them. Add documents or connected drives under [Sources](/guides/knowledge#sources) to capture knowledge that's already written down. See [Interviews](/guides/build-improve#interviews). As interviews and sources come in, go to **Work with Clara** to turn raw input into trusted knowledge. Clara analyzes what was captured, flags contradictions and gaps, and proposes updates to your [Artifacts](/guides/knowledge#artifacts). You review and steer every change. See [Work with Clara](/guides/build-improve#work-with-clara). Install the **Clarifeye skill** in your AI client (Claude, ChatGPT, Copilot, or a custom MCP client). From then on the client can draw on any knowledge store you have access to, applying your logic instead of generic answers. See [Connect to AI clients](/guides/mcp). Use **Task** to apply the store to real work, like filling an RFP or drafting an answer that follows your process. This is the knowledge in action, as it stands today. See [Task](/guides/use). As people use the store, corrections and gaps surface as **signals**, centralized in one place. Clara helps you triage them and feed them back into the knowledge, sometimes by triggering a new interview. Keeping the store current is the most important ongoing job, so encourage everyone to leave a signal whenever something looks off. See [Signals](/guides/build-improve#signals). Share the knowledge store with your team so they can answer interviews, run tasks, and raise signals. Permissions are scoped per store, so the same person can be a contributor in one store and a user in another. See [User management](/guides/user-management). # SharePoint Source: https://docs.clarifeye.ai/guides/sharepoint Connect a SharePoint site as a source. Connect a SharePoint site to pull its content in as a [connected source](/guides/knowledge#sources), kept in sync as it changes. ## Connect a SharePoint site From the **Sources** tab, go to **Connectors** and add SharePoint. Select the files or folders you want to bring in. Clarifeye keeps them in sync from then on: changes made in SharePoint are reflected in the knowledge store automatically. ## What gets synced Alongside the file content, Clarifeye imports metadata for each document: its path, the folder it belongs to, and its created-at and modified-at timestamps. If a folder's name matches the slug of a collection, files from that folder are placed into that collection automatically. New and updated files are picked up automatically. Deleting a document from the SharePoint folder doesn't delete it from Clarifeye — remove it from the knowledge store directly if it no longer applies. ## Connecting for a larger organization In a larger organization, the simplest setup is to have a SharePoint admin be the one to connect Clarifeye. That single connection approves the application once, so the rest of your users don't each need to approve it themselves. Once the connection is approved, the admin's account and connection can be deleted; the approval persists. ## Security The connector authenticates to SharePoint as the connecting user, via OAuth 2.0, so it can only pull in what that user has permission to see in SharePoint. Once a document is imported into a knowledge store, it's visible to every member of that knowledge store, regardless of their individual SharePoint permissions. Access in Clarifeye is scoped by knowledge store membership, not by the original SharePoint permissions of each member. # Send signals from Slack & Teams Source: https://docs.clarifeye.ai/guides/signals-slack Send signals to Clarifeye from Slack or Microsoft Teams by calling the API from your own app. A [signal](/guides/build-improve#signals) is a note flagging that something in a knowledge store is wrong, out of date, or missing. The people who spot these problems are usually mid-conversation in Slack or Teams, not logged into Clarifeye. This guide shows how to let them send a signal without leaving chat. There's no prebuilt Slack or Teams integration to install. Instead, you build your own app in the tool your team already uses and have it call the Clarifeye REST API. Anything sent this way lands in the same **Signals** inbox in the app and is reviewed like any other signal. ## Prerequisites * A Clarifeye knowledge store, and its **project ID** (the store's UUID). * An API token with access to that store. See [MCP authentication](/guides/mcp-authentication) for how to issue one — the same `Authorization: Bearer ` credential works for the REST API. * The ability to build and install an app in your Slack workspace or Microsoft Teams tenant. The examples use `eu.app.clarifeye.ai` as the server. If you're on the US environment or a dedicated deployment, use your own server URL instead. ## The API call Everything on this page reduces to a single request: a `POST` to the project signals endpoint. ``` POST https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/signals/ ``` Send the note text as `feedback`, and use the free-form `context` object to record where it came from. `source` is just a label you choose — it shows up alongside the signal in the review UI. ```bash cURL theme={null} curl -X POST \ "https://eu.app.clarifeye.ai/api/v1/projects/$PROJECT_ID/signals/" \ -H "Authorization: Bearer $CLARIFEYE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "feedback": "The refund policy in the store is out of date — EU orders are now 30 days, not 14.", "context": { "source": "Slack" } }' ``` ```javascript JavaScript theme={null} const res = await fetch( `https://eu.app.clarifeye.ai/api/v1/projects/${projectId}/signals/`, { method: "POST", headers: { Authorization: `Bearer ${process.env.CLARIFEYE_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ feedback: "The refund policy in the store is out of date — EU orders are now 30 days, not 14.", context: { source: "Slack" }, }), } ); ``` See the [Submit a signal](/api-reference/signals/submit-a-signal) reference for the full request and response schema. ## Send it from Slack or Teams Clarifeye doesn't prescribe a single way to wire this up — there are several valid approaches depending on your tooling, plan, and hosting preferences. The principle is the same on both platforms: **build your own app and have it call the signals API above.** However you build it, the app authenticates to Clarifeye with the standard API token and sends the same request. * **Slack** — build a Slack app (for example a slash command or a message shortcut) that POSTs to the endpoint. See Slack's [Create an app](https://docs.slack.dev/quickstart) guide to build and install it. * **Microsoft Teams** — build a Teams app (a bot, message action, or message extension) that POSTs to the endpoint. See Microsoft's [Build apps for Microsoft Teams](https://learn.microsoft.com/microsoftteams/platform/get-started/get-started-overview) guide. ## Where to find your project ID and token * **Project ID** — the UUID of the knowledge store you want signals to land in. You can find it in the store's URL in the Clarifeye app. * **API token** — issue one from your account settings and send it as `Authorization: Bearer `. See [MCP authentication](/guides/mcp-authentication) for the full walkthrough; the same token authenticates the REST API. Store the token as a secret in your app's configuration rather than hard-coding it. # Single Sign-On (SSO) Source: https://docs.clarifeye.ai/guides/sso Set up SSO with OpenID Connect (OIDC) or SAML for Clarifeye ## Overview Clarifeye supports both OpenID Connect (OIDC) and SAML Single Sign-On (SSO) so you can manage access using your existing Identity Provider (IdP). SSO is not available on all plans. Please contact us at `support@clarifeye.ai` to enable it for your organization. ### Supported Identity Providers Clarifeye works with all major standards‑compliant IdPs, including but not limited to: * Okta * Microsoft Entra ID (Azure AD) * Google Workspace * OneLogin ## How to enable SSO To initiate setup, contact Clarifeye Support at `support@clarifeye.ai` or through the chat widget on the bottom right of the screen with your organization details and preferred protocol (OIDC or SAML). ### OpenID Connect (OIDC) * Clarifeye will provide your tenant-specific Login URL, redirect url is of the form: `https://.clarifeye.ai/accounts/oidc/specific-id/login/callback` * You will configure your IdP application to use that Login URL and complete any required claims according to your IdP’s standard OIDC setup. ### SAML 2.0 Clarifeye will provide the following values for your IdP configuration: * ACS (Assertion Consumer Service) URL (example: `https://.clarifeye.ai/accounts/saml/specific-id/acs/`) * Entity ID / Audience URI (example: `urn:clarifeye.ai:specific-id`) Use the following attribute mapping in your IdP: ```json theme={null} { "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", "given_name": [ "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" ], "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", } ``` Then provide the following attributes to Clarifeye: * IdP Single Sign-On URL * X.509 Certificate ## Activation Once your IdP is configured, Clarifeye Support will enable the connection and activate SSO at the time you select. # Use Source: https://docs.clarifeye.ai/guides/use Put your knowledge store to work to produce a real output. A **task** applies a store to a concrete piece of work, using the knowledge exactly as it stands today. If your store captures how you answer RFPs, a task is filling one; if it captures how you review contracts, a task is reviewing one. Rather than applying the playbooks yourself, you hand the work to Clara: she follows your [artifacts](/guides/knowledge#artifacts) and draws on your [sources](/guides/knowledge#sources) to produce the output, and shows how each answer was produced and which sources it rests on so you can trust it. ## Two ways to use a store Task is one of two alternatives for putting a store to work: * **Inside Clarifeye, with Task.** Run the work and inspect each output and its sources in one place. * **In your own AI client, with the [Clarifeye skill](/guides/mcp).** Apply the same knowledge from Claude, ChatGPT, or Copilot, in the tools your team already uses. It's the same underlying knowledge either way. If a task shows the knowledge is wrong or thin, that's a [signal](/guides/build-improve#signals): take it into [Work with Clara](/guides/build-improve#work-with-clara), then run the task again. # User management Source: https://docs.clarifeye.ai/guides/user-management Profiles, permissions, and how to invite users to a knowledge store. Access to a knowledge store is controlled by two layered mechanisms: **profiles** define what a person can broadly do, and **permissions** are named grants layered on top for specific capabilities. ## Profiles Every user is assigned one of three profiles when invited. Profiles are stable — you assign one at invite time and rarely change it. Each one corresponds to a persona you'll recognize from your team. ### Contributor — the knowledge/operations persona The owner of the knowledge over time. Day-to-day responsibilities: * **Acts on production** — adds sources, edits artifacts, reviews feedback. * **Maintains the knowledge** so it stays accurate as the business changes. * **Follows the operational workflow** — work the feedback queue, refresh stale sources, apply Clara's suggestions. * **Takes interviews** — can take interviews assigned to them to capture their expertise. Surfaces: playground, knowledge store settings, sources, feedback. ### Technical user — the backend/pipeline persona More comfortable with backend systems and the data pipeline. Day-to-day responsibilities: * **Tweaks data pipeline parameters** — parsing, chunking, indexing. * **Configures extractors, flows, and connectors** for new source types. * **Maintains advanced API integrations** for systems that don't use MCP. Surfaces: everything a Contributor sees, plus the back office and pipeline settings. ### User — the end-user persona Primarily consumes the knowledge store rather than building it. Day-to-day responsibilities: * **Uses the Q\&A side** — asks questions in the playground or through an AI client. * **Runs tools** the knowledge store exposes through MCP. * **Submits feedback** when something is wrong. Surfaces: playground and MCP clients (Claude, ChatGPT, Copilot, etc.). No need for broad technical access. Profiles are scoped to a knowledge store, not the organization. The same person can be a Contributor in one store and a User in another. ## Permissions Permissions are named grants that extend or restrict what a profile can do. They can also be configured in the knowledge store settings page. ### DataReader Can use Chat or Task with the AI agent and read sources. This is the baseline grant for anyone who consumes the knowledge store: asking questions in the playground, running tasks, and browsing source documents. ### Admin Can modify knowledge and sources, and see everything that's done inside the knowledge store. Admins manage the store's content — editing artifacts, adding or removing sources — and have full visibility into all activity, including other users' conversations and interviews. ### Interviewee Can take interviews assigned to them. Interviewees have no access to knowledge store data: they don't see sources, artifacts, or the playground — only the interviews they've been assigned. ## Profiles vs. permissions * A **profile** is the persona you pick at invite time. It sets the baseline for what someone can do and rarely changes. * A **permission** is a backend-controlled grant added on top for a specific capability — useful when a profile baseline doesn't quite match what one person needs to do. If you need a permission combination that isn't currently supported, contact us at `support@clarifeye.ai`. ## How to invite users You need to be a Contributor (or higher) to invite users to a knowledge store. 1. Go to the knowledge store settings. 2. Click the **Users** tab. 3. Click **Invite user**. 4. Enter the user's email. 5. Select their profile. 6. Click **Invite user**. # What is Clarifeye? Source: https://docs.clarifeye.ai/guides/what-is-clarifeye Clarifeye captures your organization's expertise and turns it into knowledge that AI can use faithfully. Every organization runs on knowledge that lives in people's heads and scattered across documents: how you qualify a deal, answer an RFP, review a contract, run a process. Clarifeye captures that knowledge, consolidates it into a single trusted source, and packages it so any AI client (Claude, ChatGPT, Copilot, or your own) can apply it with *your* logic instead of generic priors. It works as a continuous loop across four stages. ## 1. Capture Clara, Clarifeye's agent, interviews your experts asynchronously, in their own language, adapting to whoever it's talking to. It also reads everything you connect: uploaded documents and connected drives like Google Drive or SharePoint. You decide what knowledge matters and assign interviews to the people who hold it. ## 2. Consolidate Captured knowledge is messy. People disagree, sources conflict, and the most important things are often never written down. Clara resolves contradictions, fills gaps, builds consensus, and writes it all into a clean set of **artifacts**, the trusted and structured representation of your expertise. ## 3. Make AI-ready The knowledge is packaged into a form AI can consume. Your team installs the **Clarifeye skill** in their AI client, and from then on the client can draw on any of your knowledge stores through it, faithful to what was captured and connectable anywhere. ## 4. Track signals Knowledge goes stale. As people use it, in an AI client, in a task, or anywhere else, they surface corrections, gaps, and drift. Clarifeye centralizes these as **signals**, the single place where everything that should update your knowledge converges. Signals can trigger new interviews, closing the loop back to Capture. ## How this maps to Clarifeye Everything you do in Clarifeye lives inside a **knowledge store**, one self-contained body of expertise for a team, product, or use case. The store's navigation follows the same four stages: * **Build & Improve** * **[Interviews](/guides/build-improve#interviews)**: capture knowledge from your experts *(Capture)* * **[Work with Clara](/guides/build-improve#work-with-clara)**: review interviews, tasks, and artifacts, and update the knowledge together *(Consolidate)* * **[Signals](/guides/build-improve#signals)**: everything flowing in that should update the store *(Track signals)* * **Knowledge** * **[Artifacts](/guides/knowledge#artifacts)**: the consolidated expertise (brief, playbooks, mental map, and more) * **[Sources](/guides/knowledge#sources)**: the documents and connected drives behind it * **Use** * **[Task](/guides/use)**: apply the knowledge to get real work done, like filling an RFP *(Make AI-ready)* Two surfaces are easy to confuse. **Work with Clara** *changes* the knowledge (a policy shifted, a new source arrived), while **Task** *uses* the knowledge as it stands today to produce an output. ## Next steps Build your first knowledge store and connect it to an AI client. Knowledge stores, artifacts, signals, and how AI consumes them.