> ## Documentation Index > Fetch the complete documentation index at: https://docs.clarifeye.ai/llms.txt > Use this file to discover all available pages before exploring further. # Edit a sent interview before its first answer > Change a sent guided interview's content in place. **Admin only.** Possible while the interview's `can_edit` is true: not yet answered by its respondent, not completed, not archived, not a test run. If Clara's opener was already generated (the respondent opened the link), it is discarded so the next open greets them with the new agenda. Nobody is notified and the link is unchanged. Recipients and invitation settings cannot be changed here. Send only the fields that change. `topics` replaces the whole ordered list (same shape and rules as on drafts); `artifacts` replaces the selection. ## OpenAPI ````yaml /api-reference/openapi-full.yaml post /projects/{project_id}/interviews/{interview_id}/edit/ openapi: 3.0.3 info: title: Clarifeye Platform API — Full API Documentation description: > Complete REST API reference for the Clarifeye Platform. Documents every endpoint exposed by the platform — the public surface plus the advanced surface: pipeline customization (extraction flows, pipeline runs, warehouse tables, document tag/metadata configuration), the pre-MCP AI surface (agent settings, playground conversations, conversation-scoped feedback views, notifications), and the impersonation header. New AI integrations should consume knowledge via MCP rather than the conversation/agent-settings endpoints documented here. ## Authentication All endpoints require authentication. Include the Authorization header in every request using either format: - `Authorization: Token ` - `Authorization: Bearer ` ## Service accounts and API keys Integrations authenticate with an **API key** of a **service account**: - `Authorization: Bearer ` (keys start with `cfk_`) A service account is an ordinary member (role `member`) of one organization that cannot log in. Organization admins create it and mint its keys on the organization's *Service accounts* page (`/organizations/{id}/service-accounts/`, `/organization-api-keys/`), and give it access to knowledge stores with ordinary store permissions. A key is valid on every endpoint and acts as its service account: it reaches exactly the stores, with exactly the rights, the account was given. An account can hold several keys (each with its own name, optional expiry and revocation), so a key can be rotated without changing identity. A refused key answers **403** with one of: `Invalid API key.`, `API key revoked.`, `API key expired.`, `API key disabled.` (the service account is disabled). Any valid key may also call `POST /organizations/{id}/provision-user/` and `POST /organizations/{id}/deprovision-user/` for its own organization (the `{id}` in the path must be the key's organization). The email domains these may pre-create accounts for are configured by Clarifeye on the organization (`allowed_provisioning_domains`). ## Impersonation Certain endpoints support user impersonation for creating or listing data on behalf of other users. This is useful for integrating external systems that need to attribute actions to specific users. **Header:** `X-Impersonate-Email` **Required Permission:** `CAN_IMPERSONATE_OTHER_USERS` (for a person, contact Clarifeye to enable it; org admins grant it to a service account on the organization's Service accounts page) **Behavior:** - If the header is provided and the impersonator has the required permission, the action is performed as the target user - If the target user is not found, the request proceeds as the original authenticated user - If the target user does not have access to the project, the request proceeds as the original authenticated user - If the impersonator lacks the `CAN_IMPERSONATE_OTHER_USERS` permission, the header is ignored **With an API key** the request fails instead (**403**) whenever impersonation cannot happen: missing permission, unknown target, target without access to the store, target that is itself a service account, or an endpoint outside a store. A key never silently acts as its own service account when impersonation was asked for. version: 1.0.0 contact: name: Clarifeye Support servers: - url: https://eu.app.clarifeye.ai/api/v1 description: EU - url: https://us.app.clarifeye.ai/api/v1 description: US security: - BearerAuth: [] - TokenAuth: [] tags: - name: Users description: Manage users within a project - name: Invitations description: Manage project invitations - name: Documents description: Manage documents within a project - name: Agent Settings description: Manage AI agent configurations - name: Conversations description: Create and interact with AI-powered conversations - name: Interviews description: Assign and review structured interview conversations - name: Meetings description: >- Meetings Clara attends as a bot (Recall.ai) — live transcript, live insights, recording, and calendar scheduling (CLA-1843). Store admins only. - name: Feedback description: >- Submit and review feedback — standalone (content-only), agent-submitted (MCP), or linked to a conversation message - name: Tools description: Execute configured AI tools with custom parameters - name: Tables description: Perform CRUD operations on warehouse tables - name: Notifications description: Manage project-scoped notifications for users - name: Extraction Flows description: >- Manage extraction flows (auto-sync DAGs) — list, run, inspect statistics, update, and publish - name: Object Extractors description: | Extract structured data (instances of a Pydantic model) from chunks or blocks of documents. Update auto-creates a new `ObjectExtractorVersion` when version-bearing fields change. - name: Tag Extractors description: | Apply hierarchical metadata tags to chunks or documents using an LLM. Update auto-creates a new `TagExtractorVersion` when version-bearing fields change. - name: Chunks Extractors description: | Segment parsed documents into chunks for downstream processing. Update auto-creates a new `ChunksExtractorVersion` when version-bearing fields change. - name: Parsing Extractors description: | Convert source documents to text blocks via the parsing pipeline. Update auto-creates a new `ParsingExtractorVersion` when version-bearing fields change. - name: Document Filter Extractors description: | Restrict a downstream pipeline branch to documents matching a filter. Update auto-creates a new version when the filter changes. - name: Chunk Tag Filter Extractors description: | Restrict a downstream pipeline branch to chunks carrying specific tags. Update auto-creates a new version when the filter changes. - name: Document Tag Extractors description: | Apply a flat set of metadata tags to each document. Update auto-creates a new version when version-bearing fields change. - name: Tag Alerts Extractors description: | Run LLM-based alerts over already-extracted tag rows. Update auto-creates a new version when version-bearing fields change. - name: Object Alerts Extractors description: > Run LLM-based alerts over already-extracted object rows. Update auto-creates a new version when version-bearing fields change. - name: Imported Object Extractors description: | Hold objects imported from an external system (rather than extracted by an LLM). Useful for hydrating the warehouse with data produced outside the platform. - name: Pipeline Runs description: >- Inspect pipeline runs queued by extraction flows or other pipeline triggers — list runs and fetch the details/status of a single run - name: User Provisioning description: > Pre-create and de-provision org users via an org-scoped API key (`Authorization: Bearer `). The organization is resolved from the key. - name: Organization API Keys description: | Management of org-scoped provisioning API keys. Org admins can mint, list, retrieve, update, reveal, and revoke their own org's keys. - name: Design System Templates description: Reference/example files attached to a design template. - name: Artifacts description: | Knowledge-store artifact catalog — list artifacts, create/edit custom artifacts, manage scope membership, read and publish versions, configure the store map, and export/import the whole catalog. For type-aware reads and edits of artifact content, prefer the `read-write-*-artifact` tool endpoints. paths: /projects/{project_id}/interviews/{interview_id}/edit/: post: tags: - Interviews summary: Edit a sent interview before its first answer description: > Change a sent guided interview's content in place. **Admin only.** Possible while the interview's `can_edit` is true: not yet answered by its respondent, not completed, not archived, not a test run. If Clara's opener was already generated (the respondent opened the link), it is discarded so the next open greets them with the new agenda. Nobody is notified and the link is unchanged. Recipients and invitation settings cannot be changed here. Send only the fields that change. `topics` replaces the whole ordered list (same shape and rules as on drafts); `artifacts` replaces the selection. operationId: editSentInterview parameters: - $ref: '#/components/parameters/ProjectId' - name: interview_id in: path required: true description: UUID of the interview to edit schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: name: type: string focus: type: string description: What the interview is about. Cannot be blank. topics: type: array maxItems: 12 items: $ref: '#/components/schemas/GuidedInterviewTopic' instructions: type: string description: >- How Clara runs the session (interviewer-only). Empty removes them. artifacts: type: array items: $ref: '#/components/schemas/InterviewArtifactSelection' language: type: string nullable: true description: ISO language code, or null for auto-detect. planned_minutes: type: integer minimum: 5 maximum: 180 description: >- The whole interview's planned length in minutes. Left out on a topics change, a length still at the old topic default follows the new agenda. surface: type: string enum: - ui - mcp default: ui description: >- Where the edit came from, for analytics only. The MCP server sends `mcp`. responses: '200': description: The updated interview, plus the fields that actually changed. content: application/json: schema: allOf: - $ref: '#/components/schemas/Interview' - type: object properties: updated_fields: type: array items: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- The interview can no longer be edited (already answered, completed, archived, or a test run). components: parameters: ProjectId: name: project_id in: path required: true description: UUID of the project schema: type: string format: uuid schemas: GuidedInterviewTopic: type: object description: > One ordered topic of a guided interview. `title` and `description` say what THIS topic must cover; `skill_id` is its TYPE — how the interviewer works it — and round-trips through edits, so preserve the values you received or the topic loses its skill-backed interview depth. Accepted values are the interview skills (`use_case_exploration`, `use_case_context`, `document_library`, `document_upload`, `checklist`, `custom_topic`, `guided_wrap_up`, plus ids retired from new agendas but still carried by older drafts); an unrecognized id is rejected with 400. Omit `skill_id` for a free-form topic, driven by its own title/description text — such a topic must then carry a non-empty `description` (400 otherwise); a skill-backed topic may leave it blank. required: - title properties: title: type: string maxLength: 200 description: type: string skill_id: type: string nullable: true InterviewArtifactSelection: type: object required: - slug properties: slug: type: string description: An in-scope artifact slug. show_to_respondent: type: boolean default: false description: > Whether the respondent can also open this artifact, read-only, beside the chat (`GET .../interviews/{id}/artifacts/`). False keeps it as the interviewer's background only. Interview: type: object description: A structured interview conversation, including its full transcript. properties: id: type: string format: uuid readOnly: true can_edit: type: boolean readOnly: true description: >- Whether an admin may still edit this sent interview (before its first answer). not_editable_reason: type: string nullable: true readOnly: true description: >- Why the interview can no longer be edited (answered, completed, archived, test run, not guided); null while `can_edit` is true. last_edited_at: type: string format: date-time nullable: true readOnly: true description: When an admin last edited this sent interview. last_edited_by_email: type: string format: email nullable: true readOnly: true sent_from_draft_id: type: string format: uuid nullable: true readOnly: true description: The draft this interview was sent from, when it was sent from one. name: type: string nullable: true description: Interview title (auto-generated from the topic when not provided). created_by: type: string format: uuid readOnly: true description: UUID of the user who created the interview. created_by_email: type: string format: email nullable: true readOnly: true description: >- Email of the user who created the interview (the importer, for imported interviews). type: type: string description: > Conversation type: "interview" (standard mono-topic), "guided-interview" (a multi-topic deep-dive whose ordered topics come from the sent draft or assign payload; its focus text lives in `type_additional_parameters.interview_focus`), or "imported-interview" (a read-only transcript of an interview recorded outside the platform, created via the import-transcript endpoint). type_additional_parameters: type: object description: > Free-form parameters associated with the conversation type. Assigned interviews carry `planned_minutes` (the planned length) among them. chat_history: type: array description: Ordered list of transcript entries (messages, tool calls, etc.). items: type: object chat_participants: type: object readOnly: true description: > Users who submitted at least one user turn, keyed by user id (each user entry carries a `user_id`). Can differ from `assigned_to` when an admin finishes an interview assigned to someone else. additionalProperties: type: object properties: email: type: string format: email chat_memory: type: object description: >- Assistant memory state accumulated over the conversation. Server-only keys (`respondent_profile`, the respondent's profile as of the first turn) are omitted; sending one is a 400, and a write keeps the stored value. local_documents: type: array readOnly: true description: > Files attached to this interview (ordered by upload time). Only the id, name and source are included; resolve a fresh signed download URL via the project-level local-documents detail endpoint. Both `uploaded` files and `generated` files (produced by an agent in the conversation) can be imported into the Sources library. items: type: object properties: id: type: string format: uuid name: type: string source: type: string enum: - uploaded - generated assigned_to: type: string format: uuid nullable: true readOnly: true description: >- UUID of the assigned user (null while a pending invite has not yet joined). assigned_by: type: string format: uuid nullable: true readOnly: true description: UUID of the user who created the assignment. assigned_to_email: type: string format: email nullable: true readOnly: true description: >- Assignee email, falling back to the invite email for not-yet-joined invitees. assigned_by_email: type: string format: email nullable: true readOnly: true is_pending_invite: type: boolean readOnly: true description: True when assigned to someone who has not yet joined the project. invite_config: allOf: - $ref: '#/components/schemas/InterviewInviteConfig' nullable: true readOnly: true interview_focus: type: object nullable: true readOnly: true description: > The seeded interview topic and optional specific questions, for rendering the in-chat intro card. Null for non-interviews and interviews without a topic. For guided interviews this is read from `type_additional_parameters.interview_focus` (they have no focus issue). properties: topic: type: string instructions: type: string description: > Guided interviews only: the organiser's rules for how Clara runs the session (read from `type_additional_parameters.interview_instructions`). Interviewer-only — never included in invitation emails or shown on the respondent's screen. Empty when none were set. questions: type: array items: type: string topics: type: array readOnly: true description: > Guided interviews only: the ordered topic agenda seeded at send time, with per-topic progress. Empty for every other interview type. items: type: object properties: topic_id: type: string format: uuid description: >- The topic row's id (the value `jump_to_topic_id` takes on a test run). title: type: string description: type: string status: type: string enum: - open - resolved - dismissed - skipped description: > "open" while the topic still has to be covered; "resolved" or "dismissed" once it no longer is. The interview auto-completes when no topic is left open. "skipped" (test runs only): the tester deliberately left the topic out — a choice, not a gap. skill_id: type: string nullable: true description: >- Standard-guide skill backing the topic; null for custom topics. campaign: allOf: - $ref: '#/components/schemas/InterviewCampaignRef' nullable: true readOnly: true description: Campaign this interview belongs to; null for ad hoc interviews. campaign_id: type: string format: uuid nullable: true writeOnly: true description: > PATCH-only: 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. campaign_name: type: string writeOnly: true description: > PATCH-only alternative to `campaign_id`: move the interview to the campaign with this name, creating it if the project has none (matched case-insensitively). `campaign_id` wins when both are sent. is_first_interview: type: boolean readOnly: true description: > True while the requesting user has never started an assigned interview in this project. Drives the intro card's expanded "how it works" explainer. import_info: allOf: - $ref: '#/components/schemas/ImportedInterviewInfo' nullable: true readOnly: true meeting_info: allOf: - $ref: '#/components/schemas/MeetingInfo' nullable: true readOnly: true conversation_summary: type: string readOnly: true description: >- Background-generated summary of the conversation ("" until generated). feedback_state: type: string readOnly: true enum: - none - submitted description: | Whether the interviewee has rated this interview. Drives whether the post-interview feedback prompt is shown. The grade and comment themselves are Clarifeye-internal and are never returned. test_run: allOf: - $ref: '#/components/schemas/InterviewTestRun' nullable: true readOnly: true description: > Set when this conversation is a test run of an unsent draft (CLA-1834); null for real interviews. Adds `draft_id`, `draft_name`, `draft_edit_url`. available_translations: type: array readOnly: true description: > ISO codes of the languages this transcript has a complete cached machine translation in (see the `translate` / `translations` endpoints). The translated text itself is never part of the interview payload. items: type: string language: type: string nullable: true readOnly: true description: > ISO language code the assigner set for this interview (null = adapt to the respondent). Fixed by the assign / test-run endpoints; the respondent's own choice goes through `respondent_language`. respondent_language: type: string nullable: true description: > ISO language code the respondent picked for this interview — on the type-or-talk card before Clara's first message (CLA-1884), or later from the language selector (CLA-1933). Outranks every other language candidate for both the text prompt and the voice agent; never written back to the user's preference. A change applies to the next typed reply or the next call (a call in progress keeps its language). PATCHable only by the person answering or a project admin (403 otherwise), and only until the interview is completed (400 otherwise). Null clears it (auto-detect); unsupported codes are rejected (400). default_language: type: string nullable: true readOnly: true description: > Detail payload only. The ISO code the interview would be conducted in for the requesting user if `respondent_language` is left alone — respondent pick, else the user's preferred language, else their org-membership language, else `language`; null when nothing resolves (Clara mirrors the respondent). live_voice_available: type: boolean nullable: true readOnly: true description: > Detail payload only (CLA-1784). Whether the organization owning THIS knowledge store may take interviews as calls: the instance-wide `LIVE_VOICE_ENABLED` + ElevenLabs key ANDed with the org's `allow_live_voice`. Store-scoped, unlike the `instance_flags.live_voice_enabled` twin on the user payload, which answers for the reader's *active* org — a respondent who also belongs to an org of their own has a different one. Null outside detail payloads; treat null as "not asked", never as "off". `POST .../voice-call/` returns 503 when this is false. status: type: string nullable: true readOnly: true enum: - pending - in_progress - completed description: Null for imported interviews until their transcript parse completes. created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true InterviewInviteConfig: type: object description: > Invitation-email customization and reminder schedule for an assigned interview. Null for self-assigned interviews, non-interview conversations, and interviews created before this feature existed. readOnly: true properties: custom_message: type: string description: >- The assigner's note; replaces the default invitation email copy when set. custom_focus: type: string nullable: true description: > The assigner's override of the email's "what it's about" focus block. Null means not customised (emails show the truncated topic); empty string means the block was removed; text is shown verbatim. scheduled_send_at: type: string format: date-time nullable: true description: >- When the invitation email is (or was) due to be sent. Null means it was sent immediately. invitation_email_sent_at: type: string format: date-time nullable: true description: >- When the invitation email actually went out; null while a scheduled send is still pending. reminders_enabled: type: boolean reminder_start_after_days: type: integer reminder_interval_days: type: integer reminder_max_count: type: integer reminders_sent: type: integer description: Automatic reminders sent so far (manual reminders are not counted). next_reminder_at: type: string format: date-time nullable: true description: >- When the next automatic reminder is due; null when none is scheduled. reminders_stopped: type: boolean description: True once an admin/assigner stopped the schedule via stop-reminders. InterviewCampaignRef: type: object description: Nested campaign reference carried by interviews and drafts. properties: id: type: string format: uuid name: type: string ImportedInterviewInfo: type: object description: > Parse-pipeline state of an imported external transcript (interviews of type "imported-interview"). Null on every other interview type. The raw pasted transcript is never returned — the parsed `chat_history` is the transcript. properties: import_status: type: string enum: - parsing - ready - failed description: > "parsing" while the async parse runs (transcript not yet readable), "ready" once chat_history holds the speaker-labeled turns (status becomes "completed"), "failed" when parsing errored (use retry-import). participants: type: array description: >- Participant names (importer-supplied or inferred from the transcript). items: type: string interview_date: type: string format: date nullable: true description: Date the conversation happened (importer-supplied or inferred). error: type: string nullable: true description: Failure detail when import_status is "failed". MeetingInfo: type: object description: > Set on conversations of type `meeting` — the transcript of a call Clara attended as a bot (CLA-1843). The conversation is created post-call, so this block is always complete when present. Every turn of such a transcript is `role: user` with a `speaker` name and a `meeting_offset_ms`; attribute by speaker. properties: meeting_id: type: string format: uuid platform: type: string enum: - google_meet - zoom - microsoft_teams participants: type: array items: type: object properties: id: type: string name: type: string is_host: type: boolean duration_ms: type: integer nullable: true started_at: type: string format: date-time nullable: true url: type: string nullable: true description: Relative in-app path of the meeting page (recording, insights). InterviewTestRun: type: object description: > A rehearsal of an unsent draft (CLA-1834): an ordinary interview conversation the admin plays through themselves, listed only under its draft. It is kept when the draft is sent or deleted. Topics in `skipped_topic_ids` were deliberately left out of the run (started later / jumped ahead) — they are choices, not gaps. On a conversation detail (`test_run`) the object additionally carries `draft_id`, `draft_name`, `draft_edit_url`, `draft_source_session` and a `note` for agent readers. properties: id: type: string format: uuid status: type: string nullable: true enum: - pending - in_progress - completed language: type: string nullable: true description: >- ISO code the run is conducted in (outranks the tester's preference); null = auto-detect. started_from_topic_index: type: integer started_from_topic_title: type: string nullable: true skipped_topic_ids: type: array items: type: string format: uuid jumps: type: array items: type: object properties: from_topic_id: type: string format: uuid nullable: true to_topic_id: type: string format: uuid at_message_count: type: integer message_count: type: integer description: >- Conversation-detail flavour only (drafts list runs without their transcripts). draft_changed_since_start: type: boolean description: > The draft's interview-shaping fields (focus, topics, questions, language) changed after this run began — it rehearsed a previous version. Re-saving the draft unchanged, or starting another run, does not set it. interview_url: type: string description: Absolute URL of the run's focused interview page. draft_source_session: allOf: - $ref: '#/components/schemas/InterviewDraftSourceSession' nullable: true description: >- Conversation-detail flavour only. The session that drafted the interview, so the test page can resume it for feedback. created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object properties: error: type: string description: Error message example: error: User not found ValidationError: type: object additionalProperties: type: array items: type: string example: email: - This field is required. InterviewDraftSourceSession: type: object description: > The Clara session that created a draft (provenance, SET_NULL on both ends). `kind` decides the route a client builds: `clara_fast` = in-process Work with Clara conversation (`/agent/clara-fast?conversation_id=`), `cma` = Managed-Agents Clara session (`/agent/clara?session_id=`), `coach` = any other coach conversation (e.g. scoping), recorded but not linked from the test page. properties: kind: type: string enum: - clara_fast - cma - coach id: type: string format: uuid name: type: string nullable: true responses: BadRequest: description: Bad request - invalid parameters or request body content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Unauthorized: description: Unauthorized - missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Authentication credentials were not provided. Forbidden: description: Forbidden - insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: You do not have permission to perform this action. NotFound: description: Not found - resource does not exist content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Not found. securitySchemes: BearerAuth: type: http scheme: bearer description: > Use `Authorization: Bearer `. The token is either a user token / OAuth access token, or a service-account API key (`cfk_...`). A key is valid on every endpoint and acts as its service account, an organization member with per-store permissions. Refused keys answer 403 with `Invalid API key.`, `API key revoked.`, `API key expired.` or `API key disabled.`. TokenAuth: type: apiKey in: header name: Authorization description: 'Use Authorization: Token ' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.