Drive Take a Tab from your own code

The one metered task, fill, is available over HTTP. It takes a take-what-you-need notice the page has already read - where it hangs, who walks past, the tone (warm, dry or silly), how many tabs it has (6 to 10), any tabs the person wrote themselves, their headline if they gave one, the picture and a leave-out list - and returns the filled notice: a headline, a short note, exactly that many tabs (their own first, unchanged) and a line of small print.

The division of labour first: the page does the checking; the model does the writing. Tab length (24 characters fit a tab), repeats, contact details, the picture (the first of sun, cup, leaf, star, umbrella, moon, kite, key whose words appear in the spot or the people, else the sun) and how many tabs are left to write are all computed by TabKit.buildInput. After the reply, the page checks it against the input and puts the person's own tabs and headline back if the reply changed them.

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":"take-a-tab"}), 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`, `spot`, `who`, `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: filling the tabs 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: fill (the one task is fill); a missing or different one is still answered as fill. All fields are strings.

Field	Required	What it holds
`task`	yes	Always `fill`.
`spot`	yes	Where the notice hangs, in the person's words (up to 48 characters).
`who`	yes	Who walks past it, in the person's words (up to 80 characters).
`tone`	yes	`warm`, `dry` or `silly`, followed by a short description, e.g. `dry - deadpan and understated, a straight face with a wink`.
`count`	yes	How many tabs the notice has, `6` to `10`.
`keep`	yes	The person's own tabs as numbered lines (`1. a deep breath`), or `none`.
`to_write`	yes	How many new tabs to write: `count` minus the kept tabs.
`headline`	yes	The person's headline, or `none`.
`motif`	yes	The picture: `sun`, `cup`, `leaf`, `star`, `umbrella`, `moon`, `kite` or `key`.
`avoid`	yes	Topics to leave off the notice, or `none`.
`retry_note`	no	Only on a reformat retry: why the previous reply was unusable.

New tabs are at most 22 characters, something a passer-by can take just by reading it (a feeling, a permission, a thought or a small act), never real objects, money, services or meetings, and never contact details. At least half use a noun from the spot or the people.

The reply

One JSON object, no prose around it:

{"task": "fill", "headline": "...", "note": "...", "tabs": ["...", "..."], "small_print": "...", "motif": "cup"}

Field	What it holds
`headline`	The person's headline copied, or a new one of at most 32 characters.
`note`	One or two short sentences inviting the passers-by to tear off a tab.
`tabs[]`	Exactly `count` strings: the kept tabs first, unchanged, then the new ones.
`small_print`	One light closing line, no promises and no requests.
`motif`	The input's picture, copied.

The page reads the reply with ReplyKit.normalize, lays it over the form with ReplyKit.notice and checks it with ReplyKit.check, which lists, under "The page's check", a wrong tab count, kept tabs or a headline that were changed (the page puts them back), long tabs, repeats, contact details, anything from the leave-out list, and numbers or days the page never sent.

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 all three tones, a picture matched to the spot and pictures chosen by hand, the person's own headline, their own tabs kept in place and a leave-out list.

Office kitchen - dry tone

Input:

{
 "task": "fill",
 "spot": "the office kitchen noticeboard",
 "who": "people waiting for the kettle between meetings",
 "tone": "dry - deadpan and understated, a straight face with a wink",
 "count": "8",
 "keep": "none",
 "to_write": "8",
 "headline": "none",
 "motif": "cup",
 "avoid": "none"
}

Reply:

{
 "task": "fill",
 "headline": "Take One While You Wait",
 "note": "People waiting for the kettle: take a tab to pass the time.",
 "tabs": [
  "A longer kettle stare",
  "Permission to idle",
  "A thought on meetings",
  "A kitchen kind of calm",
  "A pocket of relief",
  "An office-sized sigh",
  "A dash of patience",
  "A long, slow blink"
 ],
 "small_print": "Tabs are self-service; manage your expectations accordingly.",
 "motif": "cup"
}

Laundry room - silly tone

Input:

{
 "task": "fill",
 "spot": "the laundry room in our block of flats",
 "who": "neighbours waiting for the spin cycle to finish",
 "tone": "silly - playful and a little absurd, still kind",
 "count": "10",
 "keep": "1. a matching sock\n2. patience",
 "to_write": "8",
 "headline": "none",
 "motif": "star",
 "avoid": "noise complaints"
}

Reply:

{
 "task": "fill",
 "headline": "Spin, wait, tear off a tab!",
 "note": "Neighbours, while your spin cycle finishes, take a tab - one tiny thing just for you.",
 "tabs": [
  "a matching sock",
  "patience",
  "fondness for the flats",
  "leave to hog the room",
  "a thought about spin",
  "a wink for a neighbour",
  "permission to daydream",
  "a thought you can keep",
  "a tiny hopeful stretch",
  "a warm fuzzy feeling"
 ],
 "small_print": "Limit one per spin, no exceptions",
 "motif": "star"
}

Bus shelter - warm tone

Input:

{
 "task": "fill",
 "spot": "the bus shelter by the park",
 "who": "people waiting for a late bus",
 "tone": "warm - kind and gentle, like a note from a friend",
 "count": "6",
 "keep": "none",
 "to_write": "6",
 "headline": "Take what you need",
 "motif": "umbrella",
 "avoid": "religion"
}

Reply:

{
 "task": "fill",
 "headline": "Take what you need",
 "note": "To the people waiting for the bus: take a tab, it's yours to keep.",
 "tabs": [
  "Smile for the next bus",
  "Lean on the shelter",
  "A patch of park peace",
  "Permission to wait",
  "This moment is enough",
  "Notice your own breath"
 ],
 "small_print": "Take one, leave the rest for someone else.",
 "motif": "umbrella"
}

Office lift - warm tone

Input:

{
 "task": "fill",
 "spot": "the lift in our office building",
 "who": "people heading up to a long day at their desks",
 "tone": "warm - kind and gentle, like a note from a friend",
 "count": "7",
 "keep": "1. a deep breath\n2. permission to take lunch\n3. a straight back",
 "to_write": "4",
 "headline": "Free on the way up",
 "motif": "key",
 "avoid": "work deadlines"
}

Reply:

{
 "task": "fill",
 "headline": "Free on the way up",
 "note": "People on their way up, take a tab just for you - something small, no strings.",
 "tabs": [
  "a deep breath",
  "permission to take lunch",
  "a straight back",
  "a lift of the chin",
  "warmth for the people",
  "permission to soften",
  "a thought to carry"
 ],
 "small_print": "No need to ask - just reach up and tear",
 "motif": "key"
}

Build the input yourself

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

const K = TabKit, R = ReplyKit;
const built = K.buildInput(K.form({ spot: "the office kitchen noticeboard", who: "people waiting for the kettle between meetings",
  tone: "dry", count: "8", headline: "", tabs: "a deep breath", avoid: "", paper: "butter", motif: "auto" }));
// built.ok is false, with built.note, until the spot and the people are given and no tab breaks a rule
const wire = K.toWire(built.input);   // POST this to /estimate and /run
// then: const reply = R.normalize(R.parseReply(job.output.output));
// R.notice(reply, built)        // what the notice shows, your own tabs first
// R.check(reply, built).notes   // the page's check of the reply

Form keys: spot (up to 48 characters), who (up to 80), tone - warm, dry or silly - count from 6 to 10, headline (up to 40, optional), tabs (one per line, up to 24 characters each), avoid (optional), paper (butter, mint, rose, sky, white) and motif (auto or one of the eight pictures).

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://take-a-tab.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://take-a-tab.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"]

// take-a-tab.mjs -- Node 18+ (global fetch)
const BASE = "https://api.skillsafe.ai/v1/app-api";
let TOKEN = "paste-your-token-here"; // from https://take-a-tab.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://take-a-tab.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
}

// TakeATab.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 TakeATab {
  static final String BASE = "https://api.skillsafe.ai/v1/app-api";
  static String token = "paste-your-token-here"; // from https://take-a-tab.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://take-a-tab.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://take-a-tab.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://take-a-tab.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":"take-a-tab"}' | 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": "take-a-tab"})["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: "take-a-tab" })).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": "take-a-tab"}, 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", "take-a-tab"), 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: "take-a-tab" })["token"])

// a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
$TOKEN = "";
$TOKEN = api("POST", "/guest", ["slug" => "take-a-tab"])["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 = "take-a-tab" }))!["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": "fill", "spot": "the office kitchen noticeboard", "who": "people waiting for the kettle between meetings", "tone": "dry - ...", "count": "8", "keep": "none", "to_write": "8", "headline": "none", "motif": "cup", "avoid": "none"}
# - 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": "fill", "spot": "the office kitchen noticeboard", "who": "people waiting for the kettle between meetings", "tone": "dry - ...", "count": "8", "keep": "none", "to_write": "8", "headline": "none", "motif": "cup", "avoid": "none"}
# - 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: "fill", spot, who, tone, count, keep, to_write, headline, motif, avoid} (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 take-a-tab:<task>:<inputHash>:a<attempt> (the one task is fill), 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="take-a-tab:fill:$(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 = "take-a-tab:" + 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("headline"), reply.get("tabs"))

import { createHash } from "node:crypto";
const key = `take-a-tab:${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.headline, reply.tabs);

sum := sha256.Sum256(raw) // add "crypto/sha256", "encoding/hex", "time" to the imports
key := "take-a-tab:" + 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 = "take-a-tab:" + 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 = "take-a-tab:#{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["headline"], reply["tabs"]].inspect

$key = "take-a-tab:" . $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["headline"] ?? ""), " ", ($reply["headline"] ?? ""), "\n";

var digest = System.Security.Cryptography.SHA256.HashData(System.Text.Encoding.UTF8.GetBytes(input.ToJsonString()));
var key = $"take-a-tab:{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: take-a-tab:fill:$(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": "fill", "spot": "the office kitchen noticeboard", "who": "people waiting for the kettle between meetings", "tone": "dry - ...", "count": "8", "keep": "none", "to_write": "8", "headline": "none", "motif": "cup", "avoid": "none"}
# - 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": "take-a-tab:fill:" + 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": `take-a-tab:fill:${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", "take-a-tab:fill:"+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", "take-a-tab:fill:" + 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" => "take-a-tab:fill:#{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: take-a-tab:fill:" . 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", $"take-a-tab:fill:{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 Take a Tab from your own code

Base URL and the envelope

The task field, the input and the rules

The reply

Worked examples - every sample

Office kitchen - dry tone

Laundry room - silly tone

Bus shelter - warm tone

Office lift - warm tone

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`