Spec Desk — API

# Scripted: a guest token, no browser and no account.
curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"spec-desk"}'
# -> { "ok": true, "data": { "token": "...", "subject_type": "guest" } }

# Personal: open /tokens.html, press "Copy shell export", paste the line.
export SKILLSAFE_TOKEN="aut_xxxxxxxxxxxxxxxxxxxx"

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="$SKILLSAFE_TOKEN"

import json, os, urllib.request

BASE = "https://api.skillsafe.ai/v1/app-api"
TOKEN = os.environ.get("SKILLSAFE_TOKEN")

if not TOKEN:                                   # fall back to a scripted guest
    req = urllib.request.Request(
        BASE + "/guest",
        data=json.dumps({"slug": "spec-desk"}).encode(),
        headers={"Content-Type": "application/json"},
    )
    with urllib.request.urlopen(req) as r:
        TOKEN = json.load(r)["data"]["token"]

// Keep the token in a constant your build or your secret store injects.
// The token page at /tokens.html will show you yours and copy it for you --
// there is never a reason to fish one out of a developer console.
const BASE = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN";

// Or mint a scripted guest token, which can call /me and /estimate:
async function guestToken() {
  const res = await fetch(BASE + "/guest", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ slug: "spec-desk" })
  });
  const env = await res.json();
  if (!env.ok) throw new Error(env.error.code);
  return env.data.token;
}

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

const base = "https://api.skillsafe.ai/v1/app-api"

func token() string {
    if t := os.Getenv("SKILLSAFE_TOKEN"); t != "" {
        return t
    }
    res, err := http.Post(base+"/guest", "application/json",
        bytes.NewBufferString(`{"slug":"spec-desk"}`))
    if err != nil {
        return ""
    }
    defer res.Body.Close()
    var env struct {
        Data struct {
            Token string `json:"token"`
        } `json:"data"`
    }
    json.NewDecoder(res.Body).Decode(&env)
    return env.Data.Token
}

import java.net.URI;
import java.net.http.*;

public class SpecDesk {
    static final String BASE = "https://api.skillsafe.ai/v1/app-api";
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static String token() throws Exception {
        String t = System.getenv("SKILLSAFE_TOKEN");
        if (t != null && !t.isEmpty()) return t;

        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/guest"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("{\"slug\":\"spec-desk\"}"))
            .build();
        return HTTP.send(req, HttpResponse.BodyHandlers.ofString()).body();
        // an envelope: read data.token with the JSON library you already use
    }
}

require "json"
require "net/http"

BASE = "https://api.skillsafe.ai/v1/app-api"

TOKEN = ENV["SKILLSAFE_TOKEN"] || begin
  res = Net::HTTP.post(URI(BASE + "/guest"),
                       JSON.dump({ slug: "spec-desk" }),
                       "Content-Type" => "application/json")
  JSON.parse(res.body)["data"]["token"]
end

<?php
const BASE = "https://api.skillsafe.ai/v1/app-api";

$token = getenv("SKILLSAFE_TOKEN");
if (!$token) {                                  // scripted guest fallback
    $ch = curl_init(BASE . "/guest");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
        CURLOPT_POSTFIELDS     => json_encode(["slug" => "spec-desk"]),
    ]);
    $token = json_decode(curl_exec($ch), true)["data"]["token"];
    curl_close($ch);
}

using System.Text;
using System.Text.Json;

var BASE = "https://api.skillsafe.ai/v1/app-api";
var TOKEN = Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN");

if (string.IsNullOrEmpty(TOKEN))                 // scripted guest fallback
{
    var body = new StringContent("{\"slug\":\"spec-desk\"}", Encoding.UTF8, "application/json");
    var res = await new HttpClient().PostAsync(BASE + "/guest", body);
    var env = JsonDocument.Parse(await res.Content.ReadAsStringAsync()).RootElement;
    TOKEN = env.GetProperty("data").GetProperty("token").GetString();
}

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="$SKILLSAFE_TOKEN"

call() {   # call <path> <json-body>
  curl -sS -X POST "$BASE$1" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "$2"
}

get() {    # get <path>
  curl -sS "$BASE$1" -H "Authorization: Bearer $TOKEN"
}

def call(path, body=None, method="POST"):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(BASE + path, data=data, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req) as r:
        env = json.load(r)
    if not env.get("ok"):
        raise RuntimeError(env["error"]["code"] + ": " + env["error"]["message"])
    return env["data"]

async function call(path, body, method = "POST") {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: body === undefined ? undefined : JSON.stringify(body)
  });
  const env = await res.json();
  if (!env.ok) throw new Error(`${env.error.code}: ${env.error.message}`);
  return env.data;
}

import (
    "errors"
    "io"
)

type envelope struct {
    OK    bool            `json:"ok"`
    Data  json.RawMessage `json:"data"`
    Error *struct {
        Code    string `json:"code"`
        Message string `json:"message"`
    } `json:"error"`
}

func call(method, path string, body any) (json.RawMessage, error) {
    var r io.Reader
    if body != nil {
        b, _ := json.Marshal(body)
        r = bytes.NewReader(b)
    }
    req, _ := http.NewRequest(method, base+path, r)
    req.Header.Set("Authorization", "Bearer "+token())
    req.Header.Set("Content-Type", "application/json")
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()
    var env envelope
    if err := json.NewDecoder(res.Body).Decode(&env); err != nil {
        return nil, err
    }
    if !env.OK {
        return nil, errors.New(env.Error.Code + ": " + env.Error.Message)
    }
    return env.Data, nil
}

static String call(String path, String jsonBody) throws Exception {
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(BASE + path))
        .header("Authorization", "Bearer " + token())
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
        .build();
    HttpResponse<String> res = HTTP.send(req, HttpResponse.BodyHandlers.ofString());
    return res.body();   // a JSON envelope: { ok, data } or { ok, error }
}

static String get(String path) throws Exception {
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(BASE + path))
        .header("Authorization", "Bearer " + token())
        .GET()
        .build();
    return HTTP.send(req, HttpResponse.BodyHandlers.ofString()).body();
}

def call(path, body = nil, method = :post)
  uri = URI(BASE + path)
  klass = method == :get ? Net::HTTP::Get : Net::HTTP::Post
  req = klass.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  req["Content-Type"]  = "application/json"
  req.body = JSON.dump(body) if body
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  env = JSON.parse(res.body)
  raise "#{env["error"]["code"]}: #{env["error"]["message"]}" unless env["ok"]
  env["data"]
end

<?php
function call(string $path, ?array $body = null, string $method = "POST") {
    global $token;
    $ch = curl_init(BASE . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => [
            "Authorization: Bearer " . $token,
            "Content-Type: application/json",
        ],
    ]);
    if ($body !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    $env = json_decode(curl_exec($ch), true);
    curl_close($ch);
    if (empty($env["ok"])) {
        throw new RuntimeException($env["error"]["code"] . ": " . $env["error"]["message"]);
    }
    return $env["data"];
}

using System.Net.Http.Headers;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", TOKEN);

async Task<JsonElement> Call(string path, object? body = null)
{
    var content = new StringContent(JsonSerializer.Serialize(body ?? new { }),
                                    Encoding.UTF8, "application/json");
    var res = await http.PostAsync(BASE + path, content);
    var env = JsonDocument.Parse(await res.Content.ReadAsStringAsync()).RootElement;
    if (!env.GetProperty("ok").GetBoolean())
        throw new Exception(env.GetProperty("error").GetProperty("code").GetString());
    return env.GetProperty("data");
}

async Task<JsonElement> Get(string path)
{
    var res = await http.GetAsync(BASE + path);
    var env = JsonDocument.Parse(await res.Content.ReadAsStringAsync()).RootElement;
    if (!env.GetProperty("ok").GetBoolean())
        throw new Exception(env.GetProperty("error").GetProperty("code").GetString());
    return env.GetProperty("data");
}

get /me
# -> { "ok": true, "data": { "subject_type": "user", "credits": 250000 } }

me = call("/me", method="GET")
print(me["subject_type"], me["credits"])

const me = await call("/me", undefined, "GET");
console.log(me.subject_type, me.credits);

data, err := call("GET", "/me", nil)
if err != nil {
    log.Fatal(err)
}
var me struct {
    SubjectType string `json:"subject_type"`
    Credits     int    `json:"credits"`
}
json.Unmarshal(data, &me)
fmt.Println(me.SubjectType, me.Credits)

System.out.println(get("/me"));
// { "ok": true, "data": { "subject_type": "user", "credits": 250000 } }

me = call("/me", nil, :get)
puts me["subject_type"], me["credits"]

<?php
$me = call("/me", null, "GET");
echo $me["subject_type"], " ", $me["credits"], PHP_EOL;

var me = await Get("/me");
Console.WriteLine(me.GetProperty("subject_type").GetString());
Console.WriteLine(me.GetProperty("credits").GetInt32());

call /estimate "$(cat body.json)"
# body.json is { "input": { "task": "spec", ...the input object... } }
# -> { "ok": true, "data": { "model": "gpt-5.6-terra", "model_alias": "gpt-terra",
#                            "markup_bps": 1000, "hold_credits": 2100,
#                            "min_credits": 120, "sponsor_enabled": false } }

payload = {"input": app_input}          # app_input is the object above

est = call("/estimate", payload)
print(est["model"], est["model_alias"], est["markup_bps"], est["sponsor_enabled"])
if not est["sponsor_enabled"] and me["credits"] < est["min_credits"]:
    raise SystemExit("top up before running")
print("reserving up to", est["hold_credits"], "credits")

const payload = { input: appInput };

const est = await call("/estimate", payload);
if (!est.sponsor_enabled && me.credits < est.min_credits) {
  throw new Error("top up before running");
}
console.log(`reserving up to ${est.hold_credits} credits on ${est.model}`);

payload := map[string]any{"input": appInput}

data, err := call("POST", "/estimate", payload)
if err != nil {
    log.Fatal(err)
}
var est struct {
    Model          string `json:"model"`
    ModelAlias     string `json:"model_alias"`
    MarkupBps      int    `json:"markup_bps"`
    HoldCredits    int    `json:"hold_credits"`
    MinCredits     int    `json:"min_credits"`
    SponsorEnabled bool   `json:"sponsor_enabled"`
}
json.Unmarshal(data, &est)
if !est.SponsorEnabled && me.Credits < est.MinCredits {
    log.Fatal("top up before running")
}

String est = call("/estimate", payloadJson);
System.out.println(est);
// data: model, model_alias, markup_bps, hold_credits, min_credits, sponsor_enabled

payload = { input: app_input }

est = call("/estimate", payload)
abort("top up before running") if !est["sponsor_enabled"] && me["credits"] < est["min_credits"]
puts "reserving up to #{est["hold_credits"]} on #{est["model"]}"

<?php
$payload = ["input" => $appInput];

$est = call("/estimate", $payload);
if (!$est["sponsor_enabled"] && $me["credits"] < $est["min_credits"]) {
    exit("top up before running\n");
}
echo "reserving up to {$est["hold_credits"]} on {$est["model"]}\n";

var payload = new { input = appInput };

var est = await Call("/estimate", payload);
Console.WriteLine(est.GetProperty("model").GetString());
Console.WriteLine(est.GetProperty("hold_credits").GetInt32());
if (!est.GetProperty("sponsor_enabled").GetBoolean() &&
    me.GetProperty("credits").GetInt32() < est.GetProperty("min_credits").GetInt32())
{
    throw new Exception("top up before running");
}

KEY="spec-desk:spec:9f31c0ab:a1"

curl -sS -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  --data @body.json
# -> { "ok": true, "data": { "job_id": "job_...", "status": "queued" } }

get /jobs/job_xxxxxxxx
# poll until status is "succeeded" or "failed"; the result is data.output.output

import time

KEY = "spec-desk:spec:9f31c0ab:a1"

req = urllib.request.Request(BASE + "/run", data=json.dumps(payload).encode(), method="POST")
req.add_header("Authorization", "Bearer " + TOKEN)
req.add_header("Content-Type", "application/json")
req.add_header("Idempotency-Key", KEY)          # reuse this exact key on any retry
with urllib.request.urlopen(req) as r:
    job = json.load(r)["data"]

while True:
    j = call("/jobs/" + job["job_id"], method="GET")
    if j["status"] in ("succeeded", "failed"):
        break
    time.sleep(1.5)

if j["status"] == "failed":
    raise SystemExit(j.get("error", "the run failed"))

result = json.loads(j["output"]["output"])
print(result["lane"], "-", result["spec"]["readiness_verdict"])

const KEY = "spec-desk:spec:9f31c0ab:a1";

const job = await fetch(`${BASE}/run`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": KEY          // reuse this exact key on any retry
  },
  body: JSON.stringify(payload)
}).then(r => r.json()).then(e => {
  if (!e.ok) throw new Error(e.error.code);
  return e.data;
});

let j;
do {
  await new Promise(r => setTimeout(r, 1500));
  j = await call(`/jobs/${job.job_id}`, undefined, "GET");
} while (j.status !== "succeeded" && j.status !== "failed");

if (j.status === "failed") throw new Error("the run failed");
const result = JSON.parse(j.output.output);
console.log(result.lane, result.spec.requirements.length, "requirements");

const key = "spec-desk:spec:9f31c0ab:a1"

b, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", base+"/run", bytes.NewReader(b))
req.Header.Set("Authorization", "Bearer "+token())
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", key) // reuse this exact key on any retry
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

var env struct {
    Data struct {
        JobID string `json:"job_id"`
    } `json:"data"`
}
json.NewDecoder(res.Body).Decode(&env)

for {
    d, err := call("GET", "/jobs/"+env.Data.JobID, nil)
    if err != nil {
        log.Fatal(err)
    }
    var j struct {
        Status string `json:"status"`
        Output struct {
            Output string `json:"output"`
        } `json:"output"`
    }
    json.Unmarshal(d, &j)
    if j.Status == "succeeded" || j.Status == "failed" {
        // json.Unmarshal([]byte(j.Output.Output), &result)
        break
    }
    time.Sleep(1500 * time.Millisecond)
}

String KEY = "spec-desk:spec:9f31c0ab:a1";

HttpRequest run = HttpRequest.newBuilder()
    .uri(URI.create(BASE + "/run"))
    .header("Authorization", "Bearer " + token())
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", KEY)      // reuse this exact key on any retry
    .POST(HttpRequest.BodyPublishers.ofString(payloadJson))
    .build();
String job = HTTP.send(run, HttpResponse.BodyHandlers.ofString()).body();

// then poll GET /jobs/{job_id} until status is succeeded or failed,
// and parse data.output.output -- it is the result as a JSON *string*.
String polled = get("/jobs/" + jobId);

KEY = "spec-desk:spec:9f31c0ab:a1"

uri = URI(BASE + "/run")
req = Net::HTTP::Post.new(uri)
req["Authorization"]   = "Bearer #{TOKEN}"
req["Content-Type"]    = "application/json"
req["Idempotency-Key"] = KEY            # reuse this exact key on any retry
req.body = JSON.dump(payload)
job = JSON.parse(Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }.body)["data"]

j = nil
loop do
  j = call("/jobs/#{job["job_id"]}", nil, :get)
  break if %w[succeeded failed].include?(j["status"])
  sleep 1.5
end
abort("the run failed") if j["status"] == "failed"

result = JSON.parse(j["output"]["output"])
puts "#{result["lane"]} - #{result["spec"]["readiness_verdict"]}"

<?php
$key = "spec-desk:spec:9f31c0ab:a1";

$ch = curl_init(BASE . "/run");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . $token,
        "Content-Type: application/json",
        "Idempotency-Key: " . $key,     // reuse this exact key on any retry
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);
$job = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

do {
    sleep(2);
    $j = call("/jobs/" . $job["job_id"], null, "GET");
} while (!in_array($j["status"], ["succeeded", "failed"], true));

if ($j["status"] === "failed") {
    exit("the run failed\n");
}
$result = json_decode($j["output"]["output"], true);

var key = "spec-desk:spec:9f31c0ab:a1";

var runMsg = new HttpRequestMessage(HttpMethod.Post, BASE + "/run")
{
    Content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
};
runMsg.Headers.Add("Idempotency-Key", key);   // reuse this exact key on any retry
var runRes = await http.SendAsync(runMsg);
var jobId = JsonDocument.Parse(await runRes.Content.ReadAsStringAsync())
    .RootElement.GetProperty("data").GetProperty("job_id").GetString();

JsonElement j;
string status;
do
{
    await Task.Delay(1500);
    j = await Get("/jobs/" + jobId);
    status = j.GetProperty("status").GetString()!;
} while (status != "succeeded" && status != "failed");

if (status == "failed") throw new Exception("the run failed");
var result = JsonDocument.Parse(
    j.GetProperty("output").GetProperty("output").GetString()!).RootElement;

curl -N -sS -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  --data @body.json

# event: job
# data: {"job_id":"job_..."}
# event: delta
# data: {"text":"{\"lane\":\"spec\",\"title\":\"Teammate invites"}
# event: delta
# data: {"text":" during trial\",\"summary\":\"Trial accounts cannot"}
# event: done
# data: {"status":"succeeded","charged_credits":612,"truncated":false}

req = urllib.request.Request(BASE + "/run-stream", data=json.dumps(payload).encode())
req.add_header("Authorization", "Bearer " + TOKEN)
req.add_header("Content-Type", "application/json")
req.add_header("Idempotency-Key", KEY)

raw, event = "", None
with urllib.request.urlopen(req) as r:
    for line in r:
        line = line.decode().rstrip("\n")
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:") and event == "delta":
            raw += json.loads(line[5:])["text"]

result = json.loads(raw)

const res = await fetch(`${BASE}/run-stream`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": KEY
  },
  body: JSON.stringify(payload)
});

const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = "", raw = "", event = null;
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += dec.decode(value, { stream: true });
  const lines = buf.split("\n");
  buf = lines.pop();
  for (const line of lines) {
    if (line.startsWith("event:")) event = line.slice(6).trim();
    else if (line.startsWith("data:") && event === "delta") raw += JSON.parse(line.slice(5)).text;
  }
}
const result = JSON.parse(raw);

req, _ = http.NewRequest("POST", base+"/run-stream", bytes.NewReader(b))
req.Header.Set("Authorization", "Bearer "+token())
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", key)
res, _ = http.DefaultClient.Do(req)
defer res.Body.Close()

sc := bufio.NewScanner(res.Body)
var event, raw string
for sc.Scan() {
    line := sc.Text()
    switch {
    case strings.HasPrefix(line, "event:"):
        event = strings.TrimSpace(line[6:])
    case strings.HasPrefix(line, "data:") && event == "delta":
        var d struct{ Text string }
        json.Unmarshal([]byte(line[5:]), &d)
        raw += d.Text
    }
}
// raw is now the result as JSON text

HttpRequest stream = HttpRequest.newBuilder()
    .uri(URI.create(BASE + "/run-stream"))
    .header("Authorization", "Bearer " + token())
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", KEY)
    .POST(HttpRequest.BodyPublishers.ofString(payloadJson))
    .build();

StringBuilder raw = new StringBuilder();
String[] evt = { null };
HTTP.send(stream, HttpResponse.BodyHandlers.ofLines())
    .body()
    .forEach(l -> {
        if (l.startsWith("event:")) evt[0] = l.substring(6).trim();
        else if (l.startsWith("data:") && "delta".equals(evt[0]))
            raw.append(textOf(l.substring(5)));   // your JSON reader, field "text"
    });

uri = URI(BASE + "/run-stream")
req = Net::HTTP::Post.new(uri)
req["Authorization"]   = "Bearer #{TOKEN}"
req["Content-Type"]    = "application/json"
req["Idempotency-Key"] = KEY
req.body = JSON.dump(payload)

raw, event = +"", nil
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req) do |res|
    res.read_body do |chunk|
      chunk.each_line do |line|
        event = line[6..].strip if line.start_with?("event:")
        raw << JSON.parse(line[5..])["text"] if line.start_with?("data:") && event == "delta"
      end
    end
  end
end
result = JSON.parse(raw)

<?php
$raw = "";
$event = null;
$ch = curl_init(BASE . "/run-stream");
curl_setopt_array($ch, [
    CURLOPT_POST       => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $token,
        "Content-Type: application/json",
        "Idempotency-Key: " . $key,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$raw, &$event) {
        foreach (explode("\n", $chunk) as $line) {
            if (str_starts_with($line, "event:")) {
                $event = trim(substr($line, 6));
            } elseif (str_starts_with($line, "data:") && $event === "delta") {
                $raw .= json_decode(substr($line, 5), true)["text"] ?? "";
            }
        }
        return strlen($chunk);
    },
]);
curl_exec($ch);
$result = json_decode($raw, true);

var streamMsg = new HttpRequestMessage(HttpMethod.Post, BASE + "/run-stream")
{
    Content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
};
streamMsg.Headers.Add("Idempotency-Key", key);

var streamRes = await http.SendAsync(streamMsg, HttpCompletionOption.ResponseHeadersRead);
using var reader = new StreamReader(await streamRes.Content.ReadAsStreamAsync());
var raw = new StringBuilder();
string? evt = null, line;
while ((line = await reader.ReadLineAsync()) != null)
{
    if (line.StartsWith("event:")) evt = line[6..].Trim();
    else if (line.StartsWith("data:") && evt == "delta")
        raw.Append(JsonDocument.Parse(line[5..]).RootElement.GetProperty("text").GetString());
}
var result = JsonDocument.Parse(raw.ToString()).RootElement;

# bundle.json = { "input": {...as posted...}, "result": {...the parsed object...} }
jq '
  (.result.lane)                                        as $lane
| ([ "spec","roadmap","update" ] | map(select(.result[.] != null)))  as $present
| ((.result.spec.requirements // []) | map(.id))        as $ids
| ((.result.spec.acceptance_criteria // []) | map(.requirement_id)) as $refs
| ((.input.roadmap_facts.items // []) | map(.label))    as $labels
| ((.result.roadmap.bumped // []) | map(.item))         as $bumped
| { lane_ok:        ($present == [ $lane ]),
    orphan_criteria: ($refs - $ids | unique),
    invented_bumps:  ($bumped - $labels | unique) }
' bundle.json
# lane_ok true and both lists empty means the reply agrees with what you posted

lanes = ["spec", "roadmap", "update"]
present = [k for k in lanes if result.get(k) is not None]
if present != [result.get("lane")]:
    raise SystemExit(f"lane is {result.get('lane')} but {present} came back non-null")

spec = result.get("spec") or {}
ids = {r["id"] for r in spec.get("requirements", [])}
orphans = [c["requirement_id"] for c in spec.get("acceptance_criteria", [])
           if c["requirement_id"] not in ids]
if orphans:
    raise SystemExit("acceptance criteria point at unknown requirements: " + ", ".join(orphans))

facts = app_input.get("roadmap_facts") or {}
labels = {i["label"] for i in facts.get("items", [])}
bumped = [b["item"] for b in (result.get("roadmap") or {}).get("bumped", [])]
if bumped and facts.get("parse_confidence") != "high":
    raise SystemExit("items were bumped although the roadmap parse was " + str(facts.get("parse_confidence")))
invented = [b for b in bumped if b not in labels]
if invented:
    raise SystemExit("bumped items not on the pasted board: " + ", ".join(invented))

print(result["lane"], "-", result["title"])

const lanes = ["spec", "roadmap", "update"];
const present = lanes.filter(k => result[k] != null);
if (present.length !== 1 || present[0] !== result.lane) {
  throw new Error(`lane is ${result.lane} but [${present}] came back non-null`);
}

const spec = result.spec || {};
const ids = new Set((spec.requirements || []).map(r => r.id));
const orphans = (spec.acceptance_criteria || [])
  .map(c => c.requirement_id)
  .filter(id => !ids.has(id));
if (orphans.length) throw new Error("orphaned acceptance criteria: " + orphans.join(", "));

const facts = appInput.roadmap_facts || {};
const labels = new Set((facts.items || []).map(i => i.label));
const bumped = ((result.roadmap || {}).bumped || []).map(b => b.item);
if (bumped.length && facts.parse_confidence !== "high") {
  throw new Error("bumped items on a " + facts.parse_confidence + " roadmap parse");
}
const invented = bumped.filter(b => !labels.has(b));
if (invented.length) throw new Error("bumped items not on the board: " + invented.join(", "));

console.log(result.lane, "-", result.title);

// result and appInput decoded into structs mirroring the schemas above.

present := []string{}
if result.Spec != nil {
    present = append(present, "spec")
}
if result.Roadmap != nil {
    present = append(present, "roadmap")
}
if result.Update != nil {
    present = append(present, "update")
}
if len(present) != 1 || present[0] != result.Lane {
    log.Fatalf("lane is %s but %v came back non-null", result.Lane, present)
}

if result.Spec != nil {
    ids := map[string]bool{}
    for _, r := range result.Spec.Requirements {
        ids[r.ID] = true
    }
    for _, c := range result.Spec.AcceptanceCriteria {
        if !ids[c.RequirementID] {
            log.Fatalf("criterion points at unknown requirement %s", c.RequirementID)
        }
    }
}

if result.Roadmap != nil {
    labels := map[string]bool{}
    for _, i := range appInput.RoadmapFacts.Items {
        labels[i.Label] = true
    }
    if len(result.Roadmap.Bumped) > 0 && appInput.RoadmapFacts.ParseConfidence != "high" {
        log.Fatal("items bumped although the roadmap parse was not high-confidence")
    }
    for _, b := range result.Roadmap.Bumped {
        if !labels[b.Item] {
            log.Fatalf("bumped item %q is not on the pasted board", b.Item)
        }
    }
}

import java.util.*;
import java.util.stream.*;

List<String> present = new ArrayList<>();
if (result.spec != null) present.add("spec");
if (result.roadmap != null) present.add("roadmap");
if (result.update != null) present.add("update");
if (present.size() != 1 || !present.get(0).equals(result.lane))
    throw new IllegalStateException("lane is " + result.lane + " but " + present + " came back");

if (result.spec != null) {
    Set<String> ids = result.spec.requirements.stream()
        .map(r -> r.id).collect(Collectors.toSet());
    for (var c : result.spec.acceptanceCriteria)
        if (!ids.contains(c.requirementId))
            throw new IllegalStateException("criterion points at unknown " + c.requirementId);
}

if (result.roadmap != null) {
    Set<String> labels = appInput.roadmapFacts.items.stream()
        .map(i -> i.label).collect(Collectors.toSet());
    if (!result.roadmap.bumped.isEmpty()
        && !"high".equals(appInput.roadmapFacts.parseConfidence))
        throw new IllegalStateException("bumped items on a low-confidence roadmap parse");
    for (var b : result.roadmap.bumped)
        if (!labels.contains(b.item))
            throw new IllegalStateException("bumped item not on the board: " + b.item);
}

present = %w[spec roadmap update].select { |k| result[k] }
abort("lane is #{result["lane"]} but #{present} came back non-null") unless present == [result["lane"]]

spec = result["spec"] || {}
ids = (spec["requirements"] || []).map { |r| r["id"] }
orphans = (spec["acceptance_criteria"] || []).map { |c| c["requirement_id"] } - ids
abort("orphaned acceptance criteria: #{orphans.join(", ")}") unless orphans.empty?

facts = app_input["roadmap_facts"] || {}
labels = (facts["items"] || []).map { |i| i["label"] }
bumped = ((result["roadmap"] || {})["bumped"] || []).map { |b| b["item"] }
abort("bumped items on a #{facts["parse_confidence"]} parse") if bumped.any? && facts["parse_confidence"] != "high"
invented = bumped - labels
abort("bumped items not on the board: #{invented.join(", ")}") unless invented.empty?

puts "#{result["lane"]} - #{result["title"]}"

<?php
$present = array_values(array_filter(["spec", "roadmap", "update"],
    fn($k) => ($result[$k] ?? null) !== null));
if ($present !== [$result["lane"]]) {
    exit("lane is {$result["lane"]} but " . implode(",", $present) . " came back\n");
}

$spec = $result["spec"] ?? [];
$ids = array_column($spec["requirements"] ?? [], "id");
$orphans = array_diff(array_column($spec["acceptance_criteria"] ?? [], "requirement_id"), $ids);
if ($orphans) {
    exit("orphaned acceptance criteria: " . implode(", ", $orphans) . "\n");
}

$facts = $appInput["roadmap_facts"] ?? [];
$labels = array_column($facts["items"] ?? [], "label");
$bumped = array_column(($result["roadmap"] ?? [])["bumped"] ?? [], "item");
if ($bumped && ($facts["parse_confidence"] ?? "") !== "high") {
    exit("bumped items on a low-confidence roadmap parse\n");
}
$invented = array_diff($bumped, $labels);
if ($invented) {
    exit("bumped items not on the board: " . implode(", ", $invented) . "\n");
}

var lanes = new[] { "spec", "roadmap", "update" };
var present = lanes.Where(k => result.TryGetProperty(k, out var v) &&
                               v.ValueKind != JsonValueKind.Null).ToList();
var lane = result.GetProperty("lane").GetString();
if (present.Count != 1 || present[0] != lane)
    throw new Exception($"lane is {lane} but [{string.Join(",", present)}] came back");

if (lane == "spec")
{
    var spec = result.GetProperty("spec");
    var ids = spec.GetProperty("requirements").EnumerateArray()
        .Select(r => r.GetProperty("id").GetString()!).ToHashSet();
    foreach (var c in spec.GetProperty("acceptance_criteria").EnumerateArray())
    {
        var rid = c.GetProperty("requirement_id").GetString()!;
        if (!ids.Contains(rid)) throw new Exception($"criterion points at unknown {rid}");
    }
}

if (lane == "roadmap")
{
    var facts = appInput.GetProperty("roadmap_facts");
    var labels = facts.GetProperty("items").EnumerateArray()
        .Select(i => i.GetProperty("label").GetString()!).ToHashSet();
    var bumped = result.GetProperty("roadmap").GetProperty("bumped").EnumerateArray()
        .Select(b => b.GetProperty("item").GetString()!).ToList();
    if (bumped.Count > 0 && facts.GetProperty("parse_confidence").GetString() != "high")
        throw new Exception("bumped items on a low-confidence roadmap parse");
    foreach (var b in bumped)
        if (!labels.Contains(b)) throw new Exception($"bumped item not on the board: {b}");
}