Run one v2 conversation turn with an SSE response

SSE counterpart to POST /conversations/{id}/turns.

Token streaming: the v2 ConversationTurnDriver prepares a snapshot, computes without a checked-out connection, and then finalizes atomically. It 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 commits admission before the response is constructed, is connection-free while the driver task computes, and commits finalization before the complete frame. The generator only touches the session after the driver task has finished, so the two never race on it.

POST

conversations

{conversation_id}

turns

stream

Run one v2 conversation turn with an SSE response

curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_message": "<string>",
  "for_update": false,
  "include_evidence": false,
  "evidence_view": "display"
}
'

import requests

url = "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream"

payload = {
    "user_message": "<string>",
    "for_update": False,
    "include_evidence": False,
    "evidence_view": "display"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_message: '<string>',
    for_update: false,
    include_evidence: false,
    evidence_view: 'display'
  })
};

fetch('https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_message' => '<string>',
    'for_update' => false,
    'include_evidence' => false,
    'evidence_view' => 'display'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream"

	payload := strings.NewReader("{\n  \"user_message\": \"<string>\",\n  \"for_update\": false,\n  \"include_evidence\": false,\n  \"evidence_view\": \"display\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_message\": \"<string>\",\n  \"for_update\": false,\n  \"include_evidence\": false,\n  \"evidence_view\": \"display\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_message\": \"<string>\",\n  \"for_update\": false,\n  \"include_evidence\": false,\n  \"evidence_view\": \"display\"\n}"

response = http.request(request)
puts response.read_body

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

Authorizations

x-api-key

string

header

required

Path Parameters

conversation_id

string<uuid>

required

Query Parameters

trace

boolean

default:false

Body

application/json

Drive one turn of a v2 conversation (Phase F1).

user_message

string

required

for_update

boolean

default:false

deprecated

Deprecated compatibility field; all turns use optimistic guarded finalization and this value has no effect.

include_evidence

boolean

default:false

evidence_view

enum<string>

default:display

Available options:

display,

full

Response

Successful Response

Run one v2 conversation turn with an SSE response

curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_message": "<string>",
  "for_update": false,
  "include_evidence": false,
  "evidence_view": "display"
}
'

import requests

url = "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream"

payload = {
    "user_message": "<string>",
    "for_update": False,
    "include_evidence": False,
    "evidence_view": "display"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_message: '<string>',
    for_update: false,
    include_evidence: false,
    evidence_view: 'display'
  })
};

fetch('https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_message' => '<string>',
    'for_update' => false,
    'include_evidence' => false,
    'evidence_view' => 'display'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream"

	payload := strings.NewReader("{\n  \"user_message\": \"<string>\",\n  \"for_update\": false,\n  \"include_evidence\": false,\n  \"evidence_view\": \"display\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_message\": \"<string>\",\n  \"for_update\": false,\n  \"include_evidence\": false,\n  \"evidence_view\": \"display\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/turns/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_message\": \"<string>\",\n  \"for_update\": false,\n  \"include_evidence\": false,\n  \"evidence_view\": \"display\"\n}"

response = http.request(request)
puts response.read_body

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}