Clipper Forge — 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 template
# runs to your own account.
curl -s -X POST https://api.skillsafe.ai/v1/app-api/guest \
  -H 'Content-Type: application/json' \
  -d '{"slug":"clipper-forge"}'
# => {"data":{"token":"aut_...","subject_type":"guest","credits":0}}

import os, json, urllib.request

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

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", "clipper-forge-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 = "clipper-forge";

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 = "clipper-forge"

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 ClipperForge {
    static final String BASE = "https://api.skillsafe.ai/v1/app-api";
    static final String SLUG = "clipper-forge";
    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 = "clipper-forge"

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 = "clipper-forge";

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 ClipperForge {
    const string Base = "https://api.skillsafe.ai/v1/app-api";
    const string Slug = "clipper-forge";
    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 @clip-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=clip_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: clipInput, 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, clipInput, &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, clipInputJson);
System.out.println(est);

est = call("/estimate", body: clip_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", $clip_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", clipInput, 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="clipper-forge:$(shasum -a 256 clip-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 @clip-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"])'
# => {"template":{...},"rationale_notes":[...],"unverified":[]}
# The "template" object is the file you import in Obsidian:
# Settings → Web Clipper → Templates → Import.

import hashlib, time

def idem_key(inp, attempt=1):
    seed = " ".join(str(inp.get(k, "")) for k in
                    ("intent", "page_url", "behavior"))
    return "clipper-forge:%s:a%d" % (hashlib.sha256(seed.encode()).hexdigest()[:16], attempt)

def run_template(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"])

result = run_template(clip_input, token)
tpl = result["template"]
print(tpl["name"], "-", len(tpl["properties"]), "properties,",
      len(tpl["triggers"]), "triggers")
open("template.json", "w").write(json.dumps(tpl, indent=2))

import { createHash } from "node:crypto";
import { writeFileSync } from "node:fs";

function idemKey(inp, attempt = 1) {
  const seed = ["intent", "page_url", "behavior"]
    .map((k) => String(inp[k] ?? "")).join(" ");
  return `clipper-forge:${createHash("sha256").update(seed).digest("hex").slice(0, 16)}:a${attempt}`;
}

async function runTemplate(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 result = await runTemplate(clipInput, token);
console.log(result.template.name, "-", result.template.triggers.length + " triggers");
writeFileSync("template.json", JSON.stringify(result.template, null, 2));

import (
    "crypto/sha256"
    "encoding/hex"
    "strings"
    "time"
)

func idemKey(inp map[string]any, attempt int) string {
    parts := []string{}
    for _, k := range []string{"intent", "page_url", "behavior"} {
        parts = append(parts, fmt.Sprint(inp[k]))
    }
    sum := sha256.Sum256([]byte(strings.Join(parts, " ")))
    return fmt.Sprintf("clipper-forge:%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
// result as a JSON string; unmarshal it and write .template to a file to import.
func runTemplate(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 template twice.
String key = "clipper-forge:" + sha256Hex(intent + pageUrl + behavior).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(clipInputJson))
    .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 — {"template":{...},"rationale_notes":[...],"unverified":[]}
// as a JSON string. Write the "template" object out and import it in Obsidian.

require "digest"

def idem_key(inp, attempt = 1)
  seed = %w[intent page_url behavior].map { |k| inp[k].to_s }.join(" ")
  "clipper-forge:#{Digest::SHA256.hexdigest(seed)[0, 16]}:a#{attempt}"
end

def run_template(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

result = run_template(clip_input, token)
tpl = result["template"]
puts "#{tpl['name']} - #{tpl['properties'].length} properties"
File.write("template.json", JSON.pretty_generate(tpl))

function idem_key(array $inp, int $attempt = 1): string {
    $seed = implode(" ", array_map(fn($k) => (string)($inp[$k] ?? ""),
        ["intent", "page_url", "behavior"]));
    return "clipper-forge:" . substr(hash("sha256", $seed), 0, 16) . ":a" . $attempt;
}

function run_template(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);
    }
}

$result = run_template($clip_input, $token);
$tpl = $result["template"];
echo $tpl["name"] . " - " . count($tpl["properties"]) . " properties\n";
file_put_contents("template.json", json_encode($tpl, JSON_PRETTY_PRINT));

using System.Security.Cryptography;
using System.Text;

static string IdemKey(Dictionary<string, object> inp, int attempt = 1) {
    var seed = string.Join(" ", new[] { "intent", "page_url", "behavior" }
        .Select(k => inp.TryGetValue(k, out var v) ? v?.ToString() ?? "" : ""));
    var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(seed))).ToLowerInvariant();
    return $"clipper-forge:{hash[..16]}:a{attempt}";
}

var req = new HttpRequestMessage(HttpMethod.Post, Base + "/run") {
    Content = JsonContent.Create(clipInput)
};
req.Headers.Add("Authorization", "Bearer " + token);
req.Headers.Add("Idempotency-Key", IdemKey(clipInput));
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
// {"template":{...},"rationale_notes":[...],"unverified":[]} as a JSON string.
// Save the "template" object and import it in Obsidian's Web Clipper settings.

# 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 @clip-input.json
# event: job
# data: {"job_id":"job_..."}
# event: delta
# data: {"text":"{\"template\":{\"schemaVersion\":\"0.1.0\",\"name\":\"Rec"}
# ...
# 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")

result, settle = run_stream(clip_input, token)
print(result["template"]["name"], "charged", settle["charged_credits"])
if result["unverified"]:
    print("model could not ground:", "; ".join(result["unverified"]))

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 { result: JSON.parse(raw), settle: payload };
      }
    }
  }
  throw new Error("stream ended without a done frame");
}

let chars = 0;
const { result, settle } = await runStream(clipInput, token, (t) => { chars += t.length; });
console.log(result.template.name, "charged", settle.charged_credits, "-", chars, "chars");

// POST /run-stream and read the SSE frames. The frame name is on the `event:`
// line; `delta` payloads carry {"text":"..."} and concatenate into the result 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("result:", 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(clipInputJson))
    .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);   // {"template":{...},"rationale_notes":[...],"unverified":[]}

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

result, settle = run_stream(clip_input, token)
puts "#{result['template']['name']} 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($clip_input),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: Bearer " . $token,
        "Idempotency-Key: " . idem_key($clip_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);
$result = json_decode($raw, true);
echo $result["template"]["name"] . "\n";

var sreq = new HttpRequestMessage(HttpMethod.Post, Base + "/run-stream") {
    Content = JsonContent.Create(clipInput)
};
sreq.Headers.Add("Authorization", "Bearer " + token);
sreq.Headers.Add("Idempotency-Key", IdemKey(clipInput));

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());

# Filtered query: clean templates for one site, newest first.
curl -s -X POST https://api.skillsafe.ai/v1/app-api/collections/templates/query \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"where":{"site":{"eq":"example.com"},"lint_fails":{"eq":0}},
       "sort":{"field":"ran_at","dir":"desc"},"limit":20}'

# Semantic search over name + site + intent (30/min per IP; ~10x a query):
curl -s -X POST https://api.skillsafe.ai/v1/app-api/collections/templates/similar \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"text":"the recipe one with ingredient checkboxes","limit":8}'

res = call("/collections/templates/query", body={
    "where": {"lint_fails": {"eq": 0}},
    "sort": {"field": "ran_at", "dir": "desc"},
    "limit": 24,
}, token=token)
for rec in res["records"]:
    d = rec["doc"]
    print(d["ran_at"], d["name"], "-", d["site"], "-", d["schema_types"])

hits = call("/collections/templates/similar",
            body={"text": "the recipe one with ingredient checkboxes", "limit": 8},
            token=token)
for rec in hits["records"]:
    print("%.2f" % rec.get("score", 0), rec["doc"]["name"])

const res = await call("/collections/templates/query", {
  token,
  body: {
    where: { lint_fails: { eq: 0 } },
    sort: { field: "ran_at", dir: "desc" },
    limit: 24,
  },
});
for (const rec of res.records) {
  const d = rec.doc;
  console.log(d.ran_at, d.name, "-", d.site, "-", d.schema_types);
}

const hits = await call("/collections/templates/similar", {
  token,
  body: { text: "the recipe one with ingredient checkboxes", limit: 8 },
});
for (const rec of hits.records) console.log(rec.score, rec.doc.name);

// POST /collections/templates/query with an operator object per where field.
query := map[string]any{
    "where": map[string]any{"lint_fails": map[string]any{"eq": 0}},
    "sort":  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/templates/query", token, query, &res); err != nil {
    panic(err)
}
for _, r := range res.Records {
    fmt.Println(r.Doc["ran_at"], r.Doc["name"], r.Doc["site"])
}

// POST /collections/templates/query
String q = "{\"where\":{\"lint_fails\":{\"eq\":0}}," +
           "\"sort\":{\"field\":\"ran_at\",\"dir\":\"desc\"},\"limit\":24}";
System.out.println(call("/collections/templates/query", token, q));
// Semantic search: POST /collections/templates/similar {"text":"...","limit":8}

res = call("/collections/templates/query", body: {
  "where" => { "lint_fails" => { "eq" => 0 } },
  "sort" => { "field" => "ran_at", "dir" => "desc" },
  "limit" => 24,
}, token: token)
res["records"].each do |rec|
  d = rec["doc"]
  puts "#{d['ran_at']} #{d['name']} - #{d['site']} - #{d['schema_types']}"
end

$res = call("/collections/templates/query", [
    "where" => ["lint_fails" => ["eq" => 0]],
    "sort" => ["field" => "ran_at", "dir" => "desc"],
    "limit" => 24,
], $token);
foreach ($res["records"] as $rec) {
    $d = $rec["doc"];
    echo "{$d['ran_at']} {$d['name']} - {$d['site']}\n";
}

var q = new {
    where = new { lint_fails = new { eq = 0 } },
    sort = new { field = "ran_at", dir = "desc" },
    limit = 24
};
var res = await Call("/collections/templates/query", q, token);
foreach (var rec in res.GetProperty("records").EnumerateArray()) {
    var d = rec.GetProperty("doc");
    Console.WriteLine($"{d.GetProperty("ran_at")} {d.GetProperty("name")}");
}