> ## Documentation Index
> Fetch the complete documentation index at: https://doc.featherhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run one v2 conversation turn with an SSE response

> SSE counterpart to ``POST /v2/conversations/{id}/turns``.

Token streaming: the v2 ``ConversationTurnDriver`` runs the turn as one
read-modify-write transaction but now accepts an ``on_token`` callback that
the orchestrators/runnables fire as the *answer* streams (speculative losers
and transferring members are filtered upstream — a Supervisor buffers the
speculation and flushes only on ``continue``). We bridge that push-callback
to this pull-generator with an :class:`asyncio.Queue`: the driver runs as a
task that enqueues each token delta, and the generator drains the queue into
``delta`` frames as they arrive. When the driver finishes we emit a
``complete`` frame carrying the v2 ``TurnResponse`` JSON (including the
server-measured ``turn_ttft_ms``). The wire contract (``delta`` /
``complete`` / ``error`` frames) matches ``/v1/runtime/turn/stream`` so the
UI needs no change.

DB session lifecycle: the per-request ``session`` runs the org-scope check
and the turn (inside the driver task), and is committed before the
``complete`` frame so the FastAPI dependency teardown doesn't hold it open
across the response. The generator only touches the session after the driver
task has finished, so the two never race on it.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/v2/conversations/{conversation_id}/turns/stream
openapi: 3.1.0
info:
  title: Feather API
  description: >-
    Unified customer experience platform API. Manages identity, conversations,
    memory, agents, procedures, policies, model routing, knowledge bases,
    integrations, and runtime execution.
  version: 1.21.0
servers:
  - url: https://api-sandbox.featherhq.com
    description: Sandbox
  - url: http://localhost:8000
    description: Local dev
security: []
paths:
  /v1/v2/conversations/{conversation_id}/turns/stream:
    post:
      tags:
        - runtime v2
      summary: Run one v2 conversation turn with an SSE response
      description: >-
        SSE counterpart to ``POST /v2/conversations/{id}/turns``.


        Token streaming: the v2 ``ConversationTurnDriver`` runs the turn as one

        read-modify-write transaction but now accepts an ``on_token`` callback
        that

        the orchestrators/runnables fire as the *answer* streams (speculative
        losers

        and transferring members are filtered upstream — a Supervisor buffers
        the

        speculation and flushes only on ``continue``). We bridge that
        push-callback

        to this pull-generator with an :class:`asyncio.Queue`: the driver runs
        as a

        task that enqueues each token delta, and the generator drains the queue
        into

        ``delta`` frames as they arrive. When the driver finishes we emit a

        ``complete`` frame carrying the v2 ``TurnResponse`` JSON (including the

        server-measured ``turn_ttft_ms``). The wire contract (``delta`` /

        ``complete`` / ``error`` frames) matches ``/v1/runtime/turn/stream`` so
        the

        UI needs no change.


        DB session lifecycle: the per-request ``session`` runs the org-scope
        check

        and the turn (inside the driver task), and is committed before the

        ``complete`` frame so the FastAPI dependency teardown doesn't hold it
        open

        across the response. The generator only touches the session after the
        driver

        task has finished, so the two never race on it.
      operationId: runV2ConversationTurnStream
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Conversation Id
        - name: trace
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Trace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TurnRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    TurnRequest:
      properties:
        user_message:
          type: string
          title: User Message
        for_update:
          type: boolean
          title: For Update
          default: false
        include_evidence:
          type: boolean
          title: Include Evidence
          default: false
        evidence_view:
          type: string
          enum:
            - display
            - full
          title: Evidence View
          default: display
      type: object
      required:
        - user_message
      title: TurnRequest
      description: Drive one turn of a v2 conversation (Phase F1).
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        message:
          type: string
          title: Message
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Standard error response returned by all API error handlers.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````