> ## 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. # Create an interview draft > 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). ## OpenAPI ````yaml /api-reference/openapi-full.yaml post /projects/{project_id}/interview-drafts/ openapi: 3.0.3 info: title: Clarifeye Platform API — Full API Documentation description: > Complete REST API reference for the Clarifeye Platform. Documents every endpoint exposed by the platform — the public surface plus the advanced surface: pipeline customization (extraction flows, pipeline runs, warehouse tables, document tag/metadata configuration), the pre-MCP AI surface (agent settings, playground conversations, conversation-scoped feedback views, notifications), and the impersonation header. New AI integrations should consume knowledge via MCP rather than the conversation/agent-settings endpoints documented here. ## Authentication All endpoints require authentication. Include the Authorization header in every request using either format: - `Authorization: Token ` - `Authorization: Bearer ` ## Organization API Key Authentication The user-provisioning endpoints authenticate with an **org-scoped API key** instead of a user token: - `Authorization: Api-Key ` The key is minted internally by Clarifeye (not self-service) and is scoped to a single organization — it can only act on the organization whose UUID matches the `{id}` in the request path. The email domains a key may pre-create accounts for are configured by Clarifeye on the organization (`allowed_provisioning_domains`). Once you have a key and your domains are set, call `POST /organizations/{id}/provision-user/` to pre-create users and `POST /organizations/{id}/deprovision-user/` to remove them. ## Impersonation Certain endpoints support user impersonation for creating or listing data on behalf of other users. This is useful for integrating external systems that need to attribute actions to specific users. **Header:** `X-Impersonate-Email` **Required Permission:** `CAN_IMPERSONATE_OTHER_USERS` (contact Clarifeye to enable this permission) **Behavior:** - If the header is provided and the impersonator has the required permission, the action is performed as the target user - If the target user is not found, the request proceeds as the original authenticated user - If the target user does not have access to the project, the request proceeds as the original authenticated user - If the impersonator lacks the `CAN_IMPERSONATE_OTHER_USERS` permission, the header is ignored version: 1.0.0 contact: name: Clarifeye Support servers: - url: https://eu.app.clarifeye.ai/api/v1 description: EU - url: https://us.app.clarifeye.ai/api/v1 description: US security: - BearerAuth: [] - TokenAuth: [] tags: - name: Users description: Manage users within a project - name: Invitations description: Manage project invitations - name: Documents description: Manage documents within a project - name: Agent Settings description: Manage AI agent configurations - name: Conversations description: Create and interact with AI-powered conversations - name: Interviews description: Assign and review structured interview conversations - name: Feedback description: >- Submit and review feedback — standalone (content-only), agent-submitted (MCP), or linked to a conversation message - name: Tools description: Execute configured AI tools with custom parameters - name: Tables description: Perform CRUD operations on warehouse tables - name: Notifications description: Manage project-scoped notifications for users - name: Extraction Flows description: >- Manage extraction flows (auto-sync DAGs) — list, run, inspect statistics, update, and publish - name: Object Extractors description: | Extract structured data (instances of a Pydantic model) from chunks or blocks of documents. Update auto-creates a new `ObjectExtractorVersion` when version-bearing fields change. - name: Tag Extractors description: | Apply hierarchical metadata tags to chunks or documents using an LLM. Update auto-creates a new `TagExtractorVersion` when version-bearing fields change. - name: Chunks Extractors description: | Segment parsed documents into chunks for downstream processing. Update auto-creates a new `ChunksExtractorVersion` when version-bearing fields change. - name: Parsing Extractors description: | Convert source documents to text blocks via the parsing pipeline. Update auto-creates a new `ParsingExtractorVersion` when version-bearing fields change. - name: Document Filter Extractors description: | Restrict a downstream pipeline branch to documents matching a filter. Update auto-creates a new version when the filter changes. - name: Chunk Tag Filter Extractors description: | Restrict a downstream pipeline branch to chunks carrying specific tags. Update auto-creates a new version when the filter changes. - name: Document Tag Extractors description: | Apply a flat set of metadata tags to each document. Update auto-creates a new version when version-bearing fields change. - name: Tag Alerts Extractors description: | Run LLM-based alerts over already-extracted tag rows. Update auto-creates a new version when version-bearing fields change. - name: Object Alerts Extractors description: > Run LLM-based alerts over already-extracted object rows. Update auto-creates a new version when version-bearing fields change. - name: Imported Object Extractors description: | Hold objects imported from an external system (rather than extracted by an LLM). Useful for hydrating the warehouse with data produced outside the platform. - name: Pipeline Runs description: >- Inspect pipeline runs queued by extraction flows or other pipeline triggers — list runs and fetch the details/status of a single run - name: User Provisioning description: > Pre-create and de-provision org users via an org-scoped API key (`Authorization: Api-Key `). The organization is resolved from the key. - name: Organization API Keys description: > Superuser management of org-scoped provisioning API keys. Minting and revoking are superuser-only; org admins can list/retrieve/reveal their own org's keys. - name: Design System Templates description: Reference/example files attached to a design template. paths: /projects/{project_id}/interview-drafts/: post: tags: - Interviews summary: Create an interview draft description: > 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). operationId: createInterviewDraft parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InterviewDraftInput' responses: '201': description: Draft created content: application/json: schema: $ref: '#/components/schemas/InterviewDraft' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: ProjectId: name: project_id in: path required: true description: UUID of the project schema: type: string format: uuid schemas: InterviewDraftInput: type: object description: > Writable fields of an interview draft. Everything is optional — drafts are deliberately permissive and only sending (assign with `draft_id`) enforces the real assignment rules. properties: topic: type: string description: The interview focus. When set, a short title is generated from it. interview_type: type: string enum: - interview - guided-interview default: interview description: > Which conversation type the draft fans out to when sent. Set at creation (form type cards, or the scoping conversation's draft tool) and immutable afterwards — updates that change it are rejected (400). questions: type: array description: | Optional specific topics or questions (max 10). Rejected on guided-interview drafts — their `topics` structure the conversation. items: type: string topics: type: array description: > Guided drafts only (rejected otherwise): the ordered, editable topics the interview walks through (max 12). The scoping conversation's draft tool pre-seeds them from the standard guide. items: $ref: '#/components/schemas/GuidedInterviewTopic' assignee_ids: type: array description: >- UUIDs of project members to interview. May go stale; re-validated at send. items: type: string format: uuid invite_emails: type: array description: >- Emails of people not yet on the project. Nobody is contacted until the draft is sent. items: type: string format: email write_scope: type: string enum: - local - global default: local focused_mode: type: boolean default: false description: > Simplified interview: recipients open the distraction-free full-page chat instead of the app. Best for external or mobile respondents. language: type: string nullable: true description: > ISO language code (e.g. `fr`) the interviews created from this draft must be conducted in. Null (the default) adapts to each recipient's own preferred language. Unknown codes are rejected (400). custom_message: type: string description: Optional note replacing the default invitation email copy. scheduled_send_at: type: string format: date-time nullable: true reminders_enabled: type: boolean default: false reminder_start_after_days: type: integer minimum: 1 maximum: 30 default: 2 reminder_interval_days: type: integer minimum: 1 maximum: 30 default: 3 reminder_max_count: type: integer minimum: 1 maximum: 10 default: 3 campaign_id: type: string format: uuid nullable: true writeOnly: true description: > Existing campaign (of the same project) to group the draft's interviews under; null removes the draft from its campaign. Wins over `campaign_name` when both are sent. campaign_name: type: string writeOnly: true description: | Campaign to group the draft's interviews under, by name: reuses the project's campaign with that name (case-insensitive) or creates it. InterviewDraft: allOf: - $ref: '#/components/schemas/InterviewDraftInput' - type: object description: > A saved, unsent interview-assignment payload. Becomes one interview per recipient when sent via the assign endpoint (with `draft_id`), which also deletes the draft. properties: id: type: string format: uuid readOnly: true name: type: string readOnly: true description: > Title generated from the topic at save time; empty when the draft has no topic (clients show "Untitled draft interview"). campaign: allOf: - $ref: '#/components/schemas/InterviewCampaignRef' nullable: true readOnly: true description: > Campaign the interviews created from this draft will belong to; null when none. Set via `campaign_id` / `campaign_name`. created_by: type: string format: uuid nullable: true readOnly: true created_by_email: type: string format: email nullable: true readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true GuidedInterviewTopic: type: object description: > One ordered topic of a guided interview. `skill_id` identifies a topic backed by a built-in skill from the standard guide and round-trips through edits: when editing and resending default-guide topics, preserve the `skill_id` values you received so the topics keep their skill-backed interview depth. Omit `skill_id` for hand-added custom topics, which are driven by their own title/description text. required: - title properties: title: type: string maxLength: 200 description: type: string skill_id: type: string nullable: true InterviewCampaignRef: type: object description: Nested campaign reference carried by interviews and drafts. properties: id: type: string format: uuid name: type: string Error: type: object properties: error: type: string description: Error message example: error: User not found ValidationError: type: object additionalProperties: type: array items: type: string example: email: - This field is required. responses: BadRequest: description: Bad request - invalid parameters or request body content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Unauthorized: description: Unauthorized - missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Authentication credentials were not provided. Forbidden: description: Forbidden - insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: You do not have permission to perform this action. 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 ' TokenAuth: type: apiKey in: header name: Authorization description: 'Use Authorization: Token ' ````