Drive On a Field from your own code

The one metered task, grant, is available over HTTP. It takes what someone stands for (one to three lines), one to three everyday quirks, and optionally an everyday object and a favourite colour, and returns mock arms: a field tincture, an ordinary (the band), a charge and its count, a blazon, a short plain-English motto and, for each part, the line of the input it came from.

The division of labour first: the page decides the mechanics; the model does the choosing. The page works out the tincture named by the colour words (colour_tincture) and the number of charges (one per quirk, charge_count), and after the reply it re-checks the rule of tincture (metal on colour, colour on metal), writes the blazon itself for the same arms and confirms every quote is one of the input lines. Mock arms made for fun, not a grant from any heraldic authority.

Base URL and the envelope

Every endpoint lives under https://api.skillsafe.ai/v1/app-api, and every response uses one envelope:

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

The token is minted for this app (the guest call takes {"slug":"on-a-field"}), so no slug header is needed afterwards. Send it as Authorization: Bearer …. The run body is the input object, sent bare.

Status	Code	Meaning
400	validation_error	The body is not a JSON object, or a required field (`task`, `values`, `quirks`, `charge_count`) is missing.
401	unauthorized	No token, or a stale one. Mint a guest token or sign in again.
402	insufficient_credits	The balance is under `min_credits`. Price with `/estimate` first.
403	forbidden	A guest token tried to run: the grant is metered and needs a personal sign-in.
404	not_found	Unknown job id.
429	rate_limited	Back off and retry.
5xx	server_error	Transient. Retry with the same `Idempotency-Key` so a retry never double-bills.

The task field, the input and the rules

Every run sends task: grant (the one task is grant); a missing or different one is still answered as grant. All fields are strings.

Field	Required	What it holds
`task`	yes	Always `grant`.
`holder`	yes	Who the arms are for, up to 40 characters; `you` when empty.
`values`	yes	One to three numbered lines (`1. kindness`): what they stand for. Line 1 sets the field, line 2 the ordinary.
`quirks`	yes	One to three numbered lines: everyday quirks. One charge per quirk; line 1 picks the charge unless the object does.
`object`	yes	An everyday object, or `none`.
`colour`	yes	A favourite colour in their words, or `none`.
`colour_tincture`	yes	The tincture the colour words name (`gold` is `or`, `green` is `vert`...), or `none`. Build it with `ArmsKit.buildInput`.
`charge_count`	yes	The number of quirks, as a string.
`retry_note`	no	Only on a reformat retry: why the previous reply was unusable.

Vocabulary. Tinctures: metals or, argent; colours gules, azure, vert, purpure, sable. Ordinaries: none, fess, pale, bend, chevron, cross, saltire, chief. Charges: mullet, roundel, lozenge, crescent, heart, key, cup, book, tree, bell, anchor. One value line means no ordinary; the ordinary and the charges must each contrast with what they lie on (the rule of tincture).

The reply

One JSON object, no prose around it:

{"task": "grant", "headline": "...", "arms": {"field": "azure", "ordinary": "fess", "ordinary_tincture": "or", "charge": "bell", "charge_count": 2, "charge_tincture": "gules"}, "blazon": "Azure, on a fess Or two bells Gules", "reasons": [{"part": "field", "from": "...", "because": "..."}], "motto": "...", "motto_from": "..."}

Field	What it holds
`headline`	One sentence describing the arms in plain colour words.
`arms`	The six choices, ids from the vocabulary; `ordinary_tincture` is `none` when there is no ordinary.
`blazon`	The arms in heraldic shorthand, for example `Vert, two books in pale Or`.
`reasons[]`	Three entries - `field`, `ordinary`, `charge` - each with `from` (an exact input line) and `because`.
`motto` / `motto_from`	Two to six plain-English words built from one input line, and that line.

The page reads the reply with ReplyKit.normalize and checks it with ReplyKit.check, which lists, under "The page's check", a field that ignores the colour, an ordinary on a one-value shield, a charge count that is not one per quirk, a break of the rule of tincture, a blazon that differs from the page's own, a quote that is not one of the input lines, and motto words not drawn from its line.

Worked examples - every sample

These are the free samples on the page: the exact input the page sends and the reply that replays for free. Together they cover a plain field and a field with a band, a field taken from a favourite colour, a charge taken from an object, and two and three charges.

The late-night reader - Vert, two books in pale Or

Input:

{
 "task": "grant",
 "holder": "me",
 "values": "1. kindness",
 "quirks": "1. reads in bed far too late\n2. names every houseplant",
 "object": "a battered paperback",
 "colour": "dark green",
 "colour_tincture": "vert",
 "charge_count": "2"
}

Reply:

{
 "task": "grant",
 "headline": "Your arms show a green field with two gold books.",
 "arms": {
  "field": "vert",
  "ordinary": "none",
  "ordinary_tincture": "none",
  "charge": "book",
  "charge_count": 2,
  "charge_tincture": "or"
 },
 "blazon": "Vert, two books in pale Or",
 "reasons": [
  {
   "part": "field",
   "from": "dark green",
   "because": "Green is your colour, so it becomes the field itself."
  },
  {
   "part": "ordinary",
   "from": "none",
   "because": "With just one line to work from, a plain field keeps the focus on the charges."
  },
  {
   "part": "charge",
   "from": "a battered paperback",
   "because": "A battered paperback is a book at heart, so it stands as the charge for reading and learning."
  }
 ],
 "motto": "Be kind",
 "motto_from": "kindness"
}

Sam, always early - Azure, on a fess Or two bells Sable

Input:

{
 "task": "grant",
 "holder": "Sam",
 "values": "1. showing up for people\n2. fairness\n3. a good cup of tea",
 "quirks": "1. always early\n2. keeps a spare umbrella by the door",
 "object": "none",
 "colour": "none",
 "colour_tincture": "none",
 "charge_count": "2"
}

Reply:

{
 "task": "grant",
 "headline": "Sam gets a blue shield with a gold band across the middle and two black bells on it.",
 "arms": {
  "field": "azure",
  "ordinary": "fess",
  "ordinary_tincture": "or",
  "charge": "bell",
  "charge_count": 2,
  "charge_tincture": "sable"
 },
 "blazon": "Azure, on a fess Or two bells Sable",
 "reasons": [
  {
   "part": "field",
   "from": "showing up for people",
   "because": "Showing up for people is pretty much what loyalty means, so the field is blue."
  },
  {
   "part": "ordinary",
   "from": "fairness",
   "because": "Fairness is what balance means, so there's a band straight across the middle."
  },
  {
   "part": "charge",
   "from": "always early",
   "because": "Being always early is simply timekeeping, and that same steady habit is why the two charges are black."
  }
 ],
 "motto": "To show up for people",
 "motto_from": "showing up for people"
}

The tinkerer - Or, on a fess Gules three anchors Or

Input:

{
 "task": "grant",
 "holder": "me",
 "values": "1. curiosity\n2. being useful",
 "quirks": "1. fixes things with tape\n2. asks too many questions\n3. never finishes a crossword",
 "object": "my bicycle",
 "colour": "orange",
 "colour_tincture": "none",
 "charge_count": "3"
}

Reply:

{
 "task": "grant",
 "headline": "Your shield is gold, crossed by a red band, with three gold anchors on it.",
 "arms": {
  "field": "or",
  "ordinary": "fess",
  "ordinary_tincture": "gules",
  "charge": "anchor",
  "charge_count": 3,
  "charge_tincture": "or"
 },
 "blazon": "Or, on a fess Gules three anchors Or",
 "reasons": [
  {
   "part": "field",
   "from": "curiosity",
   "because": "Curiosity didn't match any of the colours' meanings, so gold, the first in line, was used instead."
  },
  {
   "part": "ordinary",
   "from": "being useful",
   "because": "None of the band shapes matched being useful, so the first one in line, a band across the middle, was used instead."
  },
  {
   "part": "charge",
   "from": "fixes things with tape",
   "because": "Fixing things with tape makes you someone people can rely on, which is just what the anchor stands for."
  }
 ],
 "motto": "Be curious",
 "motto_from": "curiosity"
}

Build the input yourself

Load the engine in node (global.window = global; require("./armskit.js"); require("./replykit.js")), then:

const K = ArmsKit, R = ReplyKit;
const built = K.buildInput(K.form({ holder: "Sam", value1: "showing up for people", value2: "fairness",
  quirk1: "always early", quirk2: "keeps a spare umbrella by the door", object: "", colour: "" }));  // built.ok is false, with built.note, until a value and a quirk are given
const wire = K.toWire(built.input);   // POST this to /estimate and /run
// then: const reply = R.normalize(R.parseReply(job.output.output));
// R.check(reply, built).notes                        // the page's re-check of the grant
// K.blazon(R.fixed(reply, built))                    // the page's own blazon for the same arms

Form keys: holder, value1-value3, quirk1-quirk3, object and colour, each up to 80 characters (40 for the holder).

Step 1 — a tiny client helper

One function that sends JSON and unwraps the envelope. Paste a personal token from /tokens.html, or leave it empty and mint a guest token in step 2.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://on-a-field.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

import json, urllib.request

BASE = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "paste-your-token-here"  # from https://on-a-field.skillsafe.ai/tokens.html

def api(method, path, body=None, headers=None):
    req = urllib.request.Request(BASE + path, method=method,
        data=None if body is None else json.dumps(body).encode(),
        headers={"Content-Type": "application/json", **({"Authorization": "Bearer " + TOKEN} if TOKEN else {}), **(headers or {})})
    with urllib.request.urlopen(req) as r:
        env = json.load(r)
    if env.get("error"):
        raise RuntimeError(env["error"])
    return env["data"]

// on-a-field.mjs -- Node 18+ (global fetch)
const BASE = "https://api.skillsafe.ai/v1/app-api";
let TOKEN = "paste-your-token-here"; // from https://on-a-field.skillsafe.ai/tokens.html
async function api(method, path, body, headers = {}) {
  const r = await fetch(BASE + path, { method, headers: { "Content-Type": "application/json",
    ...(TOKEN ? { Authorization: "Bearer " + TOKEN } : {}), ...headers },
    body: body === undefined ? undefined : JSON.stringify(body) });
  const env = await r.json();
  if (env.error) throw new Error(env.error.code + ": " + env.error.message);
  return env.data;
}

package main

import ("bytes"; "encoding/json"; "fmt"; "net/http")

const base = "https://api.skillsafe.ai/v1/app-api"
var token = "paste-your-token-here" // from https://on-a-field.skillsafe.ai/tokens.html

func api(method, path string, body any, headers map[string]string) (map[string]any, error) {
	var buf bytes.Buffer
	if body != nil { json.NewEncoder(&buf).Encode(body) }
	req, _ := http.NewRequest(method, base+path, &buf)
	req.Header.Set("Content-Type", "application/json")
	if token != "" { req.Header.Set("Authorization", "Bearer "+token) }
	for k, v := range headers { req.Header.Set(k, v) }
	res, err := http.DefaultClient.Do(req)
	if err != nil { return nil, err }
	defer res.Body.Close()
	var env struct { Data map[string]any; Error map[string]any }
	json.NewDecoder(res.Body).Decode(&env)
	if env.Error != nil { return nil, fmt.Errorf("%v", env.Error) }
	return env.Data, nil
}

// OnAField.java -- Java 17+, with com.fasterxml.jackson.core:jackson-databind
import com.fasterxml.jackson.databind.*;
import java.net.URI; import java.net.http.*; import java.util.*;

public class OnAField {
  static final String BASE = "https://api.skillsafe.ai/v1/app-api";
  static String token = "paste-your-token-here"; // from https://on-a-field.skillsafe.ai/tokens.html
  static final ObjectMapper M = new ObjectMapper();
  static final HttpClient C = HttpClient.newHttpClient();
  static JsonNode api(String method, String path, Object body, Map<String, String> headers) throws Exception {
    var b = HttpRequest.newBuilder(URI.create(BASE + path)).header("Content-Type", "application/json");
    if (!token.isEmpty()) b.header("Authorization", "Bearer " + token);
    if (headers != null) headers.forEach(b::header);
    b.method(method, body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(M.writeValueAsString(body)));
    JsonNode env = M.readTree(C.send(b.build(), HttpResponse.BodyHandlers.ofString()).body());
    if (env.hasNonNull("error")) throw new RuntimeException(env.get("error").toString());
    return env.get("data");
  }
}

require "json"
require "net/http"

BASE = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "paste-your-token-here" # from https://on-a-field.skillsafe.ai/tokens.html

def api(method, path, body = nil, headers = {})
  uri = URI(BASE + path)
  req = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri,
    { "Content-Type" => "application/json" }.merge(TOKEN.empty? ? {} : { "Authorization" => "Bearer #{TOKEN}" }).merge(headers))
  req.body = JSON.generate(body) unless body.nil?
  env = JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }.body)
  raise env["error"].to_s if env["error"]
  env["data"]
end

<?php
const BASE = "https://api.skillsafe.ai/v1/app-api";
$TOKEN = "paste-your-token-here"; // from https://on-a-field.skillsafe.ai/tokens.html

function api(string $method, string $path, $body = null, array $headers = []) {
    global $TOKEN;
    $h = ["Content-Type: application/json"];
    if ($TOKEN) $h[] = "Authorization: Bearer $TOKEN";
    foreach ($headers as $k => $v) $h[] = "$k: $v";
    $ch = curl_init(BASE . $path);
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $h, CURLOPT_RETURNTRANSFER => true]);
    if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    $env = json_decode(curl_exec($ch), true);
    if (!empty($env["error"])) throw new Exception(json_encode($env["error"]));
    return $env["data"];
}

// Program.cs -- .NET 6+ console app
using System.Net.Http.Json; using System.Text.Json; using System.Text.Json.Nodes;

static class Api {
  public const string Base = "https://api.skillsafe.ai/v1/app-api";
  public static string Token = "paste-your-token-here"; // from https://on-a-field.skillsafe.ai/tokens.html
  static readonly HttpClient C = new();
  public static async Task<JsonNode?> Call(string method, string path, object? body = null, Dictionary<string, string>? headers = null) {
    var req = new HttpRequestMessage(new HttpMethod(method), Base + path);
    if (Token != "") req.Headers.Add("Authorization", "Bearer " + Token);
    if (headers != null) foreach (var h in headers) req.Headers.Add(h.Key, h.Value);
    if (body != null) req.Content = JsonContent.Create(body);
    var env = JsonNode.Parse(await (await C.SendAsync(req)).Content.ReadAsStringAsync())!;
    if (env["error"] is JsonNode e && e.GetValueKind() != JsonValueKind.Null) throw new Exception(e.ToJsonString());
    return env["data"];
  }
}

Step 2 — a token

A guest token is enough for /me and /estimate. A run is metered, so it needs a personal token: sign in on /tokens.html and copy it from there.

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"on-a-field"}' | jq -r '.data.token')

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN = ""
TOKEN = api("POST", "/guest", {"slug": "on-a-field"})["token"]

// a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN = "";
TOKEN = (await api("POST", "/guest", { slug: "on-a-field" })).token;

// inside main: a guest token (enough for /me and /estimate); a run needs your personal token
token = ""
g, err := api("POST", "/guest", map[string]string{"slug": "on-a-field"}, nil)
if err != nil { panic(err) }
token = g["token"].(string)

// inside main: a guest token (enough for /me and /estimate); a run needs your personal token
token = "";
token = api("POST", "/guest", Map.of("slug", "on-a-field"), null).get("token").asText();

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN.replace("")
TOKEN.replace(api("POST", "/guest", { slug: "on-a-field" })["token"])

// a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
$TOKEN = "";
$TOKEN = api("POST", "/guest", ["slug" => "on-a-field"])["token"];

// a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
Api.Token = "";
Api.Token = (await Api.Call("POST", "/guest", new { slug = "on-a-field" }))!["token"]!.GetValue<string>();

Step 3 — `GET /me`

Who the token is (subject_type: user or guest) and the credit balance.

api GET /me | jq '.data | {subject_type, credits}'

me = api("GET", "/me")
print(me["subject_type"], me.get("credits"))

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

me, _ := api("GET", "/me", nil, nil)
fmt.Println(me["subject_type"], me["credits"])

JsonNode me = api("GET", "/me", null, null);
System.out.println(me.get("subject_type") + " " + me.get("credits"));

me = api("GET", "/me")
puts [me["subject_type"], me["credits"]].inspect

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

var me = await Api.Call("GET", "/me");
Console.WriteLine($"{me!["subject_type"]} {me["credits"]}");

Step 4 — `POST /estimate`

Free. The body is the run input itself, the bare object (never wrapped in {"input": ...}). hold_credits is a reservation, not the price; min_credits is what the balance must cover; model_alias reads gpt-terra.

# input.json: the run input object - {"task": "grant", "holder": "Sam", "values": "1. ...", "quirks": "1. ...", "object": "none", "colour": "none", "colour_tincture": "none", "charge_count": "2"}
# - see the field table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}'

inp = json.load(open("input.json"))   # {"task": "grant", "holder": "Sam", "values": "1. ...", "quirks": "1. ...", "object": "none", "colour": "none", "colour_tincture": "none", "charge_count": "2"}
# - see the field table
est = api("POST", "/estimate", inp)
print(est["hold_credits"], est["min_credits"], est["model"], est.get("warnings"))

import { readFileSync } from "node:fs";
const input = JSON.parse(readFileSync("input.json", "utf8")); // {task: "grant", holder, values, quirks, object, colour, colour_tincture, charge_count} (see the field table)
const est = await api("POST", "/estimate", input);
console.log(est.hold_credits, est.min_credits, est.model, est.warnings);

raw, _ := os.ReadFile("input.json") // add "os" to the imports
var input map[string]any
json.Unmarshal(raw, &input)
est, _ := api("POST", "/estimate", input, nil)
fmt.Println(est["hold_credits"], est["min_credits"], est["model"])

Map<String, Object> input = M.readValue(new java.io.File("input.json"), Map.class);
JsonNode est = api("POST", "/estimate", input, null);
System.out.println(est.get("hold_credits") + " " + est.get("min_credits") + " " + est.get("model"));

input = JSON.parse(File.read("input.json"))
est = api("POST", "/estimate", input)
puts [est["hold_credits"], est["min_credits"], est["model"]].inspect

$input = json_decode(file_get_contents("input.json"), true);
$est = api("POST", "/estimate", $input);
echo $est["hold_credits"], " ", $est["min_credits"], " ", $est["model"], "\n";

var input = JsonNode.Parse(File.ReadAllText("input.json"))!;
var est = await Api.Call("POST", "/estimate", input);
Console.WriteLine($"{est!["hold_credits"]} {est["min_credits"]} {est["model"]}");

Step 5 — `POST /run`, then poll the job

Send an Idempotency-Key built from the lane and the input: a retry with the same key never bills twice. The page uses on-a-field:<task>:<inputHash>:a<attempt> (the one task is grant), and its one reformat retry (with retry_note added) is attempt 2, a new key and a second run. The job's output.output is the reply text; truncated: true means the balance cut it short.

KEY="on-a-field:grant:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}'

import hashlib, time
key = "on-a-field:" + inp["task"] + ":" + hashlib.sha256(json.dumps(inp).encode()).hexdigest()[:16] + ":a1"
job = api("POST", "/run", inp, {"Idempotency-Key": key})
while True:
    j = api("GET", "/jobs/" + job["job_id"])
    if j["status"] in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(2)
reply = json.loads(j["output"]["output"])  # the reply as one JSON object
print(j["charged_credits"], j.get("truncated"), reply.get("blazon"), reply.get("motto"))

import { createHash } from "node:crypto";
const key = `on-a-field:${input.task}:${createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 16)}:a1`;
const job = await api("POST", "/run", input, { "Idempotency-Key": key });
let j;
do { await new Promise((r) => setTimeout(r, 2000)); j = await api("GET", "/jobs/" + job.job_id); }
while (!["succeeded", "failed", "cancelled"].includes(j.status));
const reply = JSON.parse(j.output.output);
console.log(j.charged_credits, j.truncated, reply.blazon, reply.motto);

sum := sha256.Sum256(raw) // add "crypto/sha256", "encoding/hex", "time" to the imports
key := "on-a-field:" + input["task"].(string) + ":" + hex.EncodeToString(sum[:8]) + ":a1"
job, _ := api("POST", "/run", input, map[string]string{"Idempotency-Key": key})
var j map[string]any
for {
	time.Sleep(2 * time.Second)
	j, _ = api("GET", "/jobs/"+job["job_id"].(string), nil, nil)
	if s := j["status"]; s == "succeeded" || s == "failed" || s == "cancelled" { break }
}
fmt.Println(j["charged_credits"], j["truncated"], j["output"].(map[string]any)["output"])

var digest = java.security.MessageDigest.getInstance("SHA-256").digest(M.writeValueAsBytes(input));
String key = "on-a-field:" + input.get("task") + ":" + HexFormat.of().formatHex(digest, 0, 8) + ":a1";
JsonNode job = api("POST", "/run", input, Map.of("Idempotency-Key", key)), j;
do { Thread.sleep(2000); j = api("GET", "/jobs/" + job.get("job_id").asText(), null, null); }
while (!Set.of("succeeded", "failed", "cancelled").contains(j.get("status").asText()));
JsonNode reply = M.readTree(j.get("output").get("output").asText());
System.out.println(j.get("charged_credits") + " " + reply);

require "digest"
key = "on-a-field:#{input["task"]}:#{Digest::SHA256.hexdigest(JSON.generate(input))[0, 16]}:a1"
job = api("POST", "/run", input, { "Idempotency-Key" => key })
j = nil
loop do
  sleep 2
  j = api("GET", "/jobs/#{job["job_id"]}")
  break if %w[succeeded failed cancelled].include?(j["status"])
end
reply = JSON.parse(j["output"]["output"])
puts [j["charged_credits"], j["truncated"], reply["blazon"], reply["motto"]].inspect

$key = "on-a-field:" . $input["task"] . ":" . substr(hash("sha256", json_encode($input)), 0, 16) . ":a1";
$job = api("POST", "/run", $input, ["Idempotency-Key" => $key]);
do { sleep(2); $j = api("GET", "/jobs/" . $job["job_id"]); }
while (!in_array($j["status"], ["succeeded", "failed", "cancelled"]));
$reply = json_decode($j["output"]["output"], true);
echo $j["charged_credits"], " ", ($reply["blazon"] ?? ""), " ", ($reply["motto"] ?? ""), "\n";

var digest = System.Security.Cryptography.SHA256.HashData(System.Text.Encoding.UTF8.GetBytes(input.ToJsonString()));
var key = $"on-a-field:{input["task"]}:{Convert.ToHexString(digest, 0, 8).ToLowerInvariant()}:a1";
var job = await Api.Call("POST", "/run", input, new() { ["Idempotency-Key"] = key });
JsonNode j;
do { await Task.Delay(2000); j = (await Api.Call("GET", "/jobs/" + job!["job_id"]))!; }
while (!new[] { "succeeded", "failed", "cancelled" }.Contains(j["status"]!.GetValue<string>()));
var reply = JsonNode.Parse(j["output"]!["output"]!.GetValue<string>());
Console.WriteLine($"{j["charged_credits"]} {reply}");

Step 6 — `POST /run-stream`

The same run as Server-Sent Events, with the same input.json. Browsers receive progress ticks rather than text deltas; the final done event carries the reply.

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: on-a-field:grant:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json

rev = json.load(open("input.json"))  # the same run input as input.json: {"task": "grant", "holder": "Sam", "values": "1. ...", "quirks": "1. ...", "object": "none", "colour": "none", "colour_tincture": "none", "charge_count": "2"}
# - see the field table
req = urllib.request.Request(BASE + "/run-stream", method="POST", data=json.dumps(rev).encode(),
    headers={"Content-Type": "application/json", "Authorization": "Bearer " + TOKEN,
             "Idempotency-Key": "on-a-field:grant:" + hashlib.sha256(json.dumps(rev).encode()).hexdigest()[:16] + ":a1"})
with urllib.request.urlopen(req) as r:
    for line in r:
        line = line.decode().strip()
        if line.startswith("data:"):
            print(line[5:].strip()[:200])

const rev = JSON.parse(readFileSync("input.json", "utf8"));
const r = await fetch(BASE + "/run-stream", { method: "POST", body: JSON.stringify(rev), headers: {
  "Content-Type": "application/json", Authorization: "Bearer " + TOKEN,
  "Idempotency-Key": `on-a-field:grant:${createHash("sha256").update(JSON.stringify(rev)).digest("hex").slice(0, 16)}:a1` } });
const dec = new TextDecoder();
for await (const chunk of r.body) for (const line of dec.decode(chunk).split("\n"))
  if (line.startsWith("data:")) console.log(line.slice(5).trim().slice(0, 200));

rraw, _ := os.ReadFile("input.json") // add "bufio", "strings" to the imports
rs := sha256.Sum256(rraw)
req, _ := http.NewRequest("POST", base+"/run-stream", bytes.NewReader(rraw))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "on-a-field:grant:"+hex.EncodeToString(rs[:8])+":a1")
res, _ := http.DefaultClient.Do(req)
sc := bufio.NewScanner(res.Body)
for sc.Scan() { if l := sc.Text(); strings.HasPrefix(l, "data:") { fmt.Println(l[5:]) } }

String rev = java.nio.file.Files.readString(java.nio.file.Path.of("input.json"));
var rd = java.security.MessageDigest.getInstance("SHA-256").digest(rev.getBytes());
var sreq = HttpRequest.newBuilder(URI.create(BASE + "/run-stream")).header("Content-Type", "application/json")
  .header("Authorization", "Bearer " + token).header("Idempotency-Key", "on-a-field:grant:" + HexFormat.of().formatHex(rd, 0, 8) + ":a1")
  .POST(HttpRequest.BodyPublishers.ofString(rev)).build();
C.send(sreq, HttpResponse.BodyHandlers.ofLines()).body().filter(l -> l.startsWith("data:")).forEach(System.out::println);

rev = File.read("input.json")
uri = URI(BASE + "/run-stream")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json", "Authorization" => "Bearer #{TOKEN}",
  "Idempotency-Key" => "on-a-field:grant:#{Digest::SHA256.hexdigest(rev)[0, 16]}:a1")
req.body = rev
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |h|
  h.request(req) { |res| res.read_body { |chunk| chunk.each_line { |l| puts l if l.start_with?("data:") } } }
end

$rev = file_get_contents("input.json");
$ch = curl_init(BASE . "/run-stream");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $rev, CURLOPT_HTTPHEADER => [
    "Content-Type: application/json", "Authorization: Bearer $TOKEN",
    "Idempotency-Key: on-a-field:grant:" . substr(hash("sha256", $rev), 0, 16) . ":a1"],
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) { foreach (explode("\n", $chunk) as $l) if (str_starts_with($l, "data:")) echo $l, "\n"; return strlen($chunk); }]);
curl_exec($ch);

var rev = File.ReadAllText("input.json");
var rd = System.Security.Cryptography.SHA256.HashData(System.Text.Encoding.UTF8.GetBytes(rev));
var sreq = new HttpRequestMessage(HttpMethod.Post, Api.Base + "/run-stream") { Content = new StringContent(rev, System.Text.Encoding.UTF8, "application/json") };
sreq.Headers.Add("Authorization", "Bearer " + Api.Token);
sreq.Headers.Add("Idempotency-Key", $"on-a-field:grant:{Convert.ToHexString(rd, 0, 8).ToLowerInvariant()}:a1");
using var http = new HttpClient();
using var res = await http.SendAsync(sreq, HttpCompletionOption.ResponseHeadersRead);
using var rdr = new StreamReader(await res.Content.ReadAsStreamAsync());
for (string? l; (l = await rdr.ReadLineAsync()) != null;) if (l.StartsWith("data:")) Console.WriteLine(l);

Drive On a Field from your own code

Base URL and the envelope

The task field, the input and the rules

The reply

Worked examples - every sample

The late-night reader - Vert, two books in pale Or

Sam, always early - Azure, on a fess Or two bells Sable

The tinkerer - Or, on a fess Gules three anchors Or

Build the input yourself

Step 1 — a tiny client helper

Step 2 — a token

Step 3 — GET /me

Step 4 — POST /estimate

Step 5 — POST /run, then poll the job

Step 6 — POST /run-stream

Step 3 — `GET /me`

Step 4 — `POST /estimate`

Step 5 — `POST /run`, then poll the job

Step 6 — `POST /run-stream`