---
title: "Ask Question"
method: POST
path: "/v1/questions"
tags: ["Public API v1"]
---

# Ask Question

`POST /v1/questions`

## Request

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

## Headers

- `Idempotency-Key` string, nullable
- `X-Corvio-Agent-Event-Id` string, uuid, nullable
- `X-Corvio-Agent-Event-Lease-Token` 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 `200`

Successful Response

- 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

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