Vol Desk — API

# Every call is one request to the same host. Keep the token in a shell
# variable; never commit it. Get one from /tokens.html, or step 2.
API=https://api.skillsafe.ai/v1/app-api
SKILLSAFE_TOKEN="YOUR_TOKEN"

call() {           # call <path> [json-body]
  if [ -n "$2" ]; then
    curl -sS -X POST "$API$1" \
      -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
      -H "Content-Type: application/json" \
      -d "$2"
  else
    curl -sS "$API$1" -H "Authorization: Bearer $SKILLSAFE_TOKEN"
  fi
}

import json, urllib.request

API = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"          # or read it from your own secret store

def call(path, body=None, method=None, token=TOKEN, headers=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(API + path, data=data,
                                 method=method or ("POST" if data else "GET"))
    if token:
        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:
        payload = json.load(r)
    if "error" in payload:
        raise RuntimeError(payload["error"]["code"] + ": " + payload["error"]["message"])
    return payload["data"]

const API = "https://api.skillsafe.ai/v1/app-api";
let TOKEN = "YOUR_TOKEN";     // or read it from your own secret store

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

package main

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

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

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, hdr 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"
		}
	}
	if method == "" {
		method = "GET"
	}
	req, _ := http.NewRequest(method, api+path, rdr)
	req.Header.Set("Authorization", "Bearer "+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 e envelope
	if err := json.NewDecoder(res.Body).Decode(&e); err != nil {
		return nil, err
	}
	if e.Error != nil {
		return nil, errors.New(e.Error.Code + ": " + e.Error.Message)
	}
	return e.Data, nil
}

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

public class VolDesk {
  static final String API = "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) throws Exception {
    HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(API + path))
        .header("Authorization", "Bearer " + token);
    if (jsonBody == null) {
      b.GET();
    } else {
      b.header("Content-Type", "application/json")
       .POST(HttpRequest.BodyPublishers.ofString(jsonBody));
    }
    HttpResponse<String> r = HTTP.send(b.build(), HttpResponse.BodyHandlers.ofString());
    if (r.body().contains("\"error\"")) throw new RuntimeException(r.body());
    return r.body();   // parse with your JSON library of choice
  }
}

require "json"
require "net/http"

API = URI("https://api.skillsafe.ai/v1/app-api")
TOKEN = ENV["SKILLSAFE_TOKEN"]

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

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

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

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

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

  public static async Task<JsonElement> Call(string path, object? body = null,
      HttpMethod? method = null, (string, string)[]? extra = null) {
    var req = new HttpRequestMessage(method ?? (body is null ? HttpMethod.Get : HttpMethod.Post), Api + path);
    req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
    foreach (var (k, v) in extra ?? Array.Empty<(string, string)>()) req.Headers.Add(k, v);
    if (body is not null)
      req.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
    var res = await Http.SendAsync(req);
    using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
    var root = doc.RootElement.Clone();
    if (root.TryGetProperty("error", out var err))
      throw new Exception(err.GetProperty("code").GetString());
    return root.GetProperty("data").Clone();
  }
}

# A guest token. The slug goes in the BODY - an X-App-Slug header 400s.
curl -sS -X POST "$API/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"vol-desk"}'
# -> {"data":{"token":"sk_app_...","subject_type":"guest",...}}
#
# For a personal token, open https://vol-desk.skillsafe.ai/tokens.html
# and copy it there. Do not open the browser console for this, ever.

# Guest token: no Authorization header on this one call.
tok = call("/guest", {"slug": "vol-desk"}, token="")["token"]
print(tok[:8] + "...")
# A personal token comes from https://vol-desk.skillsafe.ai/tokens.html
# Never read it out of the browser console.

const guest = await (await fetch(API + "/guest", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ slug: "vol-desk" }),
})).json();
TOKEN = guest.data.token;
// A personal token comes from https://vol-desk.skillsafe.ai/tokens.html
// Never read it out of the browser console.

raw, err := call("/guest", map[string]string{"slug": "vol-desk"}, "POST", nil)
if err != nil {
	panic(err)
}
var g struct {
	Token string `json:"token"`
}
json.Unmarshal(raw, &g)
token = g.Token
// Personal tokens: https://vol-desk.skillsafe.ai/tokens.html - not the console.

String guest = call("/guest", "{\"slug\":\"vol-desk\"}");
// pull data.token out of the envelope and assign it to `token`
// Personal tokens: https://vol-desk.skillsafe.ai/tokens.html - not the console.

token = call("/guest", { "slug" => "vol-desk" })["token"]
# Personal tokens: https://vol-desk.skillsafe.ai/tokens.html - not the console.

$guest = call("/guest", ["slug" => "vol-desk"]);
$TOKEN = $guest["token"];
// Personal tokens: https://vol-desk.skillsafe.ai/tokens.html - not the console.

var guest = await VolDesk.Call("/guest", new { slug = "vol-desk" });
// guest.GetProperty("token").GetString()
// Personal tokens: https://vol-desk.skillsafe.ai/tokens.html - not the console.

curl -sS "$API/me" -H "Authorization: Bearer $SKILLSAFE_TOKEN"
# -> {"data":{"subject_type":"user","subject_id":"...","credits":1240}}

me = call("/me")
print(me["subject_type"], me["credits"])

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

raw, _ := call("/me", nil, "GET", nil)
var me struct {
	SubjectType string `json:"subject_type"`
	Credits     int    `json:"credits"`
}
json.Unmarshal(raw, &me)

String me = call("/me", null);
// read data.subject_type and data.credits

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

$me = call("/me");
echo $me["subject_type"], " ", $me["credits"], "\n";

var me = await VolDesk.Call("/me");
Console.WriteLine(me.GetProperty("credits").GetInt32());

call /estimate "$(cat input.json)"
# -> {"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra",
#     "markup_bps":1000,"hold_credits":...,"min_credits":...}}
# Free: no job is created and nothing is charged.

# Assert the pricing facts before spending anything:
call /estimate "$(cat input.json)" \
  | grep -q '"model":"gpt-5.6-terra"' || echo "the model has moved - stop"

est = call("/estimate", run_input)
assert est["model"] == "gpt-5.6-terra", est["model"]
assert est["model_alias"] == "gpt-terra", est["model_alias"]
assert est["markup_bps"] == 1000, est["markup_bps"]
print(est["hold_credits"], est["min_credits"])
if me["credits"] < est["min_credits"]:
    raise SystemExit("top up first - a 402 after submit is a preflight you skipped")

const est = await call("/estimate", runInput);
if (est.model !== "gpt-5.6-terra") throw new Error("unexpected model " + est.model);
if (est.model_alias !== "gpt-terra") throw new Error("unexpected alias " + est.model_alias);
if (est.markup_bps !== 1000) throw new Error("unexpected markup " + est.markup_bps);
if (me.credits < est.min_credits) throw new Error("balance below min_credits");
console.log("reserves", est.hold_credits, "credits");

raw, _ = call("/estimate", runInput, "POST", nil)
var est struct {
	Model       string `json:"model"`
	ModelAlias  string `json:"model_alias"`
	MarkupBps   int    `json:"markup_bps"`
	HoldCredits int    `json:"hold_credits"`
	MinCredits  int    `json:"min_credits"`
}
json.Unmarshal(raw, &est)
if est.Model != "gpt-5.6-terra" || est.ModelAlias != "gpt-terra" || est.MarkupBps != 1000 {
	panic("the pricing facts have moved: " + est.Model + "/" + est.ModelAlias)
}

String est = call("/estimate", inputJson);
// assert data.model is "gpt-5.6-terra", data.model_alias is "gpt-terra"
// and data.markup_bps is 1000 before you submit anything;
// then compare data.min_credits against the balance from /me.
// data.hold_credits is the worst-case reservation, not the charge.
if (!est.contains("\"gpt-5.6-terra\"")) throw new IllegalStateException("the model has moved");

est = call("/estimate", run_input)
abort "the model has moved: #{est['model']}"       unless est["model"] == "gpt-5.6-terra"
abort "the alias has moved: #{est['model_alias']}" unless est["model_alias"] == "gpt-terra"
abort "the markup has moved: #{est['markup_bps']}" unless est["markup_bps"] == 1000
abort "top up first" if me["credits"] < est["min_credits"]
puts "holds #{est['hold_credits']}"

$est = call("/estimate", $runInput);
if ($est["model"] !== "gpt-5.6-terra") { throw new Exception("the model has moved"); }
if ($est["model_alias"] !== "gpt-terra") { throw new Exception("the alias has moved"); }
if ($est["markup_bps"] !== 1000) { throw new Exception("the markup has moved"); }
if ($me["credits"] < $est["min_credits"]) { throw new Exception("top up first"); }
echo "holds ", $est["hold_credits"], "\n";

var est = await VolDesk.Call("/estimate", runInput);
if (est.GetProperty("model").GetString() != "gpt-5.6-terra")
  throw new Exception("the model has moved");
if (est.GetProperty("model_alias").GetString() != "gpt-terra")
  throw new Exception("the alias has moved");
if (est.GetProperty("markup_bps").GetInt32() != 1000)
  throw new Exception("the markup has moved");
var hold = est.GetProperty("hold_credits").GetInt32();
var min  = est.GetProperty("min_credits").GetInt32();

# Idempotency-Key is a content hash of the input plus one nonce per
# gesture. Reuse it for a retry and the platform replays the job it
# already has instead of billing a second one.
KEY="$(shasum -a 256 input.json | cut -c1-32)-1"
curl -sS -X POST "$API/run" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d @input.json

# The reply is a job. Poll until it is terminal, no tighter than 1s.
curl -sS "$API/jobs/JOB_ID" -H "Authorization: Bearer $SKILLSAFE_TOKEN"
# -> {"data":{"job_id":"...","status":"succeeded","output_text":"{...}"}}

import hashlib, json, time

key = hashlib.sha256(json.dumps(run_input, sort_keys=True).encode()).hexdigest()[:32] + "-1"
job = call("/run", run_input, headers={"Idempotency-Key": key})
while job["status"] not in ("succeeded", "failed"):
    time.sleep(1.0)
    job = call("/jobs/" + job["job_id"], method="GET")
if job["status"] == "failed":
    raise SystemExit(job.get("error") or "the run failed")
result = json.loads(job["output_text"])
print(result["headline"])

const key = "run-" + Date.now().toString(36) + "-1";   // one nonce per gesture
let job = await call("/run", runInput, "POST", { "Idempotency-Key": key });
while (job.status !== "succeeded" && job.status !== "failed") {
  await new Promise((r) => setTimeout(r, 1000));
  job = await call("/jobs/" + job.job_id);
}
if (job.status === "failed") throw new Error(job.error || "the run failed");
const result = JSON.parse(job.output_text);

key := fmt.Sprintf("%x-1", sha256.Sum256(bodyBytes))[:34]
raw, _ = call("/run", runInput, "POST", map[string]string{"Idempotency-Key": key})
var job struct {
	JobID      string `json:"job_id"`
	Status     string `json:"status"`
	OutputText string `json:"output_text"`
}
json.Unmarshal(raw, &job)
for job.Status != "succeeded" && job.Status != "failed" {
	time.Sleep(time.Second)
	raw, _ = call("/jobs/"+job.JobID, nil, "GET", nil)
	json.Unmarshal(raw, &job)
}
// job.OutputText is the desk note, as JSON text

// Add the header on the run request:
//   .header("Idempotency-Key", key)
String job = call("/run", inputJson);
// read data.job_id, then poll GET /jobs/{job_id} until status is
// "succeeded" or "failed"; the reply text is data.output_text,
// which parses into the desk-note object documented below

require "digest"

key = Digest::SHA256.hexdigest(JSON.generate(run_input))[0, 32] + "-1"
job = call("/run", run_input, "POST", { "Idempotency-Key" => key })
until %w[succeeded failed].include?(job["status"])
  sleep 1
  job = call("/jobs/#{job['job_id']}")
end
abort(job["error"] || "the run failed") if job["status"] == "failed"
result = JSON.parse(job["output_text"])

$key = substr(hash("sha256", json_encode($runInput)), 0, 32) . "-1";
$job = call("/run", $runInput, null, ["Idempotency-Key: {$key}"]);
while (!in_array($job["status"], ["succeeded", "failed"], true)) {
  sleep(1);
  $job = call("/jobs/" . $job["job_id"]);
}
$result = json_decode($job["output_text"], true);

var key = Convert.ToHexString(
    System.Security.Cryptography.SHA256.HashData(
        JsonSerializer.SerializeToUtf8Bytes(runInput)))[..32] + "-1";
var job = await VolDesk.Call("/run", runInput, null, new[] { ("Idempotency-Key", key) });
var jobId = job.GetProperty("job_id").GetString();
while (job.GetProperty("status").GetString() is not ("succeeded" or "failed")) {
  await Task.Delay(1000);
  job = await VolDesk.Call("/jobs/" + jobId);
}
var result = JsonDocument.Parse(job.GetProperty("output_text").GetString()!);

curl -N -sS -X POST "$API/run-stream" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d @input.json
# The frame NAME arrives on the "event:" line, the payload on "data:".
# event: delta   -> {"text":"..."}      append it
# event: done    -> the terminal job object
# event: error   -> {"code":"...","message":"..."}

import json, urllib.request

req = urllib.request.Request(API + "/run-stream",
                             data=json.dumps(run_input).encode(), method="POST")
req.add_header("Authorization", "Bearer " + TOKEN)
req.add_header("Content-Type", "application/json")
req.add_header("Idempotency-Key", key)

buf, event, job = "", None, None
with urllib.request.urlopen(req) as stream:
    for line in stream:
        line = line.decode().rstrip("\n")
        if line.startswith("event:"):
            event = line[6:].strip()          # the frame NAME lives here
        elif line.startswith("data:"):
            payload = json.loads(line[5:].strip())
            if event == "delta":
                buf += payload.get("text", "")
            elif event == "done":
                job = payload
            elif event == "error":
                raise RuntimeError(payload["code"] + ": " + payload["message"])
result = json.loads(job["output_text"] if job else buf)

const res = await fetch(API + "/run-stream", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + TOKEN,
    "Content-Type": "application/json",
    "Idempotency-Key": key,
  },
  body: JSON.stringify(runInput),
});
const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = "", pending = "", event = null;
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  pending += dec.decode(value, { stream: true });
  const lines = pending.split("\n");
  pending = 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") buf += payload.text || "";
      else if (event === "error") throw new Error(payload.code + ": " + payload.message);
    }
  }
}

req, _ := http.NewRequest("POST", api+"/run-stream", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", key)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

sc := bufio.NewScanner(res.Body)
var event, buf string
for sc.Scan() {
	line := sc.Text()
	switch {
	case strings.HasPrefix(line, "event:"):
		event = strings.TrimSpace(line[6:])   // the frame NAME
	case strings.HasPrefix(line, "data:") && event == "delta":
		var d struct {
			Text string `json:"text"`
		}
		json.Unmarshal([]byte(strings.TrimSpace(line[5:])), &d)
		buf += d.Text
	}
}

HttpRequest req = HttpRequest.newBuilder(URI.create(API + "/run-stream"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", key)
    .POST(HttpRequest.BodyPublishers.ofString(inputJson))
    .build();
HttpResponse<java.util.stream.Stream<String>> res =
    HTTP.send(req, HttpResponse.BodyHandlers.ofLines());
StringBuilder buf = 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]))
    buf.append(line.substring(5).trim());   // then pull .text with your JSON library
});

uri = URI("#{API}/run-stream")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = key
req.body = JSON.generate(run_input)

buf = +""
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:") then event = line[6..].strip
        elsif line.start_with?("data:") && event == "delta"
          buf << (JSON.parse(line[5..].strip)["text"] || "")
        end
      end
    end
  end
end

$buf = "";
$event = null;
$ch = curl_init(API . "/run-stream");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($runInput));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer {$TOKEN}",
  "Content-Type: application/json",
  "Idempotency-Key: {$key}",
]);
curl_setopt($ch, CURLOPT_WRITEFUNCTION, function ($ch, $chunk) use (&$buf, &$event) {
  foreach (explode("\n", $chunk) as $line) {
    if (str_starts_with($line, "event:")) { $event = trim(substr($line, 6)); }
    elseif (str_starts_with($line, "data:") && $event === "delta") {
      $d = json_decode(trim(substr($line, 5)), true);
      $buf .= $d["text"] ?? "";
    }
  }
  return strlen($chunk);
});
curl_exec($ch);

var req = new HttpRequestMessage(HttpMethod.Post, "https://api.skillsafe.ai/v1/app-api/run-stream");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
req.Headers.Add("Idempotency-Key", key);
req.Content = new StringContent(JsonSerializer.Serialize(runInput), Encoding.UTF8, "application/json");

using var res = await Http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead);
using var sr = new StreamReader(await res.Content.ReadAsStreamAsync());
var buf = new StringBuilder();
string? evt = null;
while (await sr.ReadLineAsync() is { } line) {
  if (line.StartsWith("event:")) evt = line[6..].Trim();     // the frame NAME
  else if (line.StartsWith("data:") && evt == "delta") {
    using var d = JsonDocument.Parse(line[5..].Trim());
    buf.Append(d.RootElement.GetProperty("text").GetString());
  }
}