The Geo Desk API

# There is no helper in cURL; every call below repeats the two headers.
BASE=https://api.skillsafe.ai/v1/app-api
TOKEN=YOUR_TOKEN          # paste it from https://geo-desk.skillsafe.ai/tokens.html

# Success is {"data": ...}; failure is {"error": {"code": ..., "message": ...}}.
# There is no "ok" flag -- test for the presence of "error".

import json, urllib.request

BASE = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"      # paste it from /tokens.html

def call(path, body=None, method=None, extra_headers=None):
    data = None if body is None else json.dumps(body).encode()
    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("Authorization", "Bearer " + TOKEN)
    for k, v in (extra_headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as r:
        env = json.loads(r.read().decode())
    if "error" in env:                       # no "ok" flag in this API
        raise RuntimeError(env["error"]["code"] + ": " + env["error"].get("message", ""))
    return env["data"]

const BASE = "https://api.skillsafe.ai/v1/app-api";
let TOKEN = "YOUR_TOKEN";   // paste it from /tokens.html

async function call(path, body, method, extraHeaders) {
  const res = await fetch(BASE + path, {
    method: method || (body ? "POST" : "GET"),
    headers: Object.assign({
      "Content-Type": "application/json",
      "Authorization": "Bearer " + TOKEN
    }, extraHeaders || {}),
    body: body ? JSON.stringify(body) : undefined
  });
  const env = await res.json();
  if (env.error) throw new Error(env.error.code + ": " + (env.error.message || ""));
  return env.data;   // success carries data, failure carries error
}

package main

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

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

// Read the token from the environment rather than pasting it into source.
var token = os.Getenv("SKILLSAFE_TOKEN")

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

func call(path string, body any, method string, extra map[string]string) (json.RawMessage, error) {
    var rdr io.Reader
    if body != nil {
        b, _ := json.Marshal(body)
        rdr = bytes.NewReader(b)
        if method == "" {
            method = "POST"
        }
    } else if method == "" {
        method = "GET"
    }
    req, _ := http.NewRequest(method, base+path, rdr)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+token)
    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.Error != nil {
        return nil, errors.New(env.Error.Code + ": " + env.Error.Message)
    }
    return env.Data, nil
}

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

class GeoDesk {
    static final String BASE = "https://api.skillsafe.ai/v1/app-api";
    static String token = System.getenv("SKILLSAFE_TOKEN");
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static String call(String path, String jsonBody, String method, String idemKey)
            throws Exception {
        HttpRequest.BodyPublisher pub = jsonBody == null
            ? HttpRequest.BodyPublishers.noBody()
            : HttpRequest.BodyPublishers.ofString(jsonBody);
        HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(BASE + path))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + token)
            .method(method != null ? method : (jsonBody != null ? "POST" : "GET"), pub);
        if (idemKey != null) b.header("Idempotency-Key", idemKey);
        HttpResponse<String> res = HTTP.send(b.build(), HttpResponse.BodyHandlers.ofString());
        // res.body() is {"data": ...} or {"error": {...}} -- check for "error" first.
        return res.body();
    }
}

require "json"
require "net/http"

BASE  = URI("https://api.skillsafe.ai/v1/app-api")
TOKEN = ENV.fetch("SKILLSAFE_TOKEN", "YOUR_TOKEN")

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

<?php
const BASE  = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN";   // or getenv("SKILLSAFE_TOKEN")

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

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

static class GeoDesk
{
    const string Base = "https://api.skillsafe.ai/v1/app-api";
    static string Token = Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN") ?? "YOUR_TOKEN";
    static readonly HttpClient Http = new HttpClient();

    static async Task<JsonElement> Call(string path, object body = null,
                                        string method = null, string idemKey = null)
    {
        var verb = new HttpMethod(method ?? (body != null ? "POST" : "GET"));
        var req = new HttpRequestMessage(verb, Base + path);
        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
        if (idemKey != null) req.Headers.Add("Idempotency-Key", idemKey);
        if (body != null)
            req.Content = new StringContent(JsonSerializer.Serialize(body),
                                            Encoding.UTF8, "application/json");
        var res = await Http.SendAsync(req);
        var env = JsonDocument.Parse(await res.Content.ReadAsStringAsync()).RootElement;
        if (env.TryGetProperty("error", out var err))
            throw new Exception(err.GetProperty("code").GetString());
        return env.GetProperty("data");
    }
}

# A GUEST token is enough for /me and /estimate. The slug travels in the BODY --
# there is no X-App-Slug header, and a bogus one would simply be ignored.
curl -s -X POST https://api.skillsafe.ai/v1/app-api/guest \
  -H "Content-Type: application/json" \
  -d '{"slug":"geo-desk"}'
# -> 201 {"data":{"token":"aut_...","guest_id":"gst_...","expires_at":"2026-08-21T09:14:02Z"}}
#
# Running a lane is metered, so it needs a PERSONAL token: sign in at
# https://geo-desk.skillsafe.ai/tokens.html and copy it from there.

def guest_token():
    req = urllib.request.Request(
        BASE + "/guest",
        data=json.dumps({"slug": "geo-desk"}).encode(),   # the slug goes in the BODY
        method="POST")
    req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req) as r:                # answers 201
        return json.loads(r.read().decode())["data"]["token"]

TOKEN = guest_token()   # good for /me and /estimate; a run needs a personal token

async function guestToken() {
  const res = await fetch(BASE + "/guest", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ slug: "geo-desk" })   // the slug goes in the BODY
  });
  const env = await res.json();                  // 201
  return env.data.token;                         // also: env.data.guest_id, expires_at
}

TOKEN = await guestToken();

func guestToken() (string, error) {
    b, _ := json.Marshal(map[string]string{"slug": "geo-desk"})
    res, err := http.Post(base+"/guest", "application/json", bytes.NewReader(b))
    if err != nil {
        return "", err
    }
    defer res.Body.Close()      // 201 Created
    var env struct {
        Data struct {
            Token     string `json:"token"`
            GuestID   string `json:"guest_id"`
            ExpiresAt string `json:"expires_at"`
        } `json:"data"`
    }
    if err := json.NewDecoder(res.Body).Decode(&env); err != nil {
        return "", err
    }
    return env.Data.Token, nil
}

// POST /guest with {"slug":"geo-desk"} -- the slug travels in the body, not a header.
// Answers 201 with {"data":{"token":"aut_...","guest_id":...,"expires_at":...}}.
static String guestToken() throws Exception {
    HttpRequest req = HttpRequest.newBuilder(URI.create(BASE + "/guest"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString("{\"slug\":\"geo-desk\"}"))
        .build();
    String body = HTTP.send(req, HttpResponse.BodyHandlers.ofString()).body();
    // pull data.token out with your JSON library of choice
    return body;
}

def guest_token
  uri = URI(BASE.to_s + "/guest")
  req = Net::HTTP::Post.new(uri)
  req["Content-Type"] = "application/json"
  req.body = JSON.dump({ slug: "geo-desk" })     # the slug goes in the body
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  JSON.parse(res.body)["data"]["token"]          # 201
end

<?php
function guest_token(): string {
    $ch = curl_init(BASE . "/guest");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["slug" => "geo-desk"]));
    $env = json_decode(curl_exec($ch), true);   // 201
    curl_close($ch);
    return $env["data"]["token"];
}

static async Task<string> GuestToken()
{
    var body = new StringContent("{\"slug\":\"geo-desk\"}", Encoding.UTF8, "application/json");
    var res = await Http.PostAsync(Base + "/guest", body);      // 201 Created
    var env = JsonDocument.Parse(await res.Content.ReadAsStringAsync()).RootElement;
    return env.GetProperty("data").GetProperty("token").GetString();
}

curl -s https://api.skillsafe.ai/v1/app-api/me \
  -H "Authorization: Bearer $TOKEN"
# -> {"data":{"subject_type":"guest","subject_id":"gst_...","credits":0}}
# -> {"data":{"subject_type":"user","subject_id":"usr_...","credits":41500}}
#
# No user_id, no is_guest. Branch on subject_type.

me = call("/me")
# {"subject_type": "user" | "guest", "subject_id": "...", "credits": 41500}
signed_in = me["subject_type"] == "user"    # NOT me.get("is_guest") -- no such field
print(me["credits"], "credits")

const me = await call("/me");
// { subject_type: "user" | "guest", subject_id, credits }
const signedIn = me.subject_type === "user";   // branch on subject_type
console.log(me.credits, "credits");

raw, err := call("/me", nil, "", nil)
if err != nil {
    panic(err)
}
var me struct {
    SubjectType string `json:"subject_type"`
    SubjectID   string `json:"subject_id"`
    Credits     int64  `json:"credits"`
}
json.Unmarshal(raw, &me)
signedIn := me.SubjectType == "user"       // there is no IsGuest to read
_ = signedIn

String me = GeoDesk.call("/me", null, "GET", null);
// data.subject_type is "user" or "guest"; data.credits is the balance.
// There is no is_guest field -- branch on subject_type.
System.out.println(me);

me = call("/me")
signed_in = me["subject_type"] == "user"   # branch on subject_type
puts "#{me['credits']} credits"

<?php
$me = call("/me");
$signedIn = $me["subject_type"] === "user";   // branch on subject_type
echo $me["credits"], " credits\n";

var me = await GeoDesk.Call("/me");
var signedIn = me.GetProperty("subject_type").GetString() == "user";
Console.WriteLine($"{me.GetProperty("credits").GetInt64()} credits");

# FREE and creates no job, but AUTHENTICATED: mint the token first.
# body.json is the input object ITSELF. Never {"input": {...}}.
curl -s -X POST https://api.skillsafe.ai/v1/app-api/estimate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
# -> {"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra","markup_bps":1000,
#             "hold_credits":2870,"min_credits":240,"sponsor_enabled":false}}
#
# Each lane prices separately -- align 2870, validate 3110, report 3640 on this study.

body = {
    "task": "align",                       # price each lane on its own
    "layers": open("layers.txt").read(),
    "matrix": open("matrix.csv").read(),
    "methods": open("methods.txt").read(),
    "product": "categorical",
    "design": "",
    "claim": "The map is 90.6% accurate across the study area.",
    "context": "",
    "prescan_facts": prescan_facts,        # see "The input contract" above
}
est = call("/estimate", body)              # free, no job, but authenticated
assert est["model_alias"] == "gpt-terra" and est["markup_bps"] == 1000
print(est["hold_credits"], "held;", est["min_credits"], "minimum")

const body = {
  task: "align",                    // price each lane on its own
  layers: layersText,
  matrix: matrixText,
  methods: methodsText,
  product: "categorical",
  design: "",
  claim: "The map is 90.6% accurate across the study area.",
  context: "",
  prescan_facts: prescanFacts       // see "The input contract" above
};
const est = await call("/estimate", body);   // free, no job, but authenticated
if (est.model_alias !== "gpt-terra" || est.markup_bps !== 1000) {
  throw new Error("wired to the wrong model: " + est.model_alias);
}
console.log(est.hold_credits, "held,", est.min_credits, "minimum");

body := map[string]any{
    "task":          "align",       // price each lane on its own
    "layers":        layersText,
    "matrix":        matrixText,
    "methods":       methodsText,
    "product":       "categorical",
    "design":        "",
    "claim":         "The map is 90.6% accurate across the study area.",
    "context":       "",
    "prescan_facts": prescanFacts,
}
raw, err := call("/estimate", body, "", nil)   // free, no job
if err != nil {
    panic(err)
}
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"`
}
json.Unmarshal(raw, &est)
if est.ModelAlias != "gpt-terra" || est.MarkupBps != 1000 {
    panic("wired to the wrong model: " + est.ModelAlias)
}

// The body is the input object itself. Never wrap it in an "input" key.
String body = """
    {"task":"align","layers":"layer: lc_2024_classified\\nkind: raster\\n...",
     "matrix":"orientation: rows = map\\nmap_class, forest, cropland, ...",
     "methods":"Validation used 480 points, 120 per class...",
     "product":"categorical","design":"","claim":"The map is 90.6% accurate.",
     "context":"","prescan_facts":{"readable":true,"verdict":"needs_rework"}}
    """;
String est = GeoDesk.call("/estimate", body, "POST", null);   // free, no job
// assert data.model_alias == "gpt-terra" and data.markup_bps == 1000
System.out.println(est);

body = {
  task: "align",                       # price each lane on its own
  layers: File.read("layers.txt"),
  matrix: File.read("matrix.csv"),
  methods: File.read("methods.txt"),
  product: "categorical",
  design: "",
  claim: "The map is 90.6% accurate across the study area.",
  context: "",
  prescan_facts: prescan_facts
}
est = call("/estimate", body)          # free, no job, but authenticated
raise "wrong model" unless est["model_alias"] == "gpt-terra" && est["markup_bps"] == 1000
puts "#{est['hold_credits']} held, #{est['min_credits']} minimum"

<?php
$body = [
    "task"          => "align",          // price each lane on its own
    "layers"        => file_get_contents("layers.txt"),
    "matrix"        => file_get_contents("matrix.csv"),
    "methods"       => file_get_contents("methods.txt"),
    "product"       => "categorical",
    "design"        => "",
    "claim"         => "The map is 90.6% accurate across the study area.",
    "context"       => "",
    "prescan_facts" => $prescanFacts,
];
$est = call("/estimate", $body);         // free, no job, but authenticated
if ($est["model_alias"] !== "gpt-terra" || $est["markup_bps"] !== 1000) {
    throw new RuntimeException("wired to the wrong model");
}
echo $est["hold_credits"], " held\n";

var body = new {
    task = "align",                      // price each lane on its own
    layers = layersText,
    matrix = matrixText,
    methods = methodsText,
    product = "categorical",
    design = "",
    claim = "The map is 90.6% accurate across the study area.",
    context = "",
    prescan_facts = prescanFacts
};
var est = await GeoDesk.Call("/estimate", body);   // free, no job
if (est.GetProperty("model_alias").GetString() != "gpt-terra"
    || est.GetProperty("markup_bps").GetInt32() != 1000)
    throw new Exception("wired to the wrong model");
Console.WriteLine(est.GetProperty("hold_credits").GetInt64());

# METERED. The Idempotency-Key is what stops a retry double-billing.
curl -s -X POST https://api.skillsafe.ai/v1/app-api/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: geo-desk:align:9f31c7a4e0:a1" \
  -d @body.json
# -> {"data":{"job_id":"job_7Qd2..."}}

# then poll until terminal
curl -s "https://api.skillsafe.ai/v1/app-api/jobs/job_7Qd2..." \
  -H "Authorization: Bearer $TOKEN"
# -> data.status          queued | running | succeeded | failed
#    data.output.output   the JSON string the model produced
#    data.charged_credits the ACTUAL cost, usually well under hold_credits
#    data.truncated       true when a thin balance forced a reduced output cap

import time

key = "geo-desk:align:" + input_hash + ":a1"     # the LANE is inside the key
job_id = call("/run", body, extra_headers={"Idempotency-Key": key})["job_id"]

while True:
    job = call("/jobs/" + job_id)
    if job["status"] in ("succeeded", "failed"):
        break
    time.sleep(1.5)                              # fixed interval, never a tight loop

if job["status"] == "failed":
    raise RuntimeError(job.get("error") or "the job failed")
result = json.loads(job["output"]["output"])     # the output contract above
print(result["lane"], result["verdict"], "-", result["headline"])
print("charged", job["charged_credits"], "credits; truncated:", job.get("truncated"))
for section, sec in result["body"].items():
    print(section, "->", sec["statement"])

const key = `geo-desk:align:${inputHash}:a1`;   // the LANE is inside the key
const { job_id } = await call("/run", body, "POST", { "Idempotency-Key": key });

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

if (job.status === "failed") throw new Error(job.error || "the job failed");
const result = JSON.parse(job.output.output);
console.log(result.lane, result.verdict, result.headline);
console.log("charged", job.charged_credits, "truncated", job.truncated);
for (const [name, sec] of Object.entries(result.body)) {
  console.log(name, "->", sec.statement, sec.points.length + " points");
}

key := "geo-desk:align:" + inputHash + ":a1"   // the LANE is inside the key
raw, err := call("/run", body, "POST", map[string]string{"Idempotency-Key": key})
if err != nil {
    panic(err)
}
var started struct{ JobID string `json:"job_id"` }
json.Unmarshal(raw, &started)

for {
    time.Sleep(1500 * time.Millisecond)
    raw, err = call("/jobs/"+started.JobID, nil, "", nil)
    if err != nil {
        panic(err)
    }
    var job struct {
        Status         string `json:"status"`
        ChargedCredits int64  `json:"charged_credits"`
        Truncated      bool   `json:"truncated"`
        Output         struct{ Output string `json:"output"` } `json:"output"`
    }
    json.Unmarshal(raw, &job)
    if job.Status == "succeeded" || job.Status == "failed" {
        // job.Output.Output is the JSON string described in the output contract
        break
    }
}

// POST /run with the Idempotency-Key header, then poll GET /jobs/{id}.
// The key must include the lane: two lanes over one study are two distinct runs.
String key = "geo-desk:align:" + inputHash + ":a1";
String started = GeoDesk.call("/run", body, "POST", key);
String jobId = /* started -> data.job_id */ parseJobId(started);

String status = "queued";
String job = null;
while (!status.equals("succeeded") && !status.equals("failed")) {
    Thread.sleep(1500);
    job = GeoDesk.call("/jobs/" + jobId, null, "GET", null);
    status = parseStatus(job);
}
// data.output.output is the JSON string; data.charged_credits is the real cost.

key = "geo-desk:align:#{input_hash}:a1"        # the LANE is inside the key
job_id = call("/run", body, "POST", { "Idempotency-Key" => key })["job_id"]

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

result = JSON.parse(job["output"]["output"])
puts "#{result['lane']} #{result['verdict']} - #{result['headline']}"
puts "charged #{job['charged_credits']}, truncated #{job['truncated']}"

<?php
$key = "geo-desk:align:" . $inputHash . ":a1";   // the LANE is inside the key
$jobId = call("/run", $body, "POST", ["Idempotency-Key: " . $key])["job_id"];

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

if ($job["status"] === "failed") { throw new RuntimeException("the job failed"); }
$result = json_decode($job["output"]["output"], true);
echo $result["lane"], " ", $result["verdict"], " - charged ",
     $job["charged_credits"], "\n";

var key = $"geo-desk:align:{inputHash}:a1";      // the LANE is inside the key
var started = await GeoDesk.Call("/run", body, "POST", key);
var jobId = started.GetProperty("job_id").GetString();

JsonElement job;
string status;
do {
    await Task.Delay(1500);
    job = await GeoDesk.Call("/jobs/" + jobId);
    status = job.GetProperty("status").GetString();
} while (status is not ("succeeded" or "failed"));

if (status == "failed") throw new Exception("the job failed");
var result = JsonDocument.Parse(
    job.GetProperty("output").GetProperty("output").GetString()).RootElement;
Console.WriteLine(result.GetProperty("verdict").GetString());

# METERED, Server-Sent Events. Same Idempotency-Key rules as /run.
curl -N -X POST https://api.skillsafe.ai/v1/app-api/run-stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: geo-desk:report:9f31c7a4e0:a1" \
  -d @body.json
# event: job    data: {"job_id":"job_7Qd2..."}
# event: delta  data: {"text":"{\"lane\":\"report\","}
# event: delta  data: {"text":"\"verdict\":\"needs_rework\","}
# event: delta  data: {"text":"\"headline\":\"90.6% is the sample estimate"}
# event: done   data: {"status":"succeeded","charged_credits":1980,"truncated":false}
#
# Accumulate every delta's text; parse once, at the end.

req = urllib.request.Request(BASE + "/run-stream",
                             data=json.dumps(body).encode(), method="POST")
req.add_header("Content-Type", "application/json")
req.add_header("Authorization", "Bearer " + TOKEN)
req.add_header("Idempotency-Key", "geo-desk:report:" + input_hash + ":a1")

raw, done, event = "", None, None
with urllib.request.urlopen(req) as r:
    for line in r:
        line = line.decode().rstrip("\n")
        if line.startswith("event: "):
            event = line[7:]
        elif line.startswith("data: "):
            payload = json.loads(line[6:])
            if event == "delta":
                raw += payload["text"]       # fragments split mid-key; just append
            elif event == "done":
                done = payload

result = json.loads(raw)
print(result["verdict"], "-", result["body"]["estimator_review"]["statement"])
print("charged", done["charged_credits"])

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

const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = "", raw = "", event = null, done = null;
for (;;) {
  const { value, done: fin } = await reader.read();
  if (fin) 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(7);
    else if (line.startsWith("data: ")) {
      const p = JSON.parse(line.slice(6));
      if (event === "delta") raw += p.text;
      else if (event === "done") done = p;
    }
  }
}
const result = JSON.parse(raw);
console.log(result.verdict, "charged", done.charged_credits);

req, _ := http.NewRequest("POST", base+"/run-stream", bytes.NewReader(mustJSON(body)))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "geo-desk:report:"+inputHash+":a1")
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)     // a delta frame can be long
var raw strings.Builder
event := ""
for sc.Scan() {
    line := sc.Text()
    switch {
    case strings.HasPrefix(line, "event: "):
        event = strings.TrimPrefix(line, "event: ")
    case strings.HasPrefix(line, "data: ") && event == "delta":
        var p struct{ Text string `json:"text"` }
        json.Unmarshal([]byte(strings.TrimPrefix(line, "data: ")), &p)
        raw.WriteString(p.Text)
    }
}
// raw.String() is the whole JSON object -- parse it once, here.

// POST /run-stream and read the response as lines. "event: delta" frames carry
// {"text": "..."} fragments to concatenate; "event: done" carries the settlement.
HttpRequest req = HttpRequest.newBuilder(URI.create(BASE + "/run-stream"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer " + token)
    .header("Idempotency-Key", "geo-desk:report:" + inputHash + ":a1")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<java.util.stream.Stream<String>> res =
    HTTP.send(req, HttpResponse.BodyHandlers.ofLines());

StringBuilder raw = new StringBuilder();
final String[] event = {""};
res.body().forEach(line -> {
    if (line.startsWith("event: ")) event[0] = line.substring(7);
    else if (line.startsWith("data: ") && event[0].equals("delta"))
        raw.append(textFieldOf(line.substring(6)));   // your JSON library
});

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"] = "geo-desk:report:#{input_hash}:a1"
req.body = JSON.dump(body)

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

<?php
$ch = curl_init(BASE . "/run-stream");
$raw = "";
$event = null;
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . TOKEN,
    "Idempotency-Key: geo-desk:report:" . $inputHash . ":a1",
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
curl_setopt($ch, CURLOPT_WRITEFUNCTION,
    function ($ch, $chunk) use (&$raw, &$event) {
        foreach (explode("\n", $chunk) as $line) {
            if (str_starts_with($line, "event: ")) {
                $event = substr($line, 7);
            } elseif (str_starts_with($line, "data: ") && $event === "delta") {
                $raw .= json_decode(substr($line, 6), true)["text"];
            }
        }
        return strlen($chunk);
    });
curl_exec($ch);
curl_close($ch);
$result = json_decode($raw, true);

var req = new HttpRequestMessage(HttpMethod.Post, Base + "/run-stream");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
req.Headers.Add("Idempotency-Key", $"geo-desk:report:{inputHash}:a1");
req.Content = new StringContent(JsonSerializer.Serialize(body),
                                Encoding.UTF8, "application/json");

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

# The three pasted blocks live in three files, verbatim.
cat > layers.txt <<'TXT'
layer: lc_2024_classified
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 1
dtype: uint8
nodata: 255
role: target

layer: s2_summer_composite
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 10
dtype: uint16
nodata: 0
role: predictor

layer: dem_srtm_void_filled
kind: raster
crs: EPSG:4326
pixel_size: 0.000277778
extent: 12.0, 64.8, 14.4, 65.9
bands: 1
dtype: int16
nodata: -32768
role: predictor

layer: validation_points
kind: vector
crs: EPSG:32633
geometry: point
features: 480
role: samples

layer: study_area
kind: vector
crs: EPSG:32633
geometry: polygon
features: 1
role: aoi
TXT

cat > matrix.csv <<'TXT'
orientation: rows = map
map_class, forest, cropland, water, built, area_ha
forest,      101,       12,     3,     4,   41820
cropland,      9,      106,     2,     3,   26310
water,         2,        1,   115,     2,    9640
built,         3,        4,     0,   113,    5230
TXT

cat > methods.txt <<'TXT'
The 2024 land-cover map was classified from a Sentinel-2 summer composite and an
SRTM-derived slope layer with a random forest at 10 m.
Validation used 480 points, 120 per class, interpreted from 0.5 m aerial imagery.
Overall accuracy is 90.6% and kappa is 0.875.
Class areas were read from the pixel counts of the classified map.
Training points came from the same field campaign; no minimum separation was
enforced between training and validation locations.
TXT

# Build the body from them. The object is the body: there is no "input" wrapper.
jq -n --rawfile layers layers.txt \
      --rawfile matrix matrix.csv \
      --rawfile methods methods.txt \
      --slurpfile facts prescan.json \
  '{task: "align", layers: $layers, matrix: $matrix, methods: $methods,
    product: "categorical", design: "", context: "",
    claim: "The layer stack is ready for a per-pixel accuracy extraction.",
    prescan_facts: $facts[0]}' > align.json

curl -s -X POST https://api.skillsafe.ai/v1/app-api/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: geo-desk:align:9f31c7a4e0:a1" \
  -d @align.json

LAYERS = """\
layer: lc_2024_classified
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 1
dtype: uint8
nodata: 255
role: target

layer: s2_summer_composite
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 10
dtype: uint16
nodata: 0
role: predictor

layer: dem_srtm_void_filled
kind: raster
crs: EPSG:4326
pixel_size: 0.000277778
extent: 12.0, 64.8, 14.4, 65.9
bands: 1
dtype: int16
nodata: -32768
role: predictor

layer: validation_points
kind: vector
crs: EPSG:32633
geometry: point
features: 480
role: samples

layer: study_area
kind: vector
crs: EPSG:32633
geometry: polygon
features: 1
role: aoi
"""

MATRIX = """\
orientation: rows = map
map_class, forest, cropland, water, built, area_ha
forest,      101,       12,     3,     4,   41820
cropland,      9,      106,     2,     3,   26310
water,         2,        1,   115,     2,    9640
built,         3,        4,     0,   113,    5230
"""

METHODS = """\
The 2024 land-cover map was classified from a Sentinel-2 summer composite and an
SRTM-derived slope layer with a random forest at 10 m.
Validation used 480 points, 120 per class, interpreted from 0.5 m aerial imagery.
Overall accuracy is 90.6% and kappa is 0.875.
Class areas were read from the pixel counts of the classified map.
Training points came from the same field campaign; no minimum separation was
enforced between training and validation locations.
"""

align = {
    "task": "align",
    "layers": LAYERS,
    "matrix": MATRIX,
    "methods": METHODS,
    "product": "categorical",
    "design": "",
    "claim": "The layer stack is ready for a per-pixel accuracy extraction.",
    "context": "The DEM is the only layer I did not reproject myself.",
    "prescan_facts": prescan_facts,
}
job_id = call("/run", align,
              extra_headers={"Idempotency-Key": "geo-desk:align:" + input_hash + ":a1"})["job_id"]
# ... poll, then:
out = json.loads(job["output"]["output"])
print(out["body"]["resampling_plan"]["statement"])
for p in out["body"]["nodata_plan"]["points"]:
    print(" -", p)

const LAYERS = `\
layer: lc_2024_classified
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 1
dtype: uint8
nodata: 255
role: target

layer: s2_summer_composite
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 10
dtype: uint16
nodata: 0
role: predictor

layer: dem_srtm_void_filled
kind: raster
crs: EPSG:4326
pixel_size: 0.000277778
extent: 12.0, 64.8, 14.4, 65.9
bands: 1
dtype: int16
nodata: -32768
role: predictor

layer: validation_points
kind: vector
crs: EPSG:32633
geometry: point
features: 480
role: samples

layer: study_area
kind: vector
crs: EPSG:32633
geometry: polygon
features: 1
role: aoi
`;

const MATRIX = `\
orientation: rows = map
map_class, forest, cropland, water, built, area_ha
forest,      101,       12,     3,     4,   41820
cropland,      9,      106,     2,     3,   26310
water,         2,        1,   115,     2,    9640
built,         3,        4,     0,   113,    5230
`;

const METHODS = `\
The 2024 land-cover map was classified from a Sentinel-2 summer composite and an
SRTM-derived slope layer with a random forest at 10 m.
Validation used 480 points, 120 per class, interpreted from 0.5 m aerial imagery.
Overall accuracy is 90.6% and kappa is 0.875.
Class areas were read from the pixel counts of the classified map.
Training points came from the same field campaign; no minimum separation was
enforced between training and validation locations.
`;

const align = {
  task: "align",
  layers: LAYERS,
  matrix: MATRIX,
  methods: METHODS,
  product: "categorical",
  design: "",
  claim: "The layer stack is ready for a per-pixel accuracy extraction.",
  context: "The DEM is the only layer I did not reproject myself.",
  prescan_facts: prescanFacts
};
const { job_id } = await call("/run", align, "POST",
  { "Idempotency-Key": `geo-desk:align:${inputHash}:a1` });
// ... poll, then:
console.log(out.body.resampling_plan.statement);
out.body.nodata_plan.points.forEach((p) => console.log(" -", p));

const layers = `layer: lc_2024_classified
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 1
dtype: uint8
nodata: 255
role: target

layer: s2_summer_composite
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 10
dtype: uint16
nodata: 0
role: predictor

layer: dem_srtm_void_filled
kind: raster
crs: EPSG:4326
pixel_size: 0.000277778
extent: 12.0, 64.8, 14.4, 65.9
bands: 1
dtype: int16
nodata: -32768
role: predictor

layer: validation_points
kind: vector
crs: EPSG:32633
geometry: point
features: 480
role: samples

layer: study_area
kind: vector
crs: EPSG:32633
geometry: polygon
features: 1
role: aoi
`

const matrix = `orientation: rows = map
map_class, forest, cropland, water, built, area_ha
forest,      101,       12,     3,     4,   41820
cropland,      9,      106,     2,     3,   26310
water,         2,        1,   115,     2,    9640
built,         3,        4,     0,   113,    5230
`

const methods = `The 2024 land-cover map was classified from a Sentinel-2 summer composite and an
SRTM-derived slope layer with a random forest at 10 m.
Validation used 480 points, 120 per class, interpreted from 0.5 m aerial imagery.
Overall accuracy is 90.6% and kappa is 0.875.
Class areas were read from the pixel counts of the classified map.
Training points came from the same field campaign; no minimum separation was
enforced between training and validation locations.
`

align := map[string]any{
    "task":          "align",
    "layers":        layers,
    "matrix":        matrix,
    "methods":       methods,
    "product":       "categorical",
    "design":        "",
    "claim":         "The layer stack is ready for a per-pixel accuracy extraction.",
    "context":       "The DEM is the only layer I did not reproject myself.",
    "prescan_facts": prescanFacts,
}
raw, err := call("/run", align, "POST",
    map[string]string{"Idempotency-Key": "geo-desk:align:" + inputHash + ":a1"})

static final String LAYERS = """
    layer: lc_2024_classified
    kind: raster
    crs: EPSG:32633
    pixel_size: 10
    extent: 499980, 7190200, 609780, 7300000
    bands: 1
    dtype: uint8
    nodata: 255
    role: target

    layer: s2_summer_composite
    kind: raster
    crs: EPSG:32633
    pixel_size: 10
    extent: 499980, 7190200, 609780, 7300000
    bands: 10
    dtype: uint16
    nodata: 0
    role: predictor

    layer: dem_srtm_void_filled
    kind: raster
    crs: EPSG:4326
    pixel_size: 0.000277778
    extent: 12.0, 64.8, 14.4, 65.9
    bands: 1
    dtype: int16
    nodata: -32768
    role: predictor

    layer: validation_points
    kind: vector
    crs: EPSG:32633
    geometry: point
    features: 480
    role: samples

    layer: study_area
    kind: vector
    crs: EPSG:32633
    geometry: polygon
    features: 1
    role: aoi
    """;

static final String MATRIX = """
    orientation: rows = map
    map_class, forest, cropland, water, built, area_ha
    forest,      101,       12,     3,     4,   41820
    cropland,      9,      106,     2,     3,   26310
    water,         2,        1,   115,     2,    9640
    built,         3,        4,     0,   113,    5230
    """;

static final String METHODS = """
    The 2024 land-cover map was classified from a Sentinel-2 summer composite and an
    SRTM-derived slope layer with a random forest at 10 m.
    Validation used 480 points, 120 per class, interpreted from 0.5 m aerial imagery.
    Overall accuracy is 90.6% and kappa is 0.875.
    Class areas were read from the pixel counts of the classified map.
    Training points came from the same field campaign; no minimum separation was
    enforced between training and validation locations.
    """;

// Build the JSON with a real library; the field order does not matter.
String align = jsonOf(
    "task", "align",
    "layers", LAYERS,
    "matrix", MATRIX,
    "methods", METHODS,
    "product", "categorical",
    "design", "",
    "claim", "The layer stack is ready for a per-pixel accuracy extraction.",
    "context", "The DEM is the only layer I did not reproject myself.",
    "prescan_facts", prescanFacts);
String started = GeoDesk.call("/run", align, "POST",
    "geo-desk:align:" + inputHash + ":a1");

LAYERS = <<~TXT
  layer: lc_2024_classified
  kind: raster
  crs: EPSG:32633
  pixel_size: 10
  extent: 499980, 7190200, 609780, 7300000
  bands: 1
  dtype: uint8
  nodata: 255
  role: target

  layer: s2_summer_composite
  kind: raster
  crs: EPSG:32633
  pixel_size: 10
  extent: 499980, 7190200, 609780, 7300000
  bands: 10
  dtype: uint16
  nodata: 0
  role: predictor

  layer: dem_srtm_void_filled
  kind: raster
  crs: EPSG:4326
  pixel_size: 0.000277778
  extent: 12.0, 64.8, 14.4, 65.9
  bands: 1
  dtype: int16
  nodata: -32768
  role: predictor

  layer: validation_points
  kind: vector
  crs: EPSG:32633
  geometry: point
  features: 480
  role: samples

  layer: study_area
  kind: vector
  crs: EPSG:32633
  geometry: polygon
  features: 1
  role: aoi
TXT

MATRIX = <<~TXT
  orientation: rows = map
  map_class, forest, cropland, water, built, area_ha
  forest,      101,       12,     3,     4,   41820
  cropland,      9,      106,     2,     3,   26310
  water,         2,        1,   115,     2,    9640
  built,         3,        4,     0,   113,    5230
TXT

METHODS = <<~TXT
  The 2024 land-cover map was classified from a Sentinel-2 summer composite and an
  SRTM-derived slope layer with a random forest at 10 m.
  Validation used 480 points, 120 per class, interpreted from 0.5 m aerial imagery.
  Overall accuracy is 90.6% and kappa is 0.875.
  Class areas were read from the pixel counts of the classified map.
  Training points came from the same field campaign; no minimum separation was
  enforced between training and validation locations.
TXT

align = {
  task: "align",
  layers: LAYERS,
  matrix: MATRIX,
  methods: METHODS,
  product: "categorical",
  design: "",
  claim: "The layer stack is ready for a per-pixel accuracy extraction.",
  context: "The DEM is the only layer I did not reproject myself.",
  prescan_facts: prescan_facts
}
job_id = call("/run", align, "POST",
              { "Idempotency-Key" => "geo-desk:align:#{input_hash}:a1" })["job_id"]

<?php
$layers = <<<'TXT'
layer: lc_2024_classified
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 1
dtype: uint8
nodata: 255
role: target

layer: s2_summer_composite
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 10
dtype: uint16
nodata: 0
role: predictor

layer: dem_srtm_void_filled
kind: raster
crs: EPSG:4326
pixel_size: 0.000277778
extent: 12.0, 64.8, 14.4, 65.9
bands: 1
dtype: int16
nodata: -32768
role: predictor

layer: validation_points
kind: vector
crs: EPSG:32633
geometry: point
features: 480
role: samples

layer: study_area
kind: vector
crs: EPSG:32633
geometry: polygon
features: 1
role: aoi
TXT;

$matrix = <<<'TXT'
orientation: rows = map
map_class, forest, cropland, water, built, area_ha
forest,      101,       12,     3,     4,   41820
cropland,      9,      106,     2,     3,   26310
water,         2,        1,   115,     2,    9640
built,         3,        4,     0,   113,    5230
TXT;

$methods = <<<'TXT'
The 2024 land-cover map was classified from a Sentinel-2 summer composite and an
SRTM-derived slope layer with a random forest at 10 m.
Validation used 480 points, 120 per class, interpreted from 0.5 m aerial imagery.
Overall accuracy is 90.6% and kappa is 0.875.
Class areas were read from the pixel counts of the classified map.
Training points came from the same field campaign; no minimum separation was
enforced between training and validation locations.
TXT;

$align = [
    "task"          => "align",
    "layers"        => $layers,
    "matrix"        => $matrix,
    "methods"       => $methods,
    "product"       => "categorical",
    "design"        => "",
    "claim"         => "The layer stack is ready for a per-pixel accuracy extraction.",
    "context"       => "The DEM is the only layer I did not reproject myself.",
    "prescan_facts" => $prescanFacts,
];
$jobId = call("/run", $align, "POST",
    ["Idempotency-Key: geo-desk:align:" . $inputHash . ":a1"])["job_id"];

const string Layers = """
layer: lc_2024_classified
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 1
dtype: uint8
nodata: 255
role: target

layer: s2_summer_composite
kind: raster
crs: EPSG:32633
pixel_size: 10
extent: 499980, 7190200, 609780, 7300000
bands: 10
dtype: uint16
nodata: 0
role: predictor

layer: dem_srtm_void_filled
kind: raster
crs: EPSG:4326
pixel_size: 0.000277778
extent: 12.0, 64.8, 14.4, 65.9
bands: 1
dtype: int16
nodata: -32768
role: predictor

layer: validation_points
kind: vector
crs: EPSG:32633
geometry: point
features: 480
role: samples

layer: study_area
kind: vector
crs: EPSG:32633
geometry: polygon
features: 1
role: aoi
""";

const string Matrix = """
orientation: rows = map
map_class, forest, cropland, water, built, area_ha
forest,      101,       12,     3,     4,   41820
cropland,      9,      106,     2,     3,   26310
water,         2,        1,   115,     2,    9640
built,         3,        4,     0,   113,    5230
""";

const string Methods = """
The 2024 land-cover map was classified from a Sentinel-2 summer composite and an
SRTM-derived slope layer with a random forest at 10 m.
Validation used 480 points, 120 per class, interpreted from 0.5 m aerial imagery.
Overall accuracy is 90.6% and kappa is 0.875.
Class areas were read from the pixel counts of the classified map.
Training points came from the same field campaign; no minimum separation was
enforced between training and validation locations.
""";

var align = new {
    task = "align",
    layers = Layers,
    matrix = Matrix,
    methods = Methods,
    product = "categorical",
    design = "",
    claim = "The layer stack is ready for a per-pixel accuracy extraction.",
    context = "The DEM is the only layer I did not reproject myself.",
    prescan_facts = prescanFacts
};
var started = await GeoDesk.Call("/run", align, "POST",
    $"geo-desk:align:{inputHash}:a1");

# Reuse the same three files; only the routing fields change.
jq -n --rawfile layers layers.txt \
      --rawfile matrix matrix.csv \
      --rawfile methods methods.txt \
      --slurpfile facts prescan.json \
  '{task: "validate", layers: $layers, matrix: $matrix, methods: $methods,
    product: "categorical", design: "stratified_random",
    claim: "The map is 90.6% accurate across the study area.",
    context: "Training and validation points were collected on the same field days.",
    prescan_facts: $facts[0]}' > validate.json

# A DIFFERENT lane, so a DIFFERENT idempotency key over the same study.
curl -s -X POST https://api.skillsafe.ai/v1/app-api/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: geo-desk:validate:9f31c7a4e0:a1" \
  -d @validate.json

validate = dict(align,
    task="validate",
    design="stratified_random",             # fills a silence only; the prose wins
    claim="The map is 90.6% accurate across the study area.",
    context="Training and validation points were collected on the same field days.")

job_id = call("/run", validate, extra_headers={
    "Idempotency-Key": "geo-desk:validate:" + input_hash + ":a1"})["job_id"]
# ... poll, then:
out = json.loads(job["output"]["output"])
print(out["body"]["leakage_review"]["statement"])
print(out["body"]["redesign_plan"]["points"])
for r in out["reconciliation"]:
    print(r["flag_uid"], r["status"], r["note"])

const validate = {
  ...align,
  task: "validate",
  design: "stratified_random",          // fills a silence only; the prose wins
  claim: "The map is 90.6% accurate across the study area.",
  context: "Training and validation points were collected on the same field days."
};
const { job_id } = await call("/run", validate, "POST",
  { "Idempotency-Key": `geo-desk:validate:${inputHash}:a1` });
// ... poll, then:
console.log(out.body.leakage_review.statement);
console.log(out.body.allocation_review.points.join("\n"));

validate := map[string]any{}
for k, v := range align {
    validate[k] = v
}
validate["task"] = "validate"
validate["design"] = "stratified_random"   // fills a silence only; the prose wins
validate["claim"] = "The map is 90.6% accurate across the study area."
validate["context"] = "Training and validation points were collected on the same field days."

raw, err := call("/run", validate, "POST",
    map[string]string{"Idempotency-Key": "geo-desk:validate:" + inputHash + ":a1"})

// Same three texts, new routing fields.
String validate = jsonOf(
    "task", "validate",
    "layers", LAYERS,
    "matrix", MATRIX,
    "methods", METHODS,
    "product", "categorical",
    "design", "stratified_random",   // fills a silence only; the prose wins
    "claim", "The map is 90.6% accurate across the study area.",
    "context", "Training and validation points were collected on the same field days.",
    "prescan_facts", prescanFacts);
String started = GeoDesk.call("/run", validate, "POST",
    "geo-desk:validate:" + inputHash + ":a1");

validate = align.merge(
  task: "validate",
  design: "stratified_random",        # fills a silence only; the prose wins
  claim: "The map is 90.6% accurate across the study area.",
  context: "Training and validation points were collected on the same field days."
)
job_id = call("/run", validate, "POST",
              { "Idempotency-Key" => "geo-desk:validate:#{input_hash}:a1" })["job_id"]

<?php
$validate = array_merge($align, [
    "task"    => "validate",
    "design"  => "stratified_random",   // fills a silence only; the prose wins
    "claim"   => "The map is 90.6% accurate across the study area.",
    "context" => "Training and validation points were collected on the same field days.",
]);
$jobId = call("/run", $validate, "POST",
    ["Idempotency-Key: geo-desk:validate:" . $inputHash . ":a1"])["job_id"];

var validate = new {
    task = "validate",
    layers = Layers,
    matrix = Matrix,
    methods = Methods,
    product = "categorical",
    design = "stratified_random",       // fills a silence only; the prose wins
    claim = "The map is 90.6% accurate across the study area.",
    context = "Training and validation points were collected on the same field days.",
    prescan_facts = prescanFacts
};
var started = await GeoDesk.Call("/run", validate, "POST",
    $"geo-desk:validate:{inputHash}:a1");

jq -n --rawfile layers layers.txt \
      --rawfile matrix matrix.csv \
      --rawfile methods methods.txt \
      --slurpfile facts prescan.json \
  '{task: "report", layers: $layers, matrix: $matrix, methods: $methods,
    product: "categorical", design: "stratified_random",
    claim: "Forest covers 41,820 ha of the study area, mapped at 90.6% overall accuracy.",
    context: "The figure goes into a national reporting annex.",
    prescan_facts: $facts[0]}' > report.json

curl -s -X POST https://api.skillsafe.ai/v1/app-api/run-stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: geo-desk:report:9f31c7a4e0:a1" \
  -d @report.json
# report holds the most credits of the three lanes: it writes drafted_methods.

report = dict(align,
    task="report",
    design="stratified_random",
    claim="Forest covers 41,820 ha of the study area, mapped at 90.6% overall accuracy.",
    context="The figure goes into a national reporting annex.")

job_id = call("/run", report, extra_headers={
    "Idempotency-Key": "geo-desk:report:" + input_hash + ":a1"})["job_id"]
# ... poll, then:
out = json.loads(job["output"]["output"])
print(out["body"]["accuracy_statement"]["statement"])
print(out["body"]["area_statement"]["points"])
print(out["body"]["drafted_methods"]["statement"])    # paste-ready paragraph
for c in out["context_notes"]:
    print(c["status"], "-", c["claim"])               # honoured | contradicted | unverifiable

const report = {
  ...align,
  task: "report",
  design: "stratified_random",
  claim: "Forest covers 41,820 ha of the study area, mapped at 90.6% overall accuracy.",
  context: "The figure goes into a national reporting annex."
};
const { job_id } = await call("/run", report, "POST",
  { "Idempotency-Key": `geo-desk:report:${inputHash}:a1` });
// ... poll, then:
console.log(out.body.estimator_review.statement);
console.log(out.body.drafted_methods.statement);
out.context_notes.forEach((c) => console.log(c.status, c.claim));

report := map[string]any{}
for k, v := range align {
    report[k] = v
}
report["task"] = "report"
report["design"] = "stratified_random"
report["claim"] = "Forest covers 41,820 ha of the study area, mapped at 90.6% overall accuracy."
report["context"] = "The figure goes into a national reporting annex."

raw, err := call("/run", report, "POST",
    map[string]string{"Idempotency-Key": "geo-desk:report:" + inputHash + ":a1"})

String report = jsonOf(
    "task", "report",
    "layers", LAYERS,
    "matrix", MATRIX,
    "methods", METHODS,
    "product", "categorical",
    "design", "stratified_random",
    "claim", "Forest covers 41,820 ha of the study area, mapped at 90.6% overall accuracy.",
    "context", "The figure goes into a national reporting annex.",
    "prescan_facts", prescanFacts);
String started = GeoDesk.call("/run", report, "POST",
    "geo-desk:report:" + inputHash + ":a1");
// body.drafted_methods.statement is the paragraph to paste into the manuscript.

report = align.merge(
  task: "report",
  design: "stratified_random",
  claim: "Forest covers 41,820 ha of the study area, mapped at 90.6% overall accuracy.",
  context: "The figure goes into a national reporting annex."
)
job_id = call("/run", report, "POST",
              { "Idempotency-Key" => "geo-desk:report:#{input_hash}:a1" })["job_id"]

<?php
$report = array_merge($align, [
    "task"    => "report",
    "design"  => "stratified_random",
    "claim"   => "Forest covers 41,820 ha of the study area, mapped at 90.6% overall accuracy.",
    "context" => "The figure goes into a national reporting annex.",
]);
$jobId = call("/run", $report, "POST",
    ["Idempotency-Key: geo-desk:report:" . $inputHash . ":a1"])["job_id"];

var report = new {
    task = "report",
    layers = Layers,
    matrix = Matrix,
    methods = Methods,
    product = "categorical",
    design = "stratified_random",
    claim = "Forest covers 41,820 ha of the study area, mapped at 90.6% overall accuracy.",
    context = "The figure goes into a national reporting annex.",
    prescan_facts = prescanFacts
};
var started = await GeoDesk.Call("/run", report, "POST",
    $"geo-desk:report:{inputHash}:a1");

# Hash the lane together with the three blocks. Order matters, so keep it fixed.
HASH=$( { printf 'align\n'; cat layers.txt matrix.csv methods.txt; } \
        | shasum -a 256 | cut -c1-10 )
KEY="geo-desk:align:$HASH:a1"

curl -s -X POST https://api.skillsafe.ai/v1/app-api/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d @align.json

# Retrying a 500: send the SAME key, unchanged -- you get the original run back.
# Retrying an unparseable reply: bump the attempt, "...:a2", same hash.

import hashlib

def idem_key(body, attempt=1):
    material = "\x1f".join([
        body["task"],                      # the LANE is part of the content
        body["layers"], body["matrix"], body.get("methods", ""),
        body.get("product", ""), body.get("design", ""), body.get("claim", ""),
    ])
    digest = hashlib.sha256(material.encode("utf-8")).hexdigest()[:10]
    return "geo-desk:%s:%s:a%d" % (body["task"], digest, attempt)

key = idem_key(align)                      # geo-desk:align:9f31c7a4e0:a1
job = call("/run", align, extra_headers={"Idempotency-Key": key})

# One reformat retry, same input, bumped attempt -- cannot double-bill the first one.
retry = call("/run", align, extra_headers={"Idempotency-Key": idem_key(align, 2)})

async function idemKey(body, attempt = 1) {
  const material = [
    body.task,                             // the LANE is part of the content
    body.layers, body.matrix, body.methods || "",
    body.product || "", body.design || "", body.claim || ""
  ].join("\u001f");
  const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(material));
  const hex = [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
  return `geo-desk:${body.task}:${hex.slice(0, 10)}:a${attempt}`;
}

const key = await idemKey(align);          // geo-desk:align:9f31c7a4e0:a1
await call("/run", align, "POST", { "Idempotency-Key": key });

func idemKey(task, layers, matrix, methods, product, design, claim string, attempt int) string {
    material := strings.Join([]string{
        task,                              // the LANE is part of the content
        layers, matrix, methods, product, design, claim,
    }, "\x1f")
    sum := sha256.Sum256([]byte(material))
    return fmt.Sprintf("geo-desk:%s:%s:a%d", task, hex.EncodeToString(sum[:])[:10], attempt)
}

key := idemKey("align", layers, matrix, methods, "categorical", "", claim, 1)
raw, err := call("/run", align, "POST", map[string]string{"Idempotency-Key": key})

static String idemKey(String task, String layers, String matrix, String methods,
                      String product, String design, String claim, int attempt)
        throws Exception {
    String material = String.join("\u001f",
        task,                              // the LANE is part of the content
        layers, matrix, methods, product, design, claim);
    byte[] d = java.security.MessageDigest.getInstance("SHA-256")
        .digest(material.getBytes("UTF-8"));
    StringBuilder hex = new StringBuilder();
    for (byte b : d) hex.append(String.format("%02x", b));
    return "geo-desk:" + task + ":" + hex.substring(0, 10) + ":a" + attempt;
}

require "digest"

def idem_key(body, attempt = 1)
  material = [
    body[:task],                           # the LANE is part of the content
    body[:layers], body[:matrix], body[:methods].to_s,
    body[:product].to_s, body[:design].to_s, body[:claim].to_s
  ].join("\x1f")
  digest = Digest::SHA256.hexdigest(material)[0, 10]
  "geo-desk:#{body[:task]}:#{digest}:a#{attempt}"
end

key = idem_key(align)                      # geo-desk:align:9f31c7a4e0:a1
call("/run", align, "POST", { "Idempotency-Key" => key })

<?php
function idem_key(array $body, int $attempt = 1): string {
    $material = implode("\x1f", [
        $body["task"],                     // the LANE is part of the content
        $body["layers"], $body["matrix"], $body["methods"] ?? "",
        $body["product"] ?? "", $body["design"] ?? "", $body["claim"] ?? "",
    ]);
    $digest = substr(hash("sha256", $material), 0, 10);
    return "geo-desk:" . $body["task"] . ":" . $digest . ":a" . $attempt;
}

$key = idem_key($align);                   // geo-desk:align:9f31c7a4e0:a1
call("/run", $align, "POST", ["Idempotency-Key: " . $key]);

static string IdemKey(string task, string layers, string matrix, string methods,
                      string product, string design, string claim, int attempt = 1)
{
    var material = string.Join("\u001f",
        task,                              // the LANE is part of the content
        layers, matrix, methods, product, design, claim);
    var bytes = System.Security.Cryptography.SHA256.HashData(
        Encoding.UTF8.GetBytes(material));
    var hex = Convert.ToHexString(bytes).ToLowerInvariant()[..10];
    return $"geo-desk:{task}:{hex}:a{attempt}";
}

var key = IdemKey("align", Layers, Matrix, Methods, "categorical", "", claim);
var started = await GeoDesk.Call("/run", align, "POST", key);