Carrier Desk API

Everything the web app does, you can do from your own code: paste a carrier decision — a scorecard dump, an RFP bid table, a rate or fuel-surcharge proposal, an onboarding candidate, a compliance alert, a capacity-crunch email thread — and get it worked. The scenario named, the risk called, the single next move argued from the numbers on the page, and the traps flagged. Useful for sweeping a routing guide overnight, screening a bid round before the analyst sees it, or refusing to renew anything that comes back “Exit the carrier”. Base URL https://api.skillsafe.ai/v1/app-api.

Input fields

The object you send — and it is the input object directly, not wrapped in {"input": ...}. Only situation is required.

Field	Type	Meaning
`situation`	string	Required. The carrier record as pasted: scorecard tables, lane and volume lists, contracted rates and fuel-surcharge schedules, RFP bids, carrier or broker emails, FMCSA and insurance snapshots, claims notes, ops observations. Clipped at 40,000 characters — from the middle, keeping both ends, because a carrier worksheet carries its identifying header at the top and its live pressure (the proposal, the ops notes, the deadline) at the bottom. The cut is announced in-band with a bracketed marker saying how many characters were removed, and the model is instructed not to read across the gap.
`context`	string	Optional, clipped at 6,000 characters, also from the middle. Who is deciding, the portfolio and lanes at stake, service constraints, budget pressure, what decision is needed and what is off the table. It materially changes the answer: the same scorecard reads differently when lane A cannot lose service during peak.
`facts`	string	Optional. The deterministic output of the app's browser-side calculator. Treated as a hint, not a fact — every figure is reconciled against `situation` before it is repeated, and where the two disagree the pasted material wins. May carry: the four scorecard metrics banded against the desk's targets and red flags with a weighted composite (and, when a whole column of periods was pasted rather than a single figure, the trend direction and a count of consecutive periods at or past the exit level); a fuel-surcharge total-cost model at $3.50, $4.00 and $4.50 diesel plus the user's own posted DOE price; a comparison of the current schedule against a proposed one across that range, with the diesel price at which the two cross and the annualized difference over weekly miles; contract-versus-benchmark and contract-versus-spot deltas; and a lane-concentration share against the 40% and 50% caps.
`previous`	object	Optional, present only on a re-run of the same carrier. Carries `scenario`, `risk`, `action`, `confidence` and `when` (a `YYYY-MM-DD` date) from the last assessment. The new material is assessed on its own merits; the reply names what changed and the evidence that moved it, and will not credit a change it cannot see on the page.
`retry_note`	string	Optional, and not for humans. Tells the model its previous reply did not parse and to re-emit the same assessment in the required shape. It is a formatting instruction only: it can never change the scenario, the risk, the action or any number.

1. Get a token

Every call carries Authorization: Bearer <token>. Open the token page to sign in, reveal your token and copy a ready-made shell export. It never asks you to open the DevTools console. If you would rather script it, POST /guest mints a guest token for a named slug — that is where the app slug is bound, which is why no later path contains an /apps/{slug}/ segment. A guest token works for reading and estimating; a signed-in token is needed to run.

POST/guest

# Every call below reuses this. Get the token from the token page
# linked above - never paste it into a shared shell history.
export SKILLSAFE_TOKEN="YOUR_TOKEN"
export SKILLSAFE_BASE="https://api.skillsafe.ai/v1/app-api"

# Or mint a guest token in one unauthenticated call. The app slug is bound
# to the token here, which is why no later path carries an /apps/{slug}/ segment.
curl -s -X POST "$SKILLSAFE_BASE/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug": "carrier-desk"}'
# -> {"ok":true,"data":{"token":"...","expires_at":"..."}}

import json, os, urllib.request

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

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

# Guest token, if you do not have one yet - the slug is bound to the token:
# TOKEN = call("POST", "/guest", {"slug": "carrier-desk"})["token"]

const BASE = "https://api.skillsafe.ai/v1/app-api";
// Read it from your own secret store; never hard-code a real token.
const TOKEN = "YOUR_TOKEN";

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

// Guest token, if you do not have one yet - the slug is bound to the token:
// const { token } = await call("POST", "/guest", { slug: "carrier-desk" });

package main

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

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

func call(method, path string, body any, hdr map[string]string) (map[string]any, error) {
  var rdr io.Reader
  if body != nil {
    b, _ := json.Marshal(body)
    rdr = bytes.NewReader(b)
  }
  req, _ := http.NewRequest(method, base+path, rdr)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("SKILLSAFE_TOKEN"))
  if body != nil { req.Header.Set("Content-Type", "application/json") }
  for k, v := range hdr { req.Header.Set(k, v) }
  res, err := http.DefaultClient.Do(req)
  if err != nil { return nil, err }
  defer res.Body.Close()
  var env struct {
    OK    bool           `json:"ok"`
    Data  map[string]any `json:"data"`
    Error struct{ Code, Message string } `json:"error"`
  }
  if err := json.NewDecoder(res.Body).Decode(&env); err != nil { return nil, err }
  if !env.OK { return nil, fmt.Errorf("%s: %s", env.Error.Code, env.Error.Message) }
  return env.Data, nil
}

// Guest token, if you do not have one yet - the slug is bound to the token:
// call("POST", "/guest", map[string]any{"slug": "carrier-desk"}, nil)

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

class CarrierDesk {
  static final String BASE = "https://api.skillsafe.ai/v1/app-api";
  static final String TOKEN = System.getenv().getOrDefault("SKILLSAFE_TOKEN", "YOUR_TOKEN");
  static final HttpClient HTTP = HttpClient.newHttpClient();

  static String call(String method, String path, String body, String idemKey) throws Exception {
    var b = HttpRequest.newBuilder(URI.create(BASE + path))
        .header("Authorization", "Bearer " + TOKEN);
    if (idemKey != null) b.header("Idempotency-Key", idemKey);
    if (body != null) {
      b.header("Content-Type", "application/json");
      b.method(method, HttpRequest.BodyPublishers.ofString(body));
    } else {
      b.method(method, HttpRequest.BodyPublishers.noBody());
    }
    var res = HTTP.send(b.build(), HttpResponse.BodyHandlers.ofString());
    return res.body();  // {"ok":true,"data":{...}} - decode with your JSON library
  }
}

// Guest token, if you do not have one yet - the slug is bound to the token:
// call("POST", "/guest", "{\"slug\": \"carrier-desk\"}", null);

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

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

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

# Guest token, if you do not have one yet - the slug is bound to the token:
# TOKEN = call("POST", "/guest", { "slug" => "carrier-desk" })["token"]

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

function call($method, $path, $body = null, $extra = []) {
  global $TOKEN;
  $headers = array_merge(["Authorization: Bearer $TOKEN"], $extra);
  if ($body !== null) $headers[] = "Content-Type: application/json";
  $ch = curl_init(BASE . $path);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => $method,
    CURLOPT_HTTPHEADER     => $headers,
    CURLOPT_POSTFIELDS     => $body === null ? null : json_encode($body),
  ]);
  $env = json_decode(curl_exec($ch), true);
  curl_close($ch);
  if (empty($env["ok"])) throw new Exception($env["error"]["code"]);
  return $env["data"];
}

// Guest token, if you do not have one yet - the slug is bound to the token:
// $TOKEN = call("POST", "/guest", ["slug" => "carrier-desk"])["token"];

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

const string Base = "https://api.skillsafe.ai/v1/app-api";
var token = Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN") ?? "YOUR_TOKEN";
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

async Task<string> Call(string method, string path, string? body, string? idemKey = null) {
  var req = new HttpRequestMessage(new HttpMethod(method), Base + path);
  if (idemKey != null) req.Headers.Add("Idempotency-Key", idemKey);
  if (body != null)
    req.Content = new StringContent(body, Encoding.UTF8, "application/json");
  var res = await http.SendAsync(req);
  return await res.Content.ReadAsStringAsync();  // {"ok":true,"data":{...}}
}

// Guest token, if you do not have one yet - the slug is bound to the token:
// await Call("POST", "/guest", "{\"slug\": \"carrier-desk\"}");

2. Check the session and balance

Confirms who the token belongs to and how many credits are available. Do this before a run: a 402 after submitting is avoidable.

GET/me

curl -s -X GET "https://api.skillsafe.ai/v1/app-api/me" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN"

me = call("GET", "/me")
print(me)

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

me, err := call("GET", "/me", nil, nil)
if err != nil { log.Fatal(err) }
fmt.Println(me)

String me = call("GET", "/me", null, null);
System.out.println(me);

me = call("GET", "/me")
puts me

$me = call("GET", "/me");
print_r($me);

var me = await Call("GET", "/me", null);
Console.WriteLine(me);

3. Estimate - free, no job created

Returns the credit hold a run would reserve, plus the resolved model and markup. It creates no job and charges nothing, so it is safe to call on every keystroke. The response carries model, model_alias, markup_bps, hold_credits, min_credits and sponsor_enabled.

POST/estimate

curl -s -X POST "https://api.skillsafe.ai/v1/app-api/estimate" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"situation": "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.", "context": "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.", "facts": "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation)."}'

# -> {"ok":true,"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra",
#      "markup_bps":1000,"hold_credits":...,"min_credits":...,"sponsor_enabled":false}}

INPUT = {
  "situation": "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  "context": "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  "facts": "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
}

est = call("POST", "/estimate", INPUT)
print(est["model"], est["model_alias"], est["markup_bps"], est["hold_credits"])

const INPUT = {
  situation: "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  context: "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  facts: "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
};

const est = await call("POST", "/estimate", INPUT);
console.log(est.model, est.model_alias, est.markup_bps, est.hold_credits);

input := map[string]any{
  "situation": "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  "context":   "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  "facts":     "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
}

est, err := call("POST", "/estimate", input, nil)
if err != nil { log.Fatal(err) }
fmt.Println(est["model"], est["hold_credits"])

String inputJson = "{"
  + "\"situation\": \"CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.\","
  + "\"context\": \"40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.\","
  + "\"facts\": \"Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).\""
  + "}";

String est = call("POST", "/estimate", inputJson, null);
System.out.println(est);

INPUT = {
  "situation" => "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  "context" => "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  "facts" => "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
}

est = call("POST", "/estimate", INPUT)
puts est["model"], est["hold_credits"]

$INPUT = [
  "situation" => "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  "context" => "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  "facts" => "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
];

$est = call("POST", "/estimate", $INPUT);
print_r($est);

var inputJson = "{"
  + "\"situation\": \"CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.\","
  + "\"context\": \"40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.\","
  + "\"facts\": \"Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).\""
  + "}";

var est = await Call("POST", "/estimate", inputJson);
Console.WriteLine(est);

What this app resolves to. Carrier Desk requests the gpt-terra alias, which resolves to gpt-5.6-terra at markup_bps 1000. Read model and hold_credits from the estimate rather than assuming either — the alias is the stable part, the resolved model is not.

4. Run and poll

Creates a job and returns {"job_id": "..."} immediately; poll GET /jobs/{job_id} until status is terminal, then read data.output.output. Always send an Idempotency-Key: a retried request with the same key returns the original job instead of billing twice.

POST/run

GET/jobs/{job_id}

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: carrier-desk-redhawk-001" \
  -d '{"situation": "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.", "context": "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.", "facts": "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation)."}'
# -> {"ok":true,"data":{"job_id":"job_..."}}

# Then poll until the job is terminal:
curl -s -X GET "https://api.skillsafe.ai/v1/app-api/jobs/job_..." \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN"

import time

INPUT = {
  "situation": "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  "context": "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  "facts": "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
}

job = call("POST", "/run", INPUT, {"Idempotency-Key": "carrier-desk-redhawk-001"})
job_id = job["job_id"]

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

const INPUT = {
  situation: "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  context: "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  facts: "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
};

const { job_id } = await call("POST", "/run", INPUT, {
  "Idempotency-Key": "carrier-desk-redhawk-001",
});

let j;
for (;;) {
  j = await call("GET", `/jobs/${job_id}`);
  if (["succeeded", "failed", "cancelled"].includes(j.status)) break;
  await new Promise((r) => setTimeout(r, 2000));
}
console.log(j.output.output);

input := map[string]any{
  "situation": "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  "context":   "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  "facts":     "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
}

job, err := call("POST", "/run", input, map[string]string{
  "Idempotency-Key": "carrier-desk-redhawk-001",
})
if err != nil { log.Fatal(err) }
jobID := job["job_id"].(string)

for {
  j, err := call("GET", "/jobs/"+jobID, nil, nil)
  if err != nil { log.Fatal(err) }
  status, _ := j["status"].(string)
  if status == "succeeded" || status == "failed" || status == "cancelled" {
    fmt.Println(j["output"])
    break
  }
  time.Sleep(2 * time.Second)
}

String inputJson = "{"
  + "\"situation\": \"CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.\","
  + "\"context\": \"40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.\","
  + "\"facts\": \"Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).\""
  + "}";

String job = call("POST", "/run", inputJson, "carrier-desk-redhawk-001");
String jobId = extractJobId(job);  // decode {"ok":true,"data":{"job_id":"..."}}

String j;
while (true) {
  j = call("GET", "/jobs/" + jobId, null, null);
  if (isTerminal(j)) break;   // status in succeeded | failed | cancelled
  Thread.sleep(2000);
}
System.out.println(j);

INPUT = {
  "situation" => "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  "context" => "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  "facts" => "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
}

job = call("POST", "/run", INPUT, { "Idempotency-Key" => "carrier-desk-redhawk-001" })
job_id = job["job_id"]

loop do
  j = call("GET", "/jobs/#{job_id}")
  if %w[succeeded failed cancelled].include?(j["status"])
    puts j["output"]["output"]
    break
  end
  sleep 2
end

$INPUT = [
  "situation" => "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.",
  "context" => "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.",
  "facts" => "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).",
];

$job = call("POST", "/run", $INPUT, ["Idempotency-Key: carrier-desk-redhawk-001"]);
$jobId = $job["job_id"];

while (true) {
  $j = call("GET", "/jobs/" . $jobId);
  if (in_array($j["status"], ["succeeded", "failed", "cancelled"], true)) {
    echo $j["output"]["output"];
    break;
  }
  sleep(2);
}

var inputJson = "{"
  + "\"situation\": \"CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.\","
  + "\"context\": \"40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.\","
  + "\"facts\": \"Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation).\""
  + "}";

var job = await Call("POST", "/run", inputJson, "carrier-desk-redhawk-001");
var jobId = ExtractJobId(job);  // decode {"ok":true,"data":{"job_id":"..."}}

string j;
while (true) {
  j = await Call("GET", $"/jobs/{jobId}", null);
  if (IsTerminal(j)) break;   // status in succeeded | failed | cancelled
  await Task.Delay(2000);
}
Console.WriteLine(j);

5. Run with streaming (SSE)

Same job, delivered as server-sent events. delta events carry incremental text, job carries the job id, and done carries the authoritative full output - trust done over the concatenated deltas, which can drop the tail. Send the same Idempotency-Key discipline here as on /run.

POST/run-stream

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: carrier-desk-redhawk-001" \
  -d '{"situation": "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619)\nLane A Chicago IL - Dallas TX, 8 of 10 weekly loads, 925 mi, contracted linehaul $1.98/mi\nCurrent FSC: DOE index, trigger $1.20, $0.01/mi per $0.05 above trigger. DOE posted $4.05.\nProposal 07/24: base drops to $1.94/mi, new FSC trigger $1.00 with $0.015/mi per $0.05.\nScorecard trailing 6: OTD 96.2, 95.6, 95.1, 94.4, 93.8, 93.7. Tender acceptance 93.1, 91.4, 88.7, 85.2, 81.0, 78.3. Invoice accuracy 96.0. Claims 0.4% of spend.\nOps: two drivers report settlements running 3-4 days late; COI reissued mid-term with a new underwriter; cargo coverage on file dropped $250k to $100k.\nFMCSA still shows authority ACTIVE, rating SATISFACTORY.", "context": "40-carrier portfolio, $14M annual freight spend. Redhawk is the largest dry van partner. I present to finance Thursday and must either counter, rebalance the routing guide, or start a replacement bid. Cannot lose service on lane A during Q4 peak. A 12% increase on core lanes will not clear budget.", "facts": "Scorecard banded: on-time delivery 93.7% (mid, declining over 6 periods); tender acceptance 78.3% (bad, declining over 6 periods); claims ratio 0.4% (good); invoice accuracy 96% (mid). Weighted composite 54/100 (bad).\nProposed schedule (base $1.94/mi, trigger $1.00, step $0.015/mi per $0.05) compared with the current one: $4.00 diesel: current $2.54/mi vs proposed $2.84/mi (+$0.30/mi). The two schedules cross at about $1.25 diesel: the proposal is cheaper below that and dearer above it. Annualized at $4.00 diesel on 13,085 miles a week over 52 weeks: +$204,126 a year.\nLane concentration computed: 8 of 10 weekly loads = 80% on one carrier (desk caps: 40% on a critical lane, 50% trips escalation)."}'

# event: delta   data: {"text":"SCENARIO: Rate negotiation..."}
# event: job     data: {"job_id":"job_..."}
# event: done    data: {"output":{"output":"SCENARIO: ..."},"charged_credits":1240}

import json, urllib.request

req = urllib.request.Request(BASE + "/run-stream",
    data=json.dumps(INPUT).encode(), method="POST")
req.add_header("Authorization", "Bearer " + TOKEN)
req.add_header("Content-Type", "application/json")
req.add_header("Idempotency-Key", "carrier-desk-redhawk-001")

raw = []
with urllib.request.urlopen(req) as r:
    event = None
    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())
            if event == "delta":
                raw.append(payload.get("text", ""))
            elif event == "done":
                raw = [payload["output"]["output"]]   # authoritative
print("".join(raw))

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

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

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop() ?? "";
  for (const line of lines) {
    if (line.startsWith("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 ?? "";
      if (event === "done") raw = payload.output.output;   // authoritative
    }
  }
}
console.log(raw);

// SSE: read the body line by line rather than decoding it as one JSON document.
inputJSON, _ := json.Marshal(input)
req, _ := http.NewRequest("POST", base+"/run-stream", bytes.NewReader(inputJSON))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SKILLSAFE_TOKEN"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "carrier-desk-redhawk-001")

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

sc := bufio.NewScanner(res.Body)
var event, raw string
for sc.Scan() {
  line := sc.Text()
  switch {
  case strings.HasPrefix(line, "event:"):
    event = strings.TrimSpace(line[6:])
  case strings.HasPrefix(line, "data:"):
    var p struct {
      Text   string `json:"text"`
      Output struct{ Output string `json:"output"` } `json:"output"`
    }
    json.Unmarshal([]byte(strings.TrimSpace(line[5:])), &p)
    if event == "delta" { raw += p.Text }
    if event == "done" { raw = p.Output.Output }   // authoritative
  }
}
fmt.Println(raw)

// Stream the response body and split on SSE line prefixes.
var req = HttpRequest.newBuilder(URI.create(BASE + "/run-stream"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", "carrier-desk-redhawk-001")
    .POST(HttpRequest.BodyPublishers.ofString(inputJson))
    .build();

var res = HTTP.send(req, HttpResponse.BodyHandlers.ofLines());
var raw = new StringBuilder();
final String[] event = { null };
res.body().forEach(line -> {
  if (line.startsWith("event:")) event[0] = line.substring(6).trim();
  else if (line.startsWith("data:") && "delta".equals(event[0])) {
    // decode {"text":"..."} with your JSON library and append
    raw.append(extractText(line.substring(5).trim()));
  }
  // on "done", replace raw with output.output - it is the authoritative copy
});
System.out.println(raw);

require "net/http"

uri = URI(BASE + "/run-stream")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = "carrier-desk-redhawk-001"
req.body = JSON.generate(INPUT)

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|
        if line.start_with?("event:")
          event = line[6..].strip
        elsif line.start_with?("data:")
          p = JSON.parse(line[5..].strip)
          raw << p["text"].to_s if event == "delta"
          raw = p["output"]["output"] if event == "done"   # authoritative
        end
      end
    end
  end
end
puts raw

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

var req = new HttpRequestMessage(HttpMethod.Post, Base + "/run-stream");
req.Headers.Add("Idempotency-Key", "carrier-desk-redhawk-001");
req.Content = new StringContent(inputJson, Encoding.UTF8, "application/json");

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

string? evt = null;
var raw = new StringBuilder();
while (!reader.EndOfStream) {
  var line = await reader.ReadLineAsync();
  if (line is null) continue;
  if (line.StartsWith("event:")) evt = line[6..].Trim();
  else if (line.StartsWith("data:") && evt == "delta") {
    // decode {"text":"..."} with System.Text.Json and append
    raw.Append(ExtractText(line[5..].Trim()));
  }
  // on "done", replace raw with output.output - it is the authoritative copy
}
Console.WriteLine(raw);

Output contract

data.output.output is plain text — no code fence around the response as a whole — in exactly this shape: five header lines, then six ## sections in this order. This is what the app's parser decodes; a reply that breaks any rule below is discarded and retried once.

SCENARIO: <Carrier onboarding | Scorecard review | RFP evaluation | Rate negotiation
           | Capacity crunch | Compliance alert | Financial distress | Insufficient information>
RISK: <Low | Moderate | High | Severe>
ACTION: <Award or expand volume | Onboard with trial | Renegotiate the rate
         | Rebalance the routing guide | Start corrective action | Sign with conditions
         | Exit the carrier | Investigate first | Insufficient information>
CONFIDENCE: <integer 0-100>
SUMMARY: <2 to 4 sentences>

## Next moves
- <move, argued from a number on the page>

## The numbers
- <figure, with where it came from>

## Scorecard read
- <metric: value, band, direction>

## Risk exposure
- <exposure and what it costs>

## Watch items
- <what to re-check, and when>

## Open questions
- <question>

Parsing rules, as implemented. SCENARIO: is the first line and must be exactly one of the eight values. RISK: is one of Low, Moderate, High, Severe. ACTION: is exactly one of the nine values. CONFIDENCE: is a bare integer 0-100, no percent sign. SUMMARY: is 2 to 4 sentences, may wrap, and ends at the first blank line. All six ## headings must appear, spelled exactly, in that order. Every line inside a section is a - bullet, which may wrap onto indented continuation lines. An empty section carries the single bullet - None.

The eight scenarios and the nine actions

SCENARIO is one of: Carrier onboarding, Scorecard review, RFP evaluation, Rate negotiation, Capacity crunch, Compliance alert, Financial distress, Insufficient information. ACTION is one of: Award or expand volume, Onboard with trial, Renegotiate the rate, Rebalance the routing guide, Start corrective action, Sign with conditions, Exit the carrier, Investigate first, Insufficient information. There is exactly one action — the single next move — not a menu.

Sections that may not be empty

Only Scorecard read and Open questions may legitimately come back as - None. Two rules are enforced on top of that: if RISK is High or Severe, Risk exposure can never be - None.; and if ACTION is Insufficient information, Open questions can never be - None. A reply that breaks the shape is discarded and the app retries once with the shape spelled out, reusing the same idempotency family so the retry cannot double-bill.

The constants the answer is argued against

The output is checkable because it is argued against fixed desk constants rather than sentiment. The four scorecard metrics carry a target and a red flag: on-time delivery targets 95% and red-flags at 90%; tender acceptance targets 90% and red-flags at 80%; the claims ratio, as a percent of spend, targets 0.5% and red-flags at 1.0%; invoice accuracy targets 97% and red-flags at 93%. The composite weights them on-time delivery 35, acceptance 25, claims 20 and invoice accuracy 20. The exit thresholds are duration-qualified, so a single bad period is never an exit: on-time delivery below 85% for 60 days, tender acceptance below 70% for 30 days with no communication, a claims ratio above 2% for 90 days, or invoice accuracy below 88% for 90 days after notice. Lane concentration is capped at 40% on a critical lane, with 50% the level that trips escalation. Where the reply cites one of these, you can check it yourself against the same pasted numbers.

Re-runs and reformat retries

previous and retry_note ride along in the same input object. They are the only two fields you would not send on a first pass:

{
  "situation": "CARRIER: Redhawk Transit Lines Inc (asset, MC-742619) ...",
  "previous": {
    "scenario": "Scorecard review",
    "risk": "High",
    "action": "Start corrective action",
    "confidence": 72,
    "when": "2026-06-18"
  },
  "retry_note": "Your previous reply did not parse. Re-emit the SAME assessment, unchanged in substance, in the required shape: five header lines then the six ## sections in order, every section line a '- ' bullet."
}

Grounding. The assessment only argues from what is on the page. A figure in facts that cannot be reconciled against situation is dropped rather than repeated, and a change since previous that has no evidence in the new material is not credited. Where the record does not support a call, the scenario and the action are both Insufficient information and the questions that would settle it go in Open questions.

The envelope and error codes

Every response is {"ok": true, "data": {...}} or {"ok": false, "error": {"code": "...", "message": "..."}}. Check ok before reading data.

Status	Code	What to do
400	`VALIDATION_ERROR`	The input shape is wrong. `error.details` names the field — most often a missing `situation`, or an input object wrapped in `{"input": ...}` when it should be sent directly.
401	`UNAUTHORIZED`	Missing, malformed or expired token. Mint a new one from the token page or `POST /guest`.
402	`PAYMENT_REQUIRED`	The balance is below the run's hold. Call `/estimate` first and compare against `/me`.
404	`NOT_FOUND`	Wrong slug or job id.
429	`RATE_LIMITED`	Back off and retry with the same idempotency key.
5xx	`INTERNAL`	Retry with the same idempotency key; a completed job is returned rather than re-billed.

Idempotency. Send Idempotency-Key on every /run and /run-stream. Derive it from a hash of the input plus an attempt counter, so a network retry collapses server-side while a genuine re-run of the same carrier gets its own key. The app does exactly this, including on its automatic reformat retry, which stays inside the same idempotency family.