Spend Lens — API

# Option A — take the token this browser already has: open /tokens.html,
      # press "Copy shell export", and paste the line it gives you.
      export SKILLSAFE_TOKEN="aut_xxxxxxxxxxxxxxxxxxxx"
      
      # Option B — mint a guest token with no browser at all. Guest tokens can call
      # /me and the free /estimate; sign in for a personal token to bill plan runs
      # to your own account.
      curl -s -X POST https://api.skillsafe.ai/v1/app-api/guest \
        -H 'Content-Type: application/json' \
        -d '{"slug":"spend-lens"}'
      # => {"data":{"token":"aut_...","subject_type":"guest","credits":0}}

import os, json, urllib.request
      
      BASE = "https://api.skillsafe.ai/v1/app-api"
      SLUG = "spend-lens"
      
      def call(path, body=None, token=None, method=None):
          data = json.dumps(body).encode() if body is not None else None
          req = urllib.request.Request(BASE + path, data=data,
                                      method=method or ("POST" if data else "GET"))
          req.add_header("Content-Type", "application/json")
          req.add_header("User-Agent", "spend-lens-client/1.0")
          if token:
              req.add_header("Authorization", "Bearer " + token)
          with urllib.request.urlopen(req) as r:
              return json.loads(r.read())["data"]
      
      # Option A: the token from /tokens.html, kept in your environment.
      token = os.environ.get("SKILLSAFE_TOKEN")
      
      # Option B: a fresh guest token, no browser involved.
      if not token:
          token = call("/guest", {"slug": SLUG})["token"]
      
      print(token[:12] + "...")

const BASE = "https://api.skillsafe.ai/v1/app-api";
      const SLUG = "spend-lens";
      
      async function call(path, { body, token, method } = {}) {
        const res = await fetch(BASE + path, {
          method: method || (body ? "POST" : "GET"),
          headers: {
            "Content-Type": "application/json",
            ...(token ? { Authorization: "Bearer " + token } : {}),
          },
          body: body ? JSON.stringify(body) : undefined,
        });
        const json = await res.json();
        if (json.error) throw Object.assign(new Error(json.error.message), json.error);
        return json.data;
      }
      
      // Option A: paste the token from /tokens.html (or read it from your own config).
      let token = "YOUR_TOKEN";
      
      // Option B: mint a guest token — good for /me and the free /estimate.
      if (token === "YOUR_TOKEN") token = (await call("/guest", { body: { slug: SLUG } })).token;
      
      console.log(token.slice(0, 12) + "...");

package main
      
      import (
          "bytes"
          "encoding/json"
          "errors"
          "fmt"
          "io"
          "net/http"
          "os"
      )
      
      const base = "https://api.skillsafe.ai/v1/app-api"
      const slug = "spend-lens"
      
      type envelope struct {
          Data  json.RawMessage `json:"data"`
          Error *struct {
              Code    string `json:"code"`
              Message string `json:"message"`
          } `json:"error"`
      }
      
      func call(path, token string, body any, out any) error {
          var rdr io.Reader
          method := "GET"
          if body != nil {
              b, _ := json.Marshal(body)
              rdr = bytes.NewReader(b)
              method = "POST"
          }
          req, _ := http.NewRequest(method, base+path, rdr)
          req.Header.Set("Content-Type", "application/json")
          if token != "" {
              req.Header.Set("Authorization", "Bearer "+token)
          }
          res, err := http.DefaultClient.Do(req)
          if err != nil {
              return err
          }
          defer res.Body.Close()
          var env envelope
          if err := json.NewDecoder(res.Body).Decode(&env); err != nil {
              return err
          }
          if env.Error != nil {
              return errors.New(env.Error.Code + ": " + env.Error.Message)
          }
          if out != nil {
              return json.Unmarshal(env.Data, out)
          }
          return nil
      }
      
      func main() {
          token := os.Getenv("SKILLSAFE_TOKEN")
          if token == "" {
              var guest struct{ Token string `json:"token"` }
              if err := call("/guest", "", map[string]string{"slug": slug}, &guest); err != nil {
                  panic(err)
              }
              token = guest.Token
          }
          fmt.Println(token[:12] + "...")
      }

import java.net.URI;
      import java.net.http.*;
      import java.util.Map;
      
      public class CiteReady {
          static final String BASE = "https://api.skillsafe.ai/v1/app-api";
          static final String SLUG = "spend-lens";
          static final HttpClient HTTP = HttpClient.newHttpClient();
      
          static String call(String path, String token, String jsonBody) throws Exception {
              HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(BASE + path))
                  .header("Content-Type", "application/json");
              if (token != null) b.header("Authorization", "Bearer " + token);
              b = jsonBody == null ? b.GET()
                                   : b.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
              HttpResponse<String> res = HTTP.send(b.build(), HttpResponse.BodyHandlers.ofString());
              return res.body();   // {"data":...} or {"error":{...}} — parse with your JSON library
          }
      
          public static void main(String[] args) throws Exception {
              String token = System.getenv("SKILLSAFE_TOKEN");
              if (token == null) {
                  // POST /guest returns {"data":{"token":"aut_..."}}
                  System.out.println(call("/guest", null, "{\"slug\":\"" + SLUG + "\"}"));
              } else {
                  System.out.println(token.substring(0, 12) + "...");
              }
          }
      }

require "json"
      require "net/http"
      
      BASE = URI("https://api.skillsafe.ai/v1/app-api")
      SLUG = "spend-lens"
      
      def call(path, body: nil, token: nil, method: nil)
        uri = URI(BASE.to_s + path)
        req = (method || (body ? "POST" : "GET")) == "POST" ?
          Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
        req["Content-Type"] = "application/json"
        req["Authorization"] = "Bearer #{token}" if token
        req.body = JSON.generate(body) if body
        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
        json = JSON.parse(res.body)
        raise "#{json['error']['code']}: #{json['error']['message']}" if json["error"]
        json["data"]
      end
      
      token = ENV["SKILLSAFE_TOKEN"] || call("/guest", body: { slug: SLUG })["token"]
      puts token[0, 12] + "..."

<?php
      const BASE = "https://api.skillsafe.ai/v1/app-api";
      const SLUG = "spend-lens";
      
      function call(string $path, ?array $body = null, ?string $token = null): array {
          $headers = ["Content-Type: application/json"];
          if ($token) { $headers[] = "Authorization: Bearer " . $token; }
          $ch = curl_init(BASE . $path);
          curl_setopt_array($ch, [
              CURLOPT_RETURNTRANSFER => true,
              CURLOPT_HTTPHEADER => $headers,
          ]);
          if ($body !== null) {
              curl_setopt($ch, CURLOPT_POST, true);
              curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
          }
          $json = json_decode(curl_exec($ch), true);
          curl_close($ch);
          if (isset($json["error"])) {
              throw new RuntimeException($json["error"]["code"] . ": " . $json["error"]["message"]);
          }
          return $json["data"];
      }
      
      $token = getenv("SKILLSAFE_TOKEN") ?: call("/guest", ["slug" => SLUG])["token"];
      echo substr($token, 0, 12) . "...\n";

using System;
      using System.Net.Http;
      using System.Net.Http.Json;
      using System.Text.Json;
      using System.Threading.Tasks;
      
      class CiteReady {
          const string Base = "https://api.skillsafe.ai/v1/app-api";
          const string Slug = "spend-lens";
          static readonly HttpClient Http = new HttpClient();
      
          static async Task<JsonElement> Call(string path, object body = null, string token = null) {
              var req = new HttpRequestMessage(body == null ? HttpMethod.Get : HttpMethod.Post, Base + path);
              if (token != null) req.Headers.Add("Authorization", "Bearer " + token);
              if (body != null) req.Content = JsonContent.Create(body);
              var res = await Http.SendAsync(req);
              var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
              if (doc.RootElement.TryGetProperty("error", out var err))
                  throw new Exception(err.GetProperty("code").GetString() + ": " + err.GetProperty("message").GetString());
              return doc.RootElement.GetProperty("data");
          }
      
          static async Task Main() {
              var token = Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN");
              if (token == null) {
                  var guest = await Call("/guest", new { slug = Slug });
                  token = guest.GetProperty("token").GetString();
              }
              Console.WriteLine(token.Substring(0, 12) + "...");
          }
      }

curl -s https://api.skillsafe.ai/v1/app-api/me \
        -H "Authorization: Bearer $SKILLSAFE_TOKEN"
      # => {"data":{"subject_type":"user","subject_id":"usr_...","credits":184213}}
      #
      # subject_type is "user" for a personal token and "guest" for a guest one.
      # credits is in credit units: 10 000 credits = $1.00.

me = call("/me", token=token)
      print(me["subject_type"], me["credits"], "credits",
            "= $%.2f" % (me["credits"] / 10000))

const me = await call("/me", { token });
      console.log(me.subject_type, me.credits, "credits =",
        "$" + (me.credits / 10000).toFixed(2));

var me struct {
          SubjectType string `json:"subject_type"`
          SubjectID   string `json:"subject_id"`
          Credits     int64  `json:"credits"`
      }
      if err := call("/me", token, nil, &me); err != nil {
          panic(err)
      }
      fmt.Printf("%s %d credits = $%.2f\n", me.SubjectType, me.Credits, float64(me.Credits)/10000)

// GET /me — {"data":{"subject_type":"user","credits":184213}}
      String me = call("/me", token, null);
      System.out.println(me);

me = call("/me", token: token)
      puts "#{me['subject_type']} #{me['credits']} credits = $#{'%.2f' % (me['credits'] / 10000.0)}"

$me = call("/me", null, $token);
      printf("%s %d credits = $%.2f\n", $me["subject_type"], $me["credits"], $me["credits"] / 10000);

var me = await Call("/me", null, token);
      var credits = me.GetProperty("credits").GetInt64();
      Console.WriteLine($"{me.GetProperty("subject_type").GetString()} {credits} credits = ${credits / 10000.0:F2}");

# /estimate is free: no job is created, no credits are held, nothing is charged.
      # Use it to show a price and to prove the model binding before you spend anything.
      curl -s -X POST https://api.skillsafe.ai/v1/app-api/estimate \
        -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
        -H 'Content-Type: application/json' \
        -d @plan-input.json
      # => {"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra","markup_bps":1000,
      #             "hold_credits":3120,"min_credits":260,"sponsor_enabled":false}}

est = call("/estimate", body=plan_input, token=token)
      print("model", est["model"], "alias", est["model_alias"], "markup", est["markup_bps"])
      print("reserved up to $%.4f" % (est["hold_credits"] / 10000))
      if me["credits"] < est["min_credits"]:
          raise SystemExit("balance below the model minimum — top up before running")

const est = await call("/estimate", { body: planInput, token });
      console.log(est.model, est.model_alias, est.markup_bps);
      console.log("reserved up to $" + (est.hold_credits / 10000).toFixed(4));
      if (me.credits < est.min_credits) throw new Error("balance below the model minimum");

var est struct {
          Model       string `json:"model"`
          ModelAlias  string `json:"model_alias"`
          MarkupBps   int    `json:"markup_bps"`
          HoldCredits int64  `json:"hold_credits"`
          MinCredits  int64  `json:"min_credits"`
      }
      if err := call("/estimate", token, planInput, &est); err != nil {
          panic(err)
      }
      fmt.Printf("%s (%s) markup %d bps, reserve $%.4f\n",
          est.Model, est.ModelAlias, est.MarkupBps, float64(est.HoldCredits)/10000)

// POST /estimate with the same body you would send to /run. Free, no job.
      String est = call("/estimate", token, planInputJson);
      System.out.println(est);

est = call("/estimate", body: plan_input, token: token)
      puts "#{est['model']} (#{est['model_alias']}) markup #{est['markup_bps']} bps"
      puts "reserved up to $#{'%.4f' % (est['hold_credits'] / 10000.0)}"

$est = call("/estimate", $plan_input, $token);
      printf("%s (%s) markup %d bps, reserve $%.4f\n",
          $est["model"], $est["model_alias"], $est["markup_bps"], $est["hold_credits"] / 10000);

var est = await Call("/estimate", planInput, token);
      Console.WriteLine(est.GetProperty("model").GetString() + " / " +
                        est.GetProperty("model_alias").GetString() + " markup " +
                        est.GetProperty("markup_bps").GetInt32() + " bps");

# Metered. Always send Idempotency-Key: a retry with the same key returns the
      # same job instead of billing twice.
      KEY="spend-lens:$(shasum -a 256 plan-input.json | cut -c1-16):a1"
      
      JOB=$(curl -s -X POST https://api.skillsafe.ai/v1/app-api/run \
        -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
        -H 'Content-Type: application/json' \
        -H "Idempotency-Key: $KEY" \
        -d @plan-input.json | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["job_id"])')
      
      # Poll until terminal.
      while true; do
        OUT=$(curl -s "https://api.skillsafe.ai/v1/app-api/jobs/$JOB" \
          -H "Authorization: Bearer $SKILLSAFE_TOKEN")
        STATUS=$(printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["status"])')
        [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] && break
        sleep 2
      done
      printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["output"]["output"])'
      # => the plan, as one JSON object (see the output contract below).

import hashlib, time
      
      def idem_key(inp, attempt=1):
          seed = "\u0020".join(str(inp.get(k, "")) for k in
                          ("cloud", "commitment_appetite", "workload", "constraints"))
          return "spend-lens:%s:a%d" % (hashlib.sha256(seed.encode()).hexdigest()[:16], attempt)
      
      def run_plan(inp, token, attempt=1):
          data = json.dumps(inp).encode()
          req = urllib.request.Request(BASE + "/run", data=data, method="POST")
          req.add_header("Content-Type", "application/json")
          req.add_header("Authorization", "Bearer " + token)
          req.add_header("Idempotency-Key", idem_key(inp, attempt))
          with urllib.request.urlopen(req) as r:
              job_id = json.loads(r.read())["data"]["job_id"]
          while True:
              job = call("/jobs/" + job_id, token=token)
              if job["status"] in ("succeeded", "failed"):
                  break
              time.sleep(2)
          if job["status"] == "failed":
              raise RuntimeError(job.get("error") or "run failed")
          return json.loads(job["output"]["output"])
      
      plan = run_plan(plan_input, token)
      print(plan["verdict"], plan["grade"], len(plan["levers"]), "levers")

import { createHash } from "node:crypto";
      
      function idemKey(inp, attempt = 1) {
        const seed = ["cloud", "commitment_appetite", "workload", "constraints"]
          .map((k) => String(inp[k] ?? "")).join(" ");
        return `spend-lens:${createHash("sha256").update(seed).digest("hex").slice(0, 16)}:a${attempt}`;
      }
      
      async function runAudit(inp, token, attempt = 1) {
        const res = await fetch(BASE + "/run", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: "Bearer " + token,
            "Idempotency-Key": idemKey(inp, attempt),
          },
          body: JSON.stringify(inp),
        });
        const { data, error } = await res.json();
        if (error) throw new Error(error.message);
        let job;
        do {
          await new Promise((r) => setTimeout(r, 2000));
          job = await call("/jobs/" + data.job_id, { token });
        } while (job.status !== "succeeded" && job.status !== "failed");
        if (job.status === "failed") throw new Error(job.error || "run failed");
        return JSON.parse(job.output.output);
      }
      
      const plan = await runAudit(planInput, token);
      console.log(plan.verdict, plan.grade, plan.levers.length + " levers");

import (
          "crypto/sha256"
          "encoding/hex"
          "strings"
          "time"
      )
      
      func idemKey(inp map[string]any, attempt int) string {
          parts := []string{}
          for _, k := range []string{"cloud", "commitment_appetite", "workload", "constraints"} {
              parts = append(parts, fmt.Sprint(inp[k]))
          }
          sum := sha256.Sum256([]byte(strings.Join(parts, " ")))
          return fmt.Sprintf("spend-lens:%s:a%d", hex.EncodeToString(sum[:])[:16], attempt)
      }
      
      // POST /run with the Idempotency-Key header, then poll GET /jobs/{id} every two
      // seconds until status is "succeeded" or "failed". job.Output.Output holds the
      // plan as a JSON string; unmarshal it into your own plan struct.
      func runAudit(inp map[string]any, token string) (string, error) {
          b, _ := json.Marshal(inp)
          req, _ := http.NewRequest("POST", base+"/run", bytes.NewReader(b))
          req.Header.Set("Content-Type", "application/json")
          req.Header.Set("Authorization", "Bearer "+token)
          req.Header.Set("Idempotency-Key", idemKey(inp, 1))
          res, err := http.DefaultClient.Do(req)
          if err != nil {
              return "", err
          }
          defer res.Body.Close()
          var env envelope
          json.NewDecoder(res.Body).Decode(&env)
          var started struct{ JobID string `json:"job_id"` }
          json.Unmarshal(env.Data, &started)
          for {
              var job struct {
                  Status string `json:"status"`
                  Output struct{ Output string `json:"output"` } `json:"output"`
              }
              if err := call("/jobs/"+started.JobID, token, nil, &job); err != nil {
                  return "", err
              }
              if job.Status == "succeeded" {
                  return job.Output.Output, nil
              }
              if job.Status == "failed" {
                  return "", errors.New("run failed")
              }
              time.Sleep(2 * time.Second)
          }
      }

// POST /run must carry Idempotency-Key, derived from the input plus an attempt
      // counter, so a network retry cannot bill the plan twice.
      String key = "spend-lens:" + sha256Hex(cloud + appetite + workload).substring(0, 16) + ":a1";
      
      HttpRequest run = HttpRequest.newBuilder(URI.create(BASE + "/run"))
          .header("Content-Type", "application/json")
          .header("Authorization", "Bearer " + token)
          .header("Idempotency-Key", key)
          .POST(HttpRequest.BodyPublishers.ofString(planInputJson))
          .build();
      String started = HTTP.send(run, HttpResponse.BodyHandlers.ofString()).body();
      // started => {"data":{"job_id":"job_..."}}
      // then poll GET /jobs/{job_id} until status is succeeded or failed, and read
      // data.output.output — the plan JSON as a string.

require "digest"
      
      def idem_key(inp, attempt = 1)
        seed = %w[cloud commitment_appetite workload constraints].map { |k| inp[k].to_s }.join(" ")
        "spend-lens:#{Digest::SHA256.hexdigest(seed)[0, 16]}:a#{attempt}"
      end
      
      def run_plan(inp, token)
        uri = URI(BASE.to_s + "/run")
        req = Net::HTTP::Post.new(uri)
        req["Content-Type"] = "application/json"
        req["Authorization"] = "Bearer #{token}"
        req["Idempotency-Key"] = idem_key(inp)
        req.body = JSON.generate(inp)
        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
        job_id = JSON.parse(res.body)["data"]["job_id"]
        loop do
          job = call("/jobs/#{job_id}", token: token)
          return JSON.parse(job["output"]["output"]) if job["status"] == "succeeded"
          raise "run failed" if job["status"] == "failed"
          sleep 2
        end
      end
      
      plan = run_plan(plan_input, token)
      puts "#{plan['verdict']} #{plan['grade']} #{plan['levers'].length} levers"

function idem_key(array $inp, int $attempt = 1): string {
          $seed = implode(" ", array_map(fn($k) => (string)($inp[$k] ?? ""),
              ["cloud", "commitment_appetite", "workload", "constraints"]));
          return "spend-lens:" . substr(hash("sha256", $seed), 0, 16) . ":a" . $attempt;
      }
      
      function run_plan(array $inp, string $token): array {
          $ch = curl_init(BASE . "/run");
          curl_setopt_array($ch, [
              CURLOPT_RETURNTRANSFER => true,
              CURLOPT_POST => true,
              CURLOPT_POSTFIELDS => json_encode($inp),
              CURLOPT_HTTPHEADER => [
                  "Content-Type: application/json",
                  "Authorization: Bearer " . $token,
                  "Idempotency-Key: " . idem_key($inp),
              ],
          ]);
          $job_id = json_decode(curl_exec($ch), true)["data"]["job_id"];
          curl_close($ch);
          while (true) {
              $job = call("/jobs/" . $job_id, null, $token);
              if ($job["status"] === "succeeded") { return json_decode($job["output"]["output"], true); }
              if ($job["status"] === "failed") { throw new RuntimeException("run failed"); }
              sleep(2);
          }
      }
      
      $plan = run_plan($plan_input, $token);
      echo $plan["verdict"] . " " . $plan["grade"] . " " . count($plan["levers"]) . " levers" . "\n";

using System.Security.Cryptography;
      using System.Text;
      
      static string IdemKey(Dictionary<string, object> inp, int attempt = 1) {
          var seed = string.Join(" ", new[] { "cloud", "commitment_appetite", "workload", "constraints" }
              .Select(k => inp.TryGetValue(k, out var v) ? v?.ToString() ?? "" : ""));
          var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(seed))).ToLowerInvariant();
          return $"spend-lens:{hash[..16]}:a{attempt}";
      }
      
      var req = new HttpRequestMessage(HttpMethod.Post, Base + "/run") {
          Content = JsonContent.Create(planInput)
      };
      req.Headers.Add("Authorization", "Bearer " + token);
      req.Headers.Add("Idempotency-Key", IdemKey(planInput));
      var started = JsonDocument.Parse(await (await Http.SendAsync(req)).Content.ReadAsStringAsync());
      var jobId = started.RootElement.GetProperty("data").GetProperty("job_id").GetString();
      
      // Poll GET /jobs/{jobId} every two seconds; on "succeeded", data.output.output is
      // the plan as a JSON string.

# Server-sent events. Frame names arrive on the `event:` line, not as a field in
      # the payload — `delta` carries text chunks, `job` the job id, `done` the
      # settlement (charged_credits, truncated).
      curl -N -X POST https://api.skillsafe.ai/v1/app-api/run-stream \
        -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
        -H 'Content-Type: application/json' \
        -H "Idempotency-Key: $KEY" \
        -d @plan-input.json
      # event: job
      # data: {"job_id":"job_..."}
      # event: delta
      # data: {"text":"{\"verdict\":\"bloated\","}
      # ...
      # event: done
      # data: {"status":"succeeded","charged_credits":812,"truncated":false}

def run_stream(inp, token, attempt=1, on_delta=None):
          data = json.dumps(inp).encode()
          req = urllib.request.Request(BASE + "/run-stream", data=data, method="POST")
          req.add_header("Content-Type", "application/json")
          req.add_header("Authorization", "Bearer " + token)
          req.add_header("Idempotency-Key", idem_key(inp, attempt))
          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:"):
                      payload = json.loads(line[5:].strip() or "{}")
                      if event == "delta":
                          raw += payload.get("text", "")
                          if on_delta:
                              on_delta(payload.get("text", ""))
                      elif event == "done":
                          return json.loads(raw), payload
          raise RuntimeError("stream ended without a done frame")
      
      plan, settle = run_stream(plan_input, token)
      print(plan["verdict"], "charged", settle["charged_credits"])

async function runStream(inp, token, onDelta, attempt = 1) {
        const res = await fetch(BASE + "/run-stream", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: "Bearer " + token,
            "Idempotency-Key": idemKey(inp, attempt),
          },
          body: JSON.stringify(inp),
        });
        const reader = res.body.getReader();
        const dec = new TextDecoder();
        let buf = "", raw = "", event = null;
        for (;;) {
          const { value, done } = 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:")) {
              const payload = JSON.parse(line.slice(5).trim() || "{}");
              if (event === "delta") { raw += payload.text || ""; onDelta?.(payload.text || ""); }
              else if (event === "done") return { plan: JSON.parse(raw), settle: payload };
            }
          }
        }
        throw new Error("stream ended without a done frame");
      }
      
      const { plan, settle } = await runStream(planInput, token, (t) => process.stdout.write(t));
      console.log("\n", plan.verdict, "charged", settle.charged_credits);

// POST /run-stream and read the SSE frames. The frame name is on the `event:`
      // line; `delta` payloads carry {"text":"..."} and concatenate into the plan JSON.
      req, _ := http.NewRequest("POST", base+"/run-stream", bytes.NewReader(bodyBytes))
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("Authorization", "Bearer "+token)
      req.Header.Set("Idempotency-Key", idemKey(inp, 1))
      res, err := http.DefaultClient.Do(req)
      if err != nil {
          panic(err)
      }
      defer res.Body.Close()
      
      sc := bufio.NewScanner(res.Body)
      sc.Buffer(make([]byte, 1<<20), 1<<20)
      var raw strings.Builder
      event := ""
      for sc.Scan() {
          line := sc.Text()
          switch {
          case strings.HasPrefix(line, "event:"):
              event = strings.TrimSpace(line[6:])
          case strings.HasPrefix(line, "data:"):
              payload := strings.TrimSpace(line[5:])
              if event == "delta" {
                  var d struct{ Text string `json:"text"` }
                  json.Unmarshal([]byte(payload), &d)
                  raw.WriteString(d.Text)
              } else if event == "done" {
                  fmt.Println("settled:", payload)
                  fmt.Println("plan:", raw.String())
                  return
              }
          }
      }

// POST /run-stream with BodyHandlers.ofLines() and fold the SSE frames yourself.
      HttpRequest stream = HttpRequest.newBuilder(URI.create(BASE + "/run-stream"))
          .header("Content-Type", "application/json")
          .header("Authorization", "Bearer " + token)
          .header("Idempotency-Key", key)
          .POST(HttpRequest.BodyPublishers.ofString(planInputJson))
          .build();
      
      StringBuilder raw = new StringBuilder();
      String[] event = { "" };
      HTTP.send(stream, HttpResponse.BodyHandlers.ofLines()).body().forEach(line -> {
          if (line.startsWith("event:")) {
              event[0] = line.substring(6).trim();
          } else if (line.startsWith("data:") && event[0].equals("delta")) {
              // parse {"text":"..."} with your JSON library and append it
              raw.append(extractText(line.substring(5).trim()));
          }
      });
      System.out.println(raw);   // the plan JSON

def run_stream(inp, token, attempt = 1)
        uri = URI(BASE.to_s + "/run-stream")
        req = Net::HTTP::Post.new(uri)
        req["Content-Type"] = "application/json"
        req["Authorization"] = "Bearer #{token}"
        req["Idempotency-Key"] = idem_key(inp, attempt)
        req.body = JSON.generate(inp)
        raw = ""
        event = nil
        settle = 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|
                line = line.chomp
                if line.start_with?("event:")
                  event = line[6..].strip
                elsif line.start_with?("data:")
                  payload = JSON.parse(line[5..].strip.empty? ? "{}" : line[5..].strip)
                  raw << payload.fetch("text", "") if event == "delta"
                  settle = payload if event == "done"
                end
              end
            end
          end
        end
        [JSON.parse(raw), settle]
      end
      
      plan, settle = run_stream(plan_input, token)
      puts "#{plan['verdict']} charged #{settle['charged_credits']}"

// POST /run-stream with a write callback; the frame name arrives on `event:`.
      $raw = "";
      $event = "";
      $ch = curl_init(BASE . "/run-stream");
      curl_setopt_array($ch, [
          CURLOPT_POST => true,
          CURLOPT_POSTFIELDS => json_encode($plan_input),
          CURLOPT_HTTPHEADER => [
              "Content-Type: application/json",
              "Authorization: Bearer " . $token,
              "Idempotency-Key: " . idem_key($plan_input),
          ],
          CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$raw, &$event) {
              foreach (explode("\n", $chunk) as $line) {
                  $line = rtrim($line);
                  if (str_starts_with($line, "event:")) {
                      $event = trim(substr($line, 6));
                  } elseif (str_starts_with($line, "data:") && $event === "delta") {
                      $payload = json_decode(trim(substr($line, 5)), true) ?: [];
                      $raw .= $payload["text"] ?? "";
                  }
              }
              return strlen($chunk);
          },
      ]);
      curl_exec($ch);
      curl_close($ch);
      $plan = json_decode($raw, true);
      echo $plan["verdict"] . "\n";

var sreq = new HttpRequestMessage(HttpMethod.Post, Base + "/run-stream") {
          Content = JsonContent.Create(planInput)
      };
      sreq.Headers.Add("Authorization", "Bearer " + token);
      sreq.Headers.Add("Idempotency-Key", IdemKey(planInput));
      
      using var sres = await Http.SendAsync(sreq, HttpCompletionOption.ResponseHeadersRead);
      using var reader = new StreamReader(await sres.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:")) {
              var payload = JsonDocument.Parse(line[5..].Trim() is { Length: > 0 } s ? s : "{}");
              if (evt == "delta" && payload.RootElement.TryGetProperty("text", out var t))
                  raw.Append(t.GetString());
              else if (evt == "done")
                  Console.WriteLine("settled: " + payload.RootElement);
          }
      }
      Console.WriteLine(raw.ToString());

# The report history lives in a declared collection called `reports`, so a
      # scripted client can read and write the same records the web app does.
      curl -s -X POST https://api.skillsafe.ai/v1/app-api/collections/reports/query \
        -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
        -H 'Content-Type: application/json' \
        -d '{"where":{"verdict":{"in":["bloated","trimmable"]},"identified_savings":{"gte":1000}},
             "order_by":[{"field":"ran_at","dir":"desc"}],"limit":20}'
      # Every `where` entry must be an operator object: {"eq":...}, not a bare value.
      # Operators: eq ne lt lte gt gte in contains.

# Trend the bill and its recoverable share month over month.
      res = call("/collections/reports/query", body={
          "where": {"verdict": {"in": ["bloated", "trimmable"]}},
          "order_by": [{"field": "ran_at", "dir": "desc"}],
          "limit": 24,
      }, token=token)
      prev = None
      for rec in reversed(res["records"]):
          d = rec["doc"]
          delta = "" if prev is None else " (%+.0f vs prior)" % (d["total_cost"] - prev)
          print(d["ran_at"], d["grade"], d["total_cost"], d["currency"],
                "recoverable", d["identified_savings"], delta)
          prev = d["total_cost"]

const res = await call("/collections/reports/query", {
        token,
        body: {
          where: { identified_savings: { gte: 1000 } },
          order_by: [{ field: "ran_at", dir: "desc" }],
          limit: 24,
        },
      });
      for (const rec of res.records) {
        const d = rec.doc;
        console.log(d.ran_at, d.grade, d.total_cost, d.currency, "recoverable", d.identified_savings);
      }

// POST /collections/reports/query with an operator object per where field.
      query := map[string]any{
          "where":    map[string]any{"identified_savings": map[string]any{"gte": 1000}},
          "order_by": []map[string]string{{"field": "ran_at", "dir": "desc"}},
          "limit":    24,
      }
      var res struct {
          Records []struct {
              RecordID string         `json:"record_id"`
              Doc      map[string]any `json:"doc"`
          } `json:"records"`
      }
      if err := call("/collections/reports/query", token, query, &res); err != nil {
          panic(err)
      }
      for _, r := range res.Records {
          fmt.Println(r.Doc["ran_at"], r.Doc["grade"], r.Doc["total_cost"], r.Doc["identified_savings"])
      }

// POST /collections/reports/query
      String q = "{\"where\":{\"identified_savings\":{\"gte\":1000}}," +
                 "\"order_by\":[{\"field\":\"ran_at\",\"dir\":\"desc\"}],\"limit\":24}";
      System.out.println(call("/collections/reports/query", token, q));

res = call("/collections/reports/query", body: {
        "where" => { "identified_savings" => { "gte" => 1000 } },
        "order_by" => [{ "field" => "ran_at", "dir" => "desc" }],
        "limit" => 24,
      }, token: token)
      res["records"].each do |rec|
        d = rec["doc"]
        puts "#{d['ran_at']} #{d['grade']} #{d['total_cost']} #{d['currency']} recoverable #{d['identified_savings']}"
      end

$res = call("/collections/reports/query", [
          "where" => ["identified_savings" => ["gte" => 1000]],
          "order_by" => [["field" => "ran_at", "dir" => "desc"]],
          "limit" => 24,
      ], $token);
      foreach ($res["records"] as $rec) {
          $d = $rec["doc"];
          echo "{$d['ran_at']} {$d['grade']} {$d['total_cost']} recoverable {$d['identified_savings']}\n";
      }

var q = new {
          where = new { identified_savings = new { gte = 1000 } },
          order_by = new[] { new { field = "ran_at", dir = "desc" } },
          limit = 24
      };
      var res = await Call("/collections/reports/query", q, token);
      foreach (var rec in res.GetProperty("records").EnumerateArray()) {
          var d = rec.GetProperty("doc");
          Console.WriteLine($"{d.GetProperty("ran_at")} {d.GetProperty("grade")} {d.GetProperty("total_cost")}");
      }