Driving dbt Desk over HTTP

# Every call in this document reuses these three values.
BASE="https://api.skillsafe.ai/v1/app-api"
SLUG="dbt-desk"
TOKEN="YOUR_TOKEN"        # from https://dbt-desk.skillsafe.ai/tokens.html

post() {  # post <path> <json>
  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"
}

import json
import urllib.request

BASE = "https://api.skillsafe.ai/v1/app-api"
SLUG = "dbt-desk"
TOKEN = "YOUR_TOKEN"   # from https://dbt-desk.skillsafe.ai/tokens.html


def call(path, payload=None, method="POST", headers=None):
    body = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=body, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as resp:
        envelope = json.loads(resp.read())
    if not envelope.get("ok"):
        err = envelope["error"]
        raise RuntimeError(err["code"] + ": " + err["message"])
    return envelope["data"]

const BASE = "https://api.skillsafe.ai/v1/app-api";
const SLUG = "dbt-desk";
const TOKEN = "YOUR_TOKEN"; // from https://dbt-desk.skillsafe.ai/tokens.html

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

package main

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

const (
	base = "https://api.skillsafe.ai/v1/app-api"
	slug = "dbt-desk"
)

// Paste the token, or export DBT_DESK_TOKEN before running.
var token = tokenOrDefault()

func tokenOrDefault() string {
	if v := os.Getenv("DBT_DESK_TOKEN"); v != "" {
		return v
	}
	return "YOUR_TOKEN"
}

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, payload any, extra map[string]string) (json.RawMessage, error) {
	var body io.Reader
	if payload != nil {
		b, _ := json.Marshal(payload)
		body = bytes.NewReader(b)
	}
	req, _ := http.NewRequest(method, base+path, body)
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	for k, v := range extra {
		req.Header.Set(k, v)
	}

	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, fmt.Errorf("%s: %s", env.Error.Code, env.Error.Message)
	}
	return env.Data, nil
}

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

public class DbtDesk {
    static final String BASE = "https://api.skillsafe.ai/v1/app-api";
    static final String SLUG = "dbt-desk";
    static final String TOKEN = "YOUR_TOKEN"; // from https://dbt-desk.skillsafe.ai/tokens.html

    static final HttpClient CLIENT = HttpClient.newHttpClient();

    static String call(String path, String jsonBody) throws Exception {
        HttpRequest.Builder b = HttpRequest.newBuilder()
            .uri(URI.create(BASE + path))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json");

        HttpRequest req = (jsonBody == null ? b.GET()
            : b.POST(HttpRequest.BodyPublishers.ofString(jsonBody))).build();

        HttpResponse<String> res = CLIENT.send(req, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() >= 400) {
            throw new RuntimeException("HTTP " + res.statusCode() + ": " + res.body());
        }
        return res.body();   // {"ok":true,"data":{...}}
    }
}

require "json"
require "net/http"
require "uri"

BASE  = "https://api.skillsafe.ai/v1/app-api"
SLUG  = "dbt-desk"
TOKEN = ENV["DBT_DESK_TOKEN"] || "YOUR_TOKEN"

def call(path, payload = nil, extra = {})
  uri = URI(BASE + path)
  req = payload.nil? ? Net::HTTP::Get.new(uri) : Net::HTTP::Post.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  req["Content-Type"] = "application/json"
  extra.each { |k, v| req[k] = v }
  req.body = JSON.dump(payload) unless payload.nil?

  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
  envelope = JSON.parse(res.body)
  raise "#{envelope['error']['code']}: #{envelope['error']['message']}" unless envelope["ok"]

  envelope["data"]
end

<?php
const BASE  = "https://api.skillsafe.ai/v1/app-api";
const SLUG  = "dbt-desk";
define("TOKEN", getenv("DBT_DESK_TOKEN") ?: "YOUR_TOKEN");

function call(string $path, ?array $payload = null, array $extra = []): array {
    $headers = array_merge([
        "Authorization: Bearer " . TOKEN,
        "Content-Type: application/json",
    ], $extra);

    $ch = curl_init(BASE . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => $payload !== null,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_POSTFIELDS => $payload === null ? null : json_encode($payload),
    ]);
    $envelope = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (empty($envelope["ok"])) {
        throw new RuntimeException($envelope["error"]["code"] . ": " . $envelope["error"]["message"]);
    }
    return $envelope["data"];
}

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

public static class DbtDesk
{
    const string Base = "https://api.skillsafe.ai/v1/app-api";
    const string Slug = "dbt-desk";
    static readonly string Token =
        Environment.GetEnvironmentVariable("DBT_DESK_TOKEN") ?? "YOUR_TOKEN";

    static readonly HttpClient Client = new HttpClient();

    public static async Task<JsonElement> CallAsync(
        string path, object payload = null, HttpMethod method = null)
    {
        var req = new HttpRequestMessage(method ?? HttpMethod.Post, Base + path);
        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
        if (payload is not null)
        {
            req.Content = new StringContent(
                JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
        }

        var res = await Client.SendAsync(req);
        var envelope = JsonDocument.Parse(await res.Content.ReadAsStringAsync()).RootElement;

        if (!envelope.GetProperty("ok").GetBoolean())
        {
            var err = envelope.GetProperty("error");
            throw new Exception(
                err.GetProperty("code").GetString() + ": " + err.GetProperty("message").GetString());
        }
        return envelope.GetProperty("data");
    }
}

curl -sS -X POST "$BASE/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"dbt-desk"}' | tee guest.json
# {"ok":true,"data":{"token":"aut_...","subject_type":"guest"}}

TOKEN=$(python3 -c "import json;print(json.load(open('guest.json'))['data']['token'])")

body = json.dumps({"slug": SLUG}).encode()
req = urllib.request.Request(BASE + "/guest", data=body, method="POST")
req.add_header("Content-Type", "application/json")
with urllib.request.urlopen(req) as resp:
    guest = json.loads(resp.read())["data"]

TOKEN = guest["token"]          # reuse this for the whole session
print(guest["subject_type"])    # "guest"

const res = await fetch(`${BASE}/guest`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ slug: SLUG })     // the only call that names the slug
});
const guest = (await res.json()).data;

const token = guest.token;        // reuse for the whole session
console.log(guest.subject_type);  // "guest"

guestBody := bytes.NewReader([]byte(`{"slug":"dbt-desk"}`))
req, _ := http.NewRequest("POST", base+"/guest", guestBody)
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

var env struct {
	Data struct {
		Token       string `json:"token"`
		SubjectType string `json:"subject_type"`
	} `json:"data"`
}
json.NewDecoder(res.Body).Decode(&env)
fmt.Println(env.Data.SubjectType) // "guest"

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(BASE + "/guest"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"slug\":\"dbt-desk\"}"))
    .build();

HttpResponse<String> res = CLIENT.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
// {"ok":true,"data":{"token":"aut_...","subject_type":"guest"}}

uri = URI(BASE + "/guest")
req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/json"
req.body = JSON.dump({ "slug" => SLUG })

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
guest = JSON.parse(res.body)["data"]

token = guest["token"]           # reuse for the whole session
puts guest["subject_type"]       # "guest"

<?php
$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" => SLUG]),
]);
$guest = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

$token = $guest["token"];          // reuse for the whole session
echo $guest["subject_type"];       // "guest"

var req = new HttpRequestMessage(HttpMethod.Post, Base + "/guest");
req.Content = new StringContent("{\"slug\":\"dbt-desk\"}", Encoding.UTF8, "application/json");

var res = await Client.SendAsync(req);
var guest = JsonDocument.Parse(await res.Content.ReadAsStringAsync())
    .RootElement.GetProperty("data");

var token = guest.GetProperty("token").GetString();   // reuse for the session
Console.WriteLine(guest.GetProperty("subject_type")); // "guest"

get /me
# {"ok":true,"data":{"subject_type":"user","credits":48210, ...}}

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, nil)
if err != nil {
	panic(err)
}

var me struct {
	SubjectType string `json:"subject_type"`
	Credits     int    `json:"credits"`
}
json.Unmarshal(data, &me)
fmt.Println(me.SubjectType, me.Credits)

String me = call("/me", null);   // null body means GET
System.out.println(me);
// {"ok":true,"data":{"subject_type":"user","credits":48210}}

me = call("/me")   # no payload, so the helper issues a GET
puts "#{me['subject_type']} #{me['credits']}"

<?php
$me = call("/me");   // no payload, so the helper issues a GET
echo $me["subject_type"] . " " . $me["credits"] . "\n";

var me = await CallAsync("/me", null, HttpMethod.Get);
Console.WriteLine(me.GetProperty("subject_type") + " credits=" + me.GetProperty("credits"));

# payload.json holds the input object itself - no "input" wrapper.
cat > payload.json <<'JSON'
{
  "task": "review",
  "model_sql": "{{ config(materialized='incremental') }}\nselect ...",
  "schema_yml": "version: 2\nmodels:\n  - name: fct_orders\n",
  "model_name": "fct_orders",
  "layer": "marts",
  "adapter": "snowflake",
  "dbt_version": "1.10+"
}
JSON

curl -sS -X POST "$BASE/estimate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json
# {"ok":true,"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra","markup_bps":1000,
#                    "hold_credits":4180,"min_credits":460,"sponsor_enabled":false}}

payload = {
    "task": "review",
    "model_sql": open("models/marts/fct_orders.sql").read(),
    "schema_yml": open("models/marts/fct_orders.yml").read(),
    "model_name": "fct_orders",
    "layer": "marts",
    "adapter": "snowflake",
    "dbt_version": "1.10+",
}

est = call("/estimate", payload)          # free, creates no job
print(est["model"], est["model_alias"], est["markup_bps"])
print(est["hold_credits"], est["min_credits"], est["sponsor_enabled"])

if me["credits"] < est["min_credits"]:
    raise SystemExit("short by %d credits" % (est["min_credits"] - me["credits"]))

import { readFileSync } from "node:fs";

const payload = {
  task: "review",
  model_sql: readFileSync("models/marts/fct_orders.sql", "utf8"),
  schema_yml: readFileSync("models/marts/fct_orders.yml", "utf8"),
  model_name: "fct_orders",
  layer: "marts",
  adapter: "snowflake",
  dbt_version: "1.10+"
};

const est = await call("/estimate", payload);   // free, creates no job
console.log(est.model, est.hold_credits, est.min_credits, est.sponsor_enabled);

if (me.credits < est.min_credits) {
  throw new Error(`short by ${est.min_credits - me.credits} credits`);
}

sql, _ := os.ReadFile("models/marts/fct_orders.sql")
yml, _ := os.ReadFile("models/marts/fct_orders.yml")

payload := map[string]any{
	"task":        "review",
	"model_sql":   string(sql),
	"schema_yml":  string(yml),
	"model_name":  "fct_orders",
	"layer":       "marts",
	"adapter":     "snowflake",
	"dbt_version": "1.10+",
}

data, err := call("POST", "/estimate", payload, nil)
if err != nil {
	panic(err)
}

var est struct {
	Model       string `json:"model"`
	HoldCredits int    `json:"hold_credits"`
	MinCredits  int    `json:"min_credits"`
}
json.Unmarshal(data, &est)
fmt.Println(est.Model, est.HoldCredits, est.MinCredits)

String sql = Files.readString(Path.of("models/marts/fct_orders.sql"));
String yml = Files.readString(Path.of("models/marts/fct_orders.yml"));

// The body is the input object itself. Build it with a real JSON library.
String payload = JsonUtil.object(
    "task", "review",
    "model_sql", sql,
    "schema_yml", yml,
    "model_name", "fct_orders",
    "layer", "marts",
    "adapter", "snowflake",
    "dbt_version", "1.10+");

String estimate = call("/estimate", payload);
System.out.println(estimate);
// {"ok":true,"data":{"model":"gpt-5.6-terra","hold_credits":4180,"min_credits":460, ...}}

payload = {
  "task" => "review",
  "model_sql" => File.read("models/marts/fct_orders.sql"),
  "schema_yml" => File.read("models/marts/fct_orders.yml"),
  "model_name" => "fct_orders",
  "layer" => "marts",
  "adapter" => "snowflake",
  "dbt_version" => "1.10+"
}

est = call("/estimate", payload)
puts "#{est['model']} hold=#{est['hold_credits']} min=#{est['min_credits']}"

abort "short by #{est['min_credits'] - me['credits']}" if me["credits"] < est["min_credits"]

<?php
$payload = [
    "task" => "review",
    "model_sql" => file_get_contents("models/marts/fct_orders.sql"),
    "schema_yml" => file_get_contents("models/marts/fct_orders.yml"),
    "model_name" => "fct_orders",
    "layer" => "marts",
    "adapter" => "snowflake",
    "dbt_version" => "1.10+",
];

$est = call("/estimate", $payload);
echo "{$est['model']} hold={$est['hold_credits']} min={$est['min_credits']}\n";

if ($me["credits"] < $est["min_credits"]) {
    throw new RuntimeException("short by " . ($est["min_credits"] - $me["credits"]));
}

var payload = new
{
    task = "review",
    model_sql = await File.ReadAllTextAsync("models/marts/fct_orders.sql"),
    schema_yml = await File.ReadAllTextAsync("models/marts/fct_orders.yml"),
    model_name = "fct_orders",
    layer = "marts",
    adapter = "snowflake",
    dbt_version = "1.10+"
};

var est = await CallAsync("/estimate", payload);
Console.WriteLine(est.GetProperty("hold_credits") + " held, min " + est.GetProperty("min_credits"));

# (task, input, attempt) - the lane must be in the key or lane two returns lane one.
KEY="dbt-desk:review:$(shasum -a 256 payload.json | cut -c1-16):1"

JOB=$(curl -sS -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d @payload.json | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['job_id'])")

until curl -sS "$BASE/jobs/$JOB" -H "Authorization: Bearer $TOKEN" \
  | tee job.json | grep -q '"status":"succeeded"'; do sleep 2; done

python3 -c "import json;print(json.load(open('job.json'))['data']['output']['output'])"

import hashlib, time


def idem(payload, attempt=1):
    """dbt Desk derives the key from (task, input, attempt) - nothing else."""
    material = json.dumps(payload, sort_keys=True).encode()
    return "dbt-desk:%s:%s:%d" % (
        payload["task"], hashlib.sha256(material).hexdigest()[:16], attempt)


key = idem(payload)
job = call("/run", dict(payload, idempotency_key=key))   # or send Idempotency-Key
job_id = job["job_id"]

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

if status["status"] != "succeeded":
    raise RuntimeError("job " + status["status"])

result = json.loads(status["output"]["output"])
print(result["posture"], "-", result["verdict"])
for f in result["findings"]:
    print("  [%-8s] %s %s" % (f["severity"], f["id"], f["title"]))

import { createHash } from "node:crypto";

// (task, input, attempt). Two lanes over one model are two runs.
const idem = (p, attempt = 1) =>
  `dbt-desk:${p.task}:` +
  createHash("sha256").update(JSON.stringify(p)).digest("hex").slice(0, 16) +
  `:${attempt}`;

const key = idem(payload);
const job = await call("/run", payload, "POST", { "Idempotency-Key": key });

let status;
do {
  await new Promise(r => setTimeout(r, 2000));
  status = await call(`/jobs/${job.job_id}`, undefined, "GET");
} while (!["succeeded", "failed", "cancelled"].includes(status.status));

if (status.status !== "succeeded") throw new Error(`job ${status.status}`);

const result = JSON.parse(status.output.output);
console.log(result.posture, "-", result.verdict);
for (const f of result.findings) {
  console.log(`  [${f.severity}] ${f.id} ${f.title}`);
}

material, _ := json.Marshal(payload)
sum := sha256.Sum256(material)
key := fmt.Sprintf("dbt-desk:%s:%x:1", payload["task"], sum[:8])

data, err := call("POST", "/run", payload, map[string]string{"Idempotency-Key": key})
if err != nil {
	panic(err)
}

var job struct {
	JobID string `json:"job_id"`
}
json.Unmarshal(data, &job)

for {
	time.Sleep(2 * time.Second)

	statusData, _ := call("GET", "/jobs/"+job.JobID, nil, nil)

	var st struct {
		Status string `json:"status"`
		Output struct {
			Output string `json:"output"`
		} `json:"output"`
	}
	json.Unmarshal(statusData, &st)

	if st.Status == "succeeded" {
		fmt.Println(st.Output.Output) // the model's JSON object, as a string
		break
	}
	if st.Status == "failed" || st.Status == "cancelled" {
		panic("job " + st.Status)
	}
}

String key = "dbt-desk:review:" + Integer.toHexString(payload.hashCode()) + ":1";

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

String jobId = JsonUtil.path(
    CLIENT.send(run, HttpResponse.BodyHandlers.ofString()).body(), "data", "job_id");

String status;
do {
    Thread.sleep(2000);
    status = call("/jobs/" + jobId, null);
} while (!status.contains("\"status\":\"succeeded\"")
      && !status.contains("\"status\":\"failed\""));

System.out.println(status);

require "digest"

# (task, input, attempt)
material = JSON.dump(payload.sort.to_h)
key = "dbt-desk:#{payload['task']}:#{Digest::SHA256.hexdigest(material)[0, 16]}:1"

job = call("/run", payload, { "Idempotency-Key" => key })

status = nil
loop do
  sleep 2
  status = call("/jobs/#{job['job_id']}")
  break if %w[succeeded failed cancelled].include?(status["status"])
end

raise "job #{status['status']}" unless status["status"] == "succeeded"

result = JSON.parse(status["output"]["output"])
puts "#{result['posture']} - #{result['verdict']}"
result["findings"].each { |f| puts "  [#{f['severity']}] #{f['id']} #{f['title']}" }

<?php
// (task, input, attempt)
$key = "dbt-desk:{$payload['task']}:"
     . substr(hash("sha256", json_encode($payload)), 0, 16) . ":1";

$job = call("/run", $payload, ["Idempotency-Key: " . $key]);

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

if ($status["status"] !== "succeeded") {
    throw new RuntimeException("job " . $status["status"]);
}

$result = json_decode($status["output"]["output"], true);
echo "{$result['posture']} - {$result['verdict']}\n";
foreach ($result["findings"] as $f) {
    echo "  [{$f['severity']}] {$f['id']} {$f['title']}\n";
}

using System.Security.Cryptography;

var material = JsonSerializer.Serialize(payload);
var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(material)))[..16]
    .ToLowerInvariant();
var key = "dbt-desk:review:" + hash + ":1";

var runReq = new HttpRequestMessage(HttpMethod.Post, Base + "/run");
runReq.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
runReq.Headers.Add("Idempotency-Key", key);
runReq.Content = new StringContent(material, Encoding.UTF8, "application/json");

var runRes = await Client.SendAsync(runReq);
var jobId = JsonDocument.Parse(await runRes.Content.ReadAsStringAsync())
    .RootElement.GetProperty("data").GetProperty("job_id").GetString();

JsonElement status;
string state;
do
{
    await Task.Delay(2000);
    status = await CallAsync($"/jobs/{jobId}", null, HttpMethod.Get);
    state = status.GetProperty("status").GetString();
} while (state is not ("succeeded" or "failed" or "cancelled"));

if (state != "succeeded") throw new Exception("job " + state);

var result = JsonDocument.Parse(
    status.GetProperty("output").GetProperty("output").GetString()).RootElement;
Console.WriteLine(result.GetProperty("verdict"));

curl -sS -N -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -H "Accept: text/event-stream" \
  -d @payload.json

# event: delta
# data: {"text":"{\"lane\":\"review\",\"lane_inferred\":false,"}
# event: delta
# data: {"text":"\"model_name\":\"fct_orders\","}
# event: done
# data: {"job_id":"job_...","charged_credits":2914,"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)
req.add_header("Accept", "text/event-stream")

chunks = []
with urllib.request.urlopen(req) as stream:
    for raw in stream:
        line = raw.decode().strip()
        if not line.startswith("data:"):
            continue
        event = json.loads(line[5:].strip())
        if "text" in event:
            chunks.append(event["text"])
            print(".", end="", flush=True)

result = json.loads("".join(chunks))     # only valid once the stream has closed
print()
print(result["posture"], result["verdict"])

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

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "", text = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  const lines = buffer.split("\n");
  buffer = lines.pop();

  for (const line of lines) {
    if (!line.startsWith("data:")) continue;
    const event = JSON.parse(line.slice(5).trim());
    if (event.text) text += event.text;
  }
}

const result = JSON.parse(text);
console.log(result.posture, result.verdict);

body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", base+"/run-stream", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", key)
req.Header.Set("Accept", "text/event-stream")

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

var sb strings.Builder
scanner := bufio.NewScanner(res.Body)
scanner.Buffer(make([]byte, 1024*1024), 1024*1024)

for scanner.Scan() {
	line := scanner.Text()
	if !strings.HasPrefix(line, "data:") {
		continue
	}
	var ev struct {
		Text string `json:"text"`
	}
	if json.Unmarshal([]byte(strings.TrimSpace(line[5:])), &ev) == nil && ev.Text != "" {
		sb.WriteString(ev.Text)
	}
}
fmt.Println(sb.String()) // the whole JSON object, reassembled

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(BASE + "/run-stream"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", key)
    .header("Accept", "text/event-stream")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

StringBuilder text = new StringBuilder();

CLIENT.send(req, HttpResponse.BodyHandlers.ofLines())
      .body()
      .filter(line -> line.startsWith("data:"))
      .forEach(line -> text.append(JsonUtil.path(line.substring(5).trim(), "text")));

System.out.println(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["Accept"] = "text/event-stream"
req.body = JSON.dump(payload)

text = +""
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|
        next unless line.start_with?("data:")

        event = JSON.parse(line[5..].strip) rescue next
        text << event["text"] if event["text"]
      end
    end
  end
end

result = JSON.parse(text)
puts "#{result['posture']} #{result['verdict']}"

<?php
$text = "";

$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,
        "Accept: text/event-stream",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$text) {
        foreach (explode("\n", $chunk) as $line) {
            if (str_starts_with($line, "data:")) {
                $event = json_decode(trim(substr($line, 5)), true);
                if (isset($event["text"])) $text .= $event["text"];
            }
        }
        return strlen($chunk);
    },
]);
curl_exec($ch);
curl_close($ch);

$result = json_decode($text, true);
echo "{$result['posture']} {$result['verdict']}\n";

var req = new HttpRequestMessage(HttpMethod.Post, Base + "/run-stream");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
req.Headers.Add("Idempotency-Key", key);
req.Headers.Add("Accept", "text/event-stream");
req.Content = new StringContent(material, Encoding.UTF8, "application/json");

var res = await Client.SendAsync(req, HttpCompletionOption.ResponseHeadersRead);
using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());

var text = new StringBuilder();
while (await reader.ReadLineAsync() is { } line)
{
    if (!line.StartsWith("data:")) continue;

    var ev = JsonDocument.Parse(line[5..].Trim()).RootElement;
    if (ev.TryGetProperty("text", out var t)) text.Append(t.GetString());
}

var result = JsonDocument.Parse(text.ToString()).RootElement;
Console.WriteLine(result.GetProperty("verdict"));

post /collections/dbtruns/query '{
  "where": {"lane": {"eq": "review"}},
  "sort": {"field": "ran_at", "dir": "desc"},
  "limit": 20
}'
# {"ok":true,"data":{"records":[
#   {"record_id":"rec_01j...","created_at":"2026-08-21T09:14:03Z",
#    "doc":{"uid":"...","title":"fct_orders - grain untested","lane":"review",
#           "model_name":"fct_orders","layer":"marts","materialization":"incremental",
#           "posture":"hardening-recommended","verdict":"...","input_hash":"...",
#           "finding_count":7,"critical_count":1,"ran_at":"2026-08-21T09:14:03.221Z",
#           "entry":{"result":{...},"meta":{},"input":{...}}}}
# ]}}

runs = call("/collections/dbtruns/query", {
    "where": {"lane": {"eq": "review"}},          # operator objects, not bare values
    "sort": {"field": "ran_at", "dir": "desc"},   # "order_by" is silently ignored
    "limit": 20,
})

for rec in runs["records"]:
    doc = rec["doc"]        # ALWAYS unwrap doc; the fields are never flat on rec
    print(doc["ran_at"], doc["model_name"], doc["posture"], doc["finding_count"])

    result = doc["entry"]["result"]     # the full model output, as returned then
    print("   ", result["verdict"])

const runs = await call("/collections/dbtruns/query", {
  where: { lane: { eq: "review" } },          // operator objects, not bare values
  sort: { field: "ran_at", dir: "desc" },     // "order_by" is silently ignored
  limit: 20
});

for (const rec of runs.records) {
  const doc = rec.doc;    // ALWAYS unwrap doc; rec.model_name is undefined
  console.log(doc.ran_at, doc.model_name, doc.posture, doc.finding_count);
  console.log("   ", doc.entry.result.verdict);
}

query := map[string]any{
	"where": map[string]any{"lane": map[string]any{"eq": "review"}},
	"sort":  map[string]any{"field": "ran_at", "dir": "desc"},
	"limit": 20,
}

data, err := call("POST", "/collections/dbtruns/query", query, nil)
if err != nil {
	panic(err)
}

var page struct {
	Records []struct {
		RecordID string `json:"record_id"`
		Doc      struct {
			ModelName    string `json:"model_name"`
			Lane         string `json:"lane"`
			Posture      string `json:"posture"`
			Verdict      string `json:"verdict"`
			FindingCount int    `json:"finding_count"`
			RanAt        string `json:"ran_at"`
		} `json:"doc"` // the fields live under doc, never on the record
	} `json:"records"`
}
json.Unmarshal(data, &page)

for _, rec := range page.Records {
	fmt.Println(rec.Doc.RanAt, rec.Doc.ModelName, rec.Doc.Posture, rec.Doc.FindingCount)
}

String query = """
    {"where": {"lane": {"eq": "review"}},
     "sort": {"field": "ran_at", "dir": "desc"},
     "limit": 20}
    """;

String page = call("/collections/dbtruns/query", query);
System.out.println(page);
// data.records[i].doc.model_name - the declared fields are nested under "doc",
// so a reader that looks for records[i].model_name finds nothing.

runs = call("/collections/dbtruns/query", {
  "where" => { "lane" => { "eq" => "review" } },   # operator objects
  "sort" => { "field" => "ran_at", "dir" => "desc" },
  "limit" => 20
})

runs["records"].each do |rec|
  doc = rec["doc"]     # never rec["model_name"]
  puts "#{doc['ran_at']} #{doc['model_name']} #{doc['posture']} #{doc['finding_count']}"
  puts "    #{doc['entry']['result']['verdict']}"
end

<?php
$runs = call("/collections/dbtruns/query", [
    "where" => ["lane" => ["eq" => "review"]],       // operator objects
    "sort" => ["field" => "ran_at", "dir" => "desc"], // not "order_by"
    "limit" => 20,
]);

foreach ($runs["records"] as $rec) {
    $doc = $rec["doc"];   // never $rec["model_name"]
    echo "{$doc['ran_at']} {$doc['model_name']} {$doc['posture']} {$doc['finding_count']}\n";
    echo "    {$doc['entry']['result']['verdict']}\n";
}

var query = new
{
    where = new { lane = new { eq = "review" } },      // operator objects
    sort = new { field = "ran_at", dir = "desc" },     // not order_by
    limit = 20
};

var page = await CallAsync("/collections/dbtruns/query", query);

foreach (var rec in page.GetProperty("records").EnumerateArray())
{
    var doc = rec.GetProperty("doc");   // the fields are under doc, not on rec
    Console.WriteLine(doc.GetProperty("ran_at") + " " + doc.GetProperty("model_name")
        + " " + doc.GetProperty("posture"));
}