---
title: "Run one turn of a v2 conversation"
method: POST
path: "/v1/v2/conversations/{conversation_id}/turns"
tags: ["runtime v2"]
---

# Run one turn of a v2 conversation

`POST /v1/v2/conversations/{conversation_id}/turns`

## Path parameters

- `conversation_id` string, uuid, required

## Request body

- TurnRequest — Drive one turn of a v2 conversation (Phase F1).
  - `user_message` string, required
  - `for_update` boolean
  - `include_evidence` boolean
  - `evidence_view` 'display' | 'full'

## Response `201`

Successful Response

- SrcRuntimeConversationSchemasTurnResponse — The outcome of one driven turn — mirrors ``driver.TurnResult``.
  - `turn_id` string, uuid, required
  - `conversation_id` string, uuid, required
  - `text` string, required
  - `active_assistant_id` string, uuid, nullable, required
  - `path` string, required
  - `decision_source` string, required
  - `message_seqs` integer[], required
  - `session_status` string, required
  - `turn_ttft_ms` integer, nullable
  - `ended` boolean
  - `evidence` union
    - EvidencePackageDisplay — End-user serialization view — source cards only, NO audit internals. A distinct model (not :class:`EvidencePackage` with a narrower config) so the omitted fields are absent from the schema, and so ``view`` yields a clean tagged union. ``organization_id``, ``agent_id`` and ``status_reason`` are full-only and intentionally not present here.
      - `view` 'display'
      - `schema_version` integer
      - `package_id` string, uuid, required
      - `conversation_id` string, uuid, required
      - `message_id` string, uuid, nullable
      - `turn_id` string, uuid, required
      - `created_at` string, date-time, required
      - `evidence_status` 'complete' | 'partial' | 'failed' | 'not_applicable', required
      - `items` EvidenceItemDisplay[], required
        - `citation_marker` string, nullable
        - `label` string, nullable
        - `short_label` string, nullable
        - `document_title` string, nullable
        - `version_number` integer, nullable
        - `section` EvidenceSection — A document section path — never a fabricated ``§N``.
          - `path_titles` string[], nullable
          - `path_numbers` string[], nullable
          - `display_label` string, nullable
          - `confidence` 'parsed' | 'derived' | 'unknown'
        - `deep_link` string, nullable
    - EvidencePackageFull — Staff/audit serialization view — the full envelope plus a ``view`` tag. Adds only the ``full`` discriminator literal; every audit field (scores/basis/band, ``rag_query_id``, chunk ids, hashes, constraints, ``status_reason``) rides through unchanged from :class:`EvidencePackage`.
      - `schema_version` integer
      - `package_id` string, uuid, required
      - `organization_id` string, uuid, required
      - `conversation_id` string, uuid, required
      - `message_id` string, uuid, nullable
      - `turn_id` string, uuid, required
      - `agent_id` string, uuid, nullable
      - `created_at` string, date-time, required
      - `evidence_status` 'complete' | 'partial' | 'failed' | 'not_applicable', required
      - `status_reason` 'complete' | 'no_kb_used' | 'no_exposed_chunks' | 'answerability_suppressed' | 'partial_missing_source_rows' | 'item_cap_applied' | 'build_failed', nullable
      - `items` EvidenceItem[], required
        - `evidence_id` string, uuid, required
        - `rag_query_id` string, uuid, nullable
        - `attribution_level` 'exposed'
        - `prompt_order` integer, nullable
        - `provenance` EvidenceProvenance, required
          - `kb_id` string, uuid, required
          - `kb_name` string, nullable
          - `document_id` string, uuid, required
          - `document_title` string, required
          - `version_id` string, uuid, nullable
          - `version_number` integer, nullable
          - `source_type` string, required
          - `source_provider` string, nullable
          - `deep_link` string, nullable
          - `filename` string, nullable
          - `section` EvidenceSection — A document section path — never a fabricated ``§N``.
            - `path_titles` string[], nullable
            - `path_numbers` string[], nullable
            - `display_label` string, nullable
            - `confidence` 'parsed' | 'derived' | 'unknown'
          - `chunk_id` string, required
          - `chunk_index` integer, nullable
          - `content_sha256` string, nullable
          - `last_processed_at` string, date-time, nullable
        - `position` EvidencePosition
          - `type` 'text'
          - `start_char` integer, nullable
          - `end_char` integer, nullable
        - `score` EvidenceScore — Relevance signal — NOT a probability (``calibrated=False`` always in v1).
          - `retrieval_score_raw` number, nullable
          - `retrieval_score_display` number, nullable
          - `score_basis` 'raw_hybrid_dotproduct' | 'minmax_normalized' | 'reranked_original_score' | 'grouped_unranked', required
          - `band` 'high' | 'medium' | 'low' | 'unknown'
          - `calibrated` boolean
        - `usage_constraints` EvidenceUsageConstraints — Carried, not enforced (v1).
          - `sensitivity` 'public' | 'internal' | 'confidential' | 'restricted', nullable
          - `sensitivity_level` integer, nullable
          - `visibility_mode` 'org_wide' | 'audience', nullable
          - `audience_tags` string[], nullable
          - `constraint_source` 'acl_columns' | 'metadata' | 'none'
          - `raw` object, nullable
        - `display` EvidenceDisplay
          - `label` string, required
          - `short_label` string, nullable
          - `citation_marker` string, nullable
        - `source_trust` string, nullable
        - `scan_status` string, nullable
      - `view` 'full'

## Other responses

- `400` — Bad request
- `401` — Authentication required
- `404` — Resource not found
- `422` — Validation Error

---

[API](https://skmtc.net/oneloop-hq/apis/feather-api.md) · [All operations](https://skmtc.net/oneloop-hq/apis/feather-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oneloop-hq/feather-api/versions/888bdd5c076e/schema)