---
title: "Create Question Operation"
method: POST
path: "/v1/question-operations"
tags: ["Public API v1"]
---

# Create Question Operation

`POST /v1/question-operations`

## Request

- Base URL: `https://api.corvio.ai`
- URL: `https://api.corvio.ai/v1/question-operations`
- Auth: HTTP bearer

Start a durable Question without tying its lifetime to this HTTP request.

## Headers

- `Idempotency-Key` string, nullable
- `X-Corvio-Caller-Model` string, nullable
- `X-Corvio-Client-Name` string, nullable
- `X-Corvio-Client-Version` string, nullable

## Request body

- PublicQuestionRequest
  - `prompt` string, required
  - `conversation_id` string, uuid, nullable
  - `asset_ids` string[]: Existing Corvio Workspace Assets to attach to this question. Upload local bytes first, then pass the finalized Asset IDs here.
  - `inline_materials` PublicInlineMaterial[]: Current-turn Markdown composed by the calling host and selected as source material for this question. Original local files belong in finalized Assets instead.
    - `title` string, required
    - `content_markdown` string, required
    - `expected_content_sha256` string, nullable: Optional SHA-256 computed by the calling Host from the exact UTF-8 Markdown bytes before this request. Corvio rejects a mismatch. This checks transport integrity; it does not prove who authored the source.
  - `mode` 'answer_only' | 'allow_actions': answer_only forbids Workspace and durable-learning writes. Use allow_actions for authorized document/Work Model changes and for evidence-based Memory/Skill closure.
  - `sources` string[]
  - `processing_profile` 'auto' | 'economy' | 'standard' | 'deep'
  - `max_processing_profile` 'economy' | 'standard' | 'deep', nullable
  - `scan_mode` 'auto' | 'always' | 'off'
  - `skills_extraction_mode` 'auto' | 'always' | 'off'
  - `context` object, nullable

## Response `202`

Successful Response

- PublicQuestionOperationResponse
  - `operation_id` string, uuid, required
  - `object` 'question_operation'
  - `status` 'queued' | 'running' | 'needs_user_input' | 'succeeded' | 'failed' | 'cancelled', required
  - `phase` string, required
  - `status_message` string, required
  - `question_id` string, uuid, nullable
  - `conversation_id` string, uuid, nullable
  - `progress` PublicQuestionProgressEvent[]
    - `cursor` integer, required
    - `phase` string, required
    - `status` string, required
    - `message` string, nullable
    - `occurred_at` string, date-time, nullable
  - `progress_cursor` integer
  - `progress_has_more` boolean
  - `retry_after_seconds` integer, nullable
  - `cancellation_requested` boolean
  - `question` PublicQuestionResponse
    - `id` string, uuid, required
    - `object` 'question'
    - `status` 'in_progress' | 'needs_user_input' | 'completed' | 'failed' | 'cancelled', required
    - `prompt` string, required
    - `answer` string, nullable
    - `conversation_id` string, uuid, required
    - `thread_id` string, uuid, required
    - `trace_id` string, nullable
    - `sources` PublicQuestionSource[]
      - `kind` string, required
      - `title` string, nullable
      - `url` string, nullable
      - `document_id` string, uuid, nullable
      - `asset_id` string, uuid, nullable
      - `node_id` string, uuid, nullable
      - `conversation_id` string, uuid, nullable
      - `question_id` string, uuid, nullable
      - `page_revision` integer, nullable
      - `heading_path` string[]
      - `quote` string, nullable
      - `locator` string, nullable
    - `source_document_ids` string[]
    - `artifacts` PublicQuestionArtifact[]
      - `id` string, required: Canonical workspace_uuid/page_uuid handle accepted by document read and mutation tools.
      - `kind` string, required
      - `structural_kind` string, nullable: Live tree kind. Only project proves a structural Project; a Page may have doc_type/project semantics without owning Project ancestry.
      - `role` 'reader_output' | 'structure_container', required
      - `document_id` string, uuid, required
      - `node_id` string, uuid, required
      - `parent_node_id` string, uuid, nullable
      - `project_ancestor_node_id` string, uuid, nullable: Nearest live Project ancestor, including the artifact itself when it is a Project. Null means no complete live Project ancestry was verified.
      - `title` string, required
      - `content_revision` integer, required
      - `readback_verified` boolean, required: True when Corvio re-resolved this live object for the terminal response and the returned identity, kind, title, revision, parent, and URL are current. This does not inline or attest every body claim; read the body only when exact wording can change acceptance.
      - `url` string, required
    - `operations` PublicQuestionOperation[]
      - `name` string, required
      - `status` string, required
      - `summary` string, nullable
      - `detail` string, nullable
    - `clarification` PublicQuestionClarification
      - `session_id` string, required
      - `title` string, nullable
      - `intro` string, nullable
      - `submit_label` string, nullable
      - `final_optional_note` string, nullable
      - `questions` PublicQuestionClarificationItem[]
        - `id` string, required
        - `question` string, required
        - `mode` 'single_choice' | 'multiple_choice', required
        - `required` boolean
        - `options` PublicQuestionClarificationOption[]
          - `key` string, required
          - `label` string, required
          - `detail` string, nullable
        - `allow_note` boolean
        - `note_label` string, nullable
        - `note_placeholder` string, nullable
    - `answer_blocks` object[]
    - `usage` object
    - `execution` object: Durable execution receipt including caller origin, requested/effective processing profile, the scan/Skill-evaluation knowledge policy, and bounded Memory/Skill review and execution outcomes when this Question performed durable learning.
    - `error` object, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `links` object, required
  - `error` object, nullable
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable
  - `links` object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/corvio/apis/corvio-developer-api.md) · [All operations](https://skmtc.dev/corvio/apis/corvio-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/corvio/apis/corvio-developer-api/revisions/a5a77bb9619c?raw)