Skip to main content
POST
Edit a sent interview before its first answer

Authorizations

Authorization
string
header
required

Use Authorization: Bearer <token>. The token is either a user token / OAuth access token, or a service-account API key (cfk_...). A key is valid on every endpoint and acts as its service account, an organization member with per-store permissions. Refused keys answer 403 with Invalid API key., API key revoked., API key expired. or API key disabled..

Path Parameters

project_id
string<uuid>
required

UUID of the project

interview_id
string<uuid>
required

UUID of the interview to edit

Body

application/json
name
string
focus
string

What the interview is about. Cannot be blank.

topics
object[]
Maximum array length: 12
instructions
string

How Clara runs the session (interviewer-only). Empty removes them.

artifacts
object[]
language
string | null

ISO language code, or null for auto-detect.

planned_minutes
integer

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.

Required range: 5 <= x <= 180
surface
enum<string>
default:ui

Where the edit came from, for analytics only. The MCP server sends mcp.

Available options:
ui,
mcp

Response

The updated interview, plus the fields that actually changed.

A structured interview conversation, including its full transcript.

id
string<uuid>
read-only
can_edit
boolean
read-only

Whether an admin may still edit this sent interview (before its first answer).

not_editable_reason
string | null
read-only

Why the interview can no longer be edited (answered, completed, archived, test run, not guided); null while can_edit is true.

last_edited_at
string<date-time> | null
read-only

When an admin last edited this sent interview.

last_edited_by_email
string<email> | null
read-only
sent_from_draft_id
string<uuid> | null
read-only

The draft this interview was sent from, when it was sent from one.

name
string | null

Interview title (auto-generated from the topic when not provided).

created_by
string<uuid>
read-only

UUID of the user who created the interview.

created_by_email
string<email> | null
read-only

Email of the user who created the interview (the importer, for imported interviews).

type
string

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
object

Free-form parameters associated with the conversation type. Assigned interviews carry planned_minutes (the planned length) among them.

chat_history
object[]

Ordered list of transcript entries (messages, tool calls, etc.).

chat_participants
object
read-only

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.

chat_memory
object

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
object[]
read-only

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.

assigned_to
string<uuid> | null
read-only

UUID of the assigned user (null while a pending invite has not yet joined).

assigned_by
string<uuid> | null
read-only

UUID of the user who created the assignment.

assigned_to_email
string<email> | null
read-only

Assignee email, falling back to the invite email for not-yet-joined invitees.

assigned_by_email
string<email> | null
read-only
is_pending_invite
boolean
read-only

True when assigned to someone who has not yet joined the project.

invite_config
object | null
read-only

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.

interview_focus
object | null
read-only

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).

topics
object[]
read-only

Guided interviews only: the ordered topic agenda seeded at send time, with per-topic progress. Empty for every other interview type.

campaign
object | null

Campaign this interview belongs to; null for ad hoc interviews.

is_first_interview
boolean
read-only

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
object | null

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.

meeting_info
object | null

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.

conversation_summary
string
read-only

Background-generated summary of the conversation ("" until generated).

feedback_state
enum<string>
read-only

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.

Available options:
none,
submitted
test_run
object | null

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
string[]
read-only

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.

language
string | null
read-only

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
string | null

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
string | null
read-only

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
boolean | null
read-only

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
enum<string> | null
read-only

Null for imported interviews until their transcript parse completes.

Available options:
pending,
in_progress,
completed
created_at
string<date-time>
read-only
updated_at
string<date-time>
read-only
updated_fields
string[]