Driving Gherkin Desk from your own code

# Every call below uses these two. The token comes from step 2.
BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="YOUR_TOKEN"

import json, urllib.request

BASE = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"

def call(method, path, body=None):
    data = json.dumps(body).encode() if 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")
    with urllib.request.urlopen(req) as r:
        payload = json.loads(r.read())
    if not payload.get("ok"):
        raise RuntimeError(payload["error"]["code"] + ": " + payload["error"]["message"])
    return payload["data"]

const BASE = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN";

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

package main

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

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

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

func call(method, path string, body any) (json.RawMessage, 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 "+token)
    if body != nil {
        req.Header.Set("Content-Type", "application/json")
    }
    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.OK {
        return nil, errors.New(env.Error.Code + ": " + env.Error.Message)
    }
    return env.Data, nil
}

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

public class GherkinDesk {
    static final String BASE = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN";
    static final HttpClient CLIENT = HttpClient.newHttpClient();

    static String call(String method, String path, String jsonBody) throws Exception {
        HttpRequest.Builder b = HttpRequest.newBuilder()
            .uri(URI.create(BASE + path))
            .header("Authorization", "Bearer " + TOKEN);
        if (jsonBody == null) {
            b.method(method, HttpRequest.BodyPublishers.noBody());
        } else {
            b.header("Content-Type", "application/json")
             .method(method, HttpRequest.BodyPublishers.ofString(jsonBody));
        }
        HttpResponse<String> res = CLIENT.send(b.build(), HttpResponse.BodyHandlers.ofString());
        return res.body(); // parse with your JSON library; check "ok" before "data"
    }
}

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

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"

def call(method, path, body = nil)
  uri = URI(BASE + path)
  klass = method == "GET" ? Net::HTTP::Get : Net::HTTP::Post
  req = klass.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  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) }
  payload = JSON.parse(res.body)
  raise "#{payload["error"]["code"]}: #{payload["error"]["message"]}" unless payload["ok"]
  payload["data"]
end

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

function call(string $method, string $path, ?array $body = null): array {
    $headers = ["Authorization: Bearer " . TOKEN];
    $opts = ["http" => ["method" => $method, "ignore_errors" => true]];
    if ($body !== null) {
        $headers[] = "Content-Type: application/json";
        $opts["http"]["content"] = json_encode($body);
    }
    $opts["http"]["header"] = implode("\r\n", $headers);
    $raw = file_get_contents(BASE . $path, false, stream_context_create($opts));
    $payload = json_decode($raw, true);
    if (empty($payload["ok"])) {
        throw new RuntimeException($payload["error"]["code"] . ": " . $payload["error"]["message"]);
    }
    return $payload["data"];
}

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

static class GherkinDesk {
    const string Base  = "https://api.skillsafe.ai/v1/app-api";
    const string Token = "YOUR_TOKEN";
    static readonly HttpClient Client = new HttpClient();

    public static async Task<JsonElement> Call(HttpMethod method, string path, object? body = null) {
        var req = new HttpRequestMessage(method, Base + path);
        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
        if (body != null) {
            req.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
        }
        var res = await Client.SendAsync(req);
        using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
        var root = doc.RootElement;
        if (!root.GetProperty("ok").GetBoolean()) {
            var err = root.GetProperty("error");
            throw new Exception(err.GetProperty("code").GetString() + ": " + err.GetProperty("message").GetString());
        }
        return root.GetProperty("data").Clone();
    }
}

curl -s -X POST "$BASE/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"gherkin-desk"}'
# -> {"ok":true,"data":{"token":"aut_...","guest_id":"gst_..."}}

import json, urllib.request

req = urllib.request.Request(
    "https://api.skillsafe.ai/v1/app-api/guest",
    data=json.dumps({"slug": "gherkin-desk"}).encode(),
    headers={"Content-Type": "application/json"},
    method="POST")
with urllib.request.urlopen(req) as r:
    TOKEN = json.loads(r.read())["data"]["token"]

const res = await fetch("https://api.skillsafe.ai/v1/app-api/guest", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ slug: "gherkin-desk" })
});
const TOKEN = (await res.json()).data.token;

b, _ := json.Marshal(map[string]string{"slug": "gherkin-desk"})
res, _ := http.Post(base+"/guest", "application/json", bytes.NewReader(b))
defer res.Body.Close()
// decode into envelope, then env.Data -> {"token": "...", "guest_id": "..."}

String body = "{\"slug\":\"gherkin-desk\"}";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(BASE + "/guest"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
String json = CLIENT.send(req, HttpResponse.BodyHandlers.ofString()).body();
// json.data.token is your guest token

uri = URI("https://api.skillsafe.ai/v1/app-api/guest")
res = Net::HTTP.post(uri, JSON.generate({ "slug" => "gherkin-desk" }),
                     "Content-Type" => "application/json")
TOKEN = JSON.parse(res.body)["data"]["token"]

<?php
$opts = ["http" => [
    "method"  => "POST",
    "header"  => "Content-Type: application/json",
    "content" => json_encode(["slug" => "gherkin-desk"]),
]];
$raw = file_get_contents("https://api.skillsafe.ai/v1/app-api/guest", false,
                         stream_context_create($opts));
$token = json_decode($raw, true)["data"]["token"];

var content = new StringContent("{\"slug\":\"gherkin-desk\"}", Encoding.UTF8, "application/json");
var res = await Client.PostAsync("https://api.skillsafe.ai/v1/app-api/guest", content);
using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
var token = doc.RootElement.GetProperty("data").GetProperty("token").GetString();

curl -s "$BASE/me" -H "Authorization: Bearer $TOKEN"
# -> {"ok":true,"data":{"subject_type":"user","credits":48210,...}}

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

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

data, err := call("GET", "/me", nil)
if err != nil {
    panic(err)
}
fmt.Println(string(data))

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

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

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

var me = await Call(HttpMethod.Get, "/me");
Console.WriteLine(me.GetProperty("subject_type").GetString());

curl -s -X POST "$BASE/estimate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d @input.json
# -> {"ok":true,"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra",
#      "markup_bps":1000,"hold_credits":4120,"min_credits":260,"sponsor_enabled":false}}

INPUT = json.load(open("input.json"))
est = call("POST", "/estimate", INPUT)
print(est["model_alias"], est["hold_credits"], est["min_credits"])
# estimate is FREE and creates no job. Estimate the lane you are about to run:
# hold_credits differs per task because the prompts and output caps differ.

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

data, err := call("POST", "/estimate", input)
if err != nil {
    panic(err)
}
fmt.Println(string(data))

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

est = call("POST", "/estimate", input)
puts "#{est["model_alias"]} #{est["hold_credits"]}"

<?php
$est = call("POST", "/estimate", $input);
echo $est["hold_credits"], "\n";

var est = await Call(HttpMethod.Post, "/estimate", input);
Console.WriteLine(est.GetProperty("hold_credits").GetInt32());

# 1. submit
JOB=$(curl -s -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: gherkin-desk:audit:$(shasum -a 256 input.json | cut -c1-16):a1" \
  -d @input.json | python3 -c 'import json,sys;print(json.load(sys.stdin)["data"]["job_id"])')

# 2. poll to terminal
until curl -s "$BASE/jobs/$JOB" -H "Authorization: Bearer $TOKEN" \
  | tee /dev/stderr | grep -q '"status":"succeeded"'; do sleep 2; done

import hashlib, time

key = "gherkin-desk:audit:" + hashlib.sha256(
    json.dumps(INPUT, sort_keys=True).encode()).hexdigest()[:16] + ":a1"

req = urllib.request.Request(BASE + "/run",
                             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", key)
with urllib.request.urlopen(req) as r:
    job_id = json.loads(r.read())["data"]["job_id"]

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

result = json.loads(job["output"]["output"])   # the envelope described below
print(result["verdict"], len(result["findings"]))

const key = `gherkin-desk:audit:${hash(JSON.stringify(INPUT))}:a1`;
const res = await fetch(`${BASE}/run`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": key
  },
  body: JSON.stringify(INPUT)
});
const { job_id } = (await res.json()).data;

let job;
do {
  await new Promise(r => setTimeout(r, 2000));
  job = await call("GET", `/jobs/${job_id}`);
} while (!["succeeded", "failed", "cancelled"].includes(job.status));

const result = JSON.parse(job.output.output);
console.log(result.verdict, result.findings.length);

b, _ := json.Marshal(input)
req, _ := http.NewRequest("POST", base+"/run", bytes.NewReader(b))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "gherkin-desk:audit:"+hash(b)+":a1")
// submit, read data.job_id, then GET /jobs/{id} until status is terminal

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(BASE + "/run"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", "gherkin-desk:audit:" + hash(inputJson) + ":a1")
    .POST(HttpRequest.BodyPublishers.ofString(inputJson))
    .build();
String submitted = CLIENT.send(req, HttpResponse.BodyHandlers.ofString()).body();
// read data.job_id, then poll GET /jobs/{id}

uri = URI(BASE + "/run")
req = Net::HTTP::Post.new(uri)
req["Authorization"]   = "Bearer #{TOKEN}"
req["Content-Type"]    = "application/json"
req["Idempotency-Key"] = "gherkin-desk:audit:#{hash(input)}:a1"
req.body = JSON.generate(input)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
job_id = JSON.parse(res.body)["data"]["job_id"]

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

<?php
$opts = ["http" => [
    "method"  => "POST",
    "header"  => implode("\r\n", [
        "Authorization: Bearer " . TOKEN,
        "Content-Type: application/json",
        "Idempotency-Key: gherkin-desk:audit:" . substr(hash("sha256", json_encode($input)), 0, 16) . ":a1",
    ]),
    "content" => json_encode($input),
]];
$raw = file_get_contents(BASE . "/run", false, stream_context_create($opts));
$jobId = json_decode($raw, true)["data"]["job_id"];
// then poll GET /jobs/{id} until status is terminal

var req = new HttpRequestMessage(HttpMethod.Post, Base + "/run");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
req.Headers.Add("Idempotency-Key", $"gherkin-desk:audit:{Hash(input)}:a1");
req.Content = new StringContent(JsonSerializer.Serialize(input), Encoding.UTF8, "application/json");
var res = await Client.SendAsync(req);
// read data.job_id, then poll GET /jobs/{id}

curl -N -s -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: gherkin-desk:audit:abc123:a1" \
  -d @input.json
# event: delta   data: {"text":"{\"task\":\"audit\","}
# event: job     data: {"job_id":"job_..."}
# event: result  data: {"output":{"output":"..."},"charged_credits":2840}

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", key)

buf, event = "", None
with urllib.request.urlopen(req) as r:
    for raw in r:
        line = raw.decode().rstrip("\n")
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            payload = json.loads(line[5:].strip())
            if event == "delta":
                buf += payload["text"]
            elif event == "result":
                buf = payload["output"]["output"]
result = json.loads(buf)

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

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "", text = "", event = null;
for (;;) {
  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") text += payload.text;
      if (event === "result") text = payload.output.output;
    }
  }
}
const result = JSON.parse(text);

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

sc := bufio.NewScanner(res.Body)
for sc.Scan() {
    line := sc.Text()
    // "event: delta" then "data: {...}" - accumulate payload.text
    _ = line
}

HttpResponse<java.util.stream.Stream<String>> res =
    CLIENT.send(streamRequest, HttpResponse.BodyHandlers.ofLines());
StringBuilder text = new StringBuilder();
res.body().forEach(line -> {
    // "event: delta" then "data: {...}" - append the "text" field
});

Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(stream_req) do |res|
    res.read_body do |chunk|
      # split on newlines, read "event:" then "data:" lines
    end
  end
end

<?php
$stream = fopen(BASE . "/run-stream", "r", false, stream_context_create($opts));
while (($line = fgets($stream)) !== false) {
    // "event: delta" then "data: {...}"
}
fclose($stream);

using var stream = await Client.SendAsync(streamReq, HttpCompletionOption.ResponseHeadersRead);
using var reader = new StreamReader(await stream.Content.ReadAsStreamAsync());
string? line;
while ((line = await reader.ReadLineAsync()) != null) {
    // "event: delta" then "data: {...}"
}