← Sugar Slot
Panel API
Tokens

Drive Sugar Slot from your own code

The one metered task, panel, is available over HTTP. It takes an invented sweet - the base, the shape and the finish, one to three flavours, the name and tagline, the wrapper and lettering colours, who it is for, the price - plus the page's own flags, and returns a verdict (stock it, tweak it or rethink it), five scores, one fix per flag, three name ideas that fit the coil label and a short shelf card.

The division of labour first: the page owns the flavour-pairing rule, the flags, the score bands and the verdict; the model owns the judgement and the words; the page re-checks the reply. All of it comes from sweetkit.js, which you can run yourself (see Build the input yourself). The pairing rule and the taste gauges are the page's own rules of thumb, not a taste test.

Get a token on the token page (step 2 below also shows how to mint a guest token in code).

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": "...", "status": 402, "details": { ... } } }

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

StatusCodeMeaning
400validation_errorThe body is not a JSON object, or a required field (task, sweet, flavours, name, wrapper, audience, price, page_facts) is missing.
401unauthorizedNo token, or a stale one. Mint a guest token or sign in again.
402insufficient_creditsThe balance is under min_credits. Price with /estimate first.
403forbiddenA guest token tried to run: asking the panel is metered and needs a personal token.
404not_foundUnknown job id.
429rate_limitedBack off and retry.
5xxserver_errorTransient. Retry with the same Idempotency-Key so a retry never double-bills.

The task field, the flags and the verdict

Every run sends task: panel; a missing or different one is still answered as panel. The page first rates each flavour pair by family (SweetKit.pairs): classic (the same family, or a familiar match), clash (a known clash such as mint with salt) or bold (everything else). Then it lists numbered flags (SweetKit.flags), each red or amber and tied to one of the five score axes:

The verdict follows a fixed order, first match wins (SweetKit.verdictFor): rethink if any flag is red; tweak if any flag is amber; stock otherwise. Each axis's allowed score range follows from its flags (SweetKit.axisBand): 1-2 with a red flag, 2-3 with an amber flag, 3-5 with none. The page sends all of it in page_facts; the model copies the verdict and keeps every score in its band, and the page flags a reply that does not.

The input

Every value is a string (objects are never sent). app.js builds it with SweetKit.buildInput(form).input.

FieldRequiredWhat it holds
taskyesAlways panel.
sweetyesThe base, the shape and the finish, e.g. Gummy, heart shape, sugar-sanded.
flavoursyesOne to three flavours, each with its family in brackets.
nameyesThe sweet's name (at most 40 characters).
taglinenoThe person's tagline (at most 60 characters), or none given.
wrapperyesThe wrapper colour and the lettering colour.
audienceyesStarts with kids, teens, grownups, everyone or nostalgia.
priceyesStarts with pocket, standard or treat, with its coins (1, 2 or 4).
notenoThe person's words (at most 240 characters, the middle cut with [...]), or none given.
page_factsyesThe page's lines (SweetKit.pageFacts): verdict, flags, one flag N line per flag, pairings, taste meters, wrapper contrast and score bands.
clip_notenoWhat the page shortened, or absent.
retry_notenoSent only on the page's one reformat retry.

The reply

The reply is one JSON object in job.output.output. The page parses it with SweetKit.parseReply and SweetKit.normalize (a cut-off stream is closed by SweetKit.closeJson and shown as "N of 9 sections recovered").

{"task": "panel", "verdict": "stock | tweak | rethink", "verdict_reason": "...", "headline": "...",
 "scores": [{"axis": "craving | standout | name | wrapper | fit", "score": 4, "why": "..."}],
 "pull": "...", "hesitation": "...",
 "fixes": [{"flag": 1, "change": "...", "why": "..."}],
 "names": ["...", "...", "..."],
 "shelf_card": {"tagline": "...", "blurb": "..."}}
FieldRule
scoresFive, in the order craving, standout, name, wrapper, fit; each inside its band; why at most 20 words.
fixesOne per flag in flag order (flag = its number), then polish ideas with flag 0: exactly 2 for stock, at most 1 otherwise. change at most 20 words, why at most 18.
namesExactly 3, each at most 18 characters and 3 words, no digits, not the current name, no real brand.
shelf_cardtagline at most 8 words; blurb at most 30 words on taste and texture, using only the picked flavours, the finish, the shape and the base.
pull, hesitation, headlineAt most 25, 25 and 10 words.

The page then checks the reply against its own facts (SweetKit.check): the verdict, every score's band, one fix per flag and their order, the number of polish ideas, the name ideas' length, a shelf card that names an unpicked flavour, any health, diet or allergy claim, and internal field names in the prose.

Worked examples, one per verdict

These are the four free samples on the page: the exact input and a stand-in model's reply, unedited.

A tropical chew with no flags - stock

Input:

{
 "task": "panel",
 "sweet": "Chewy taffy, drop shape, sugar-sanded",
 "flavours": "mango (tropical family), passion fruit (tropical family), coconut (tropical family)",
 "name": "Sunset Chews",
 "tagline": "none given",
 "wrapper": "tangerine wrapper with ink black lettering",
 "audience": "everyone (anyone of any age)",
 "price": "standard (an everyday sweet, 2 coins in the machine)",
 "note": "For a stall at a school summer fair.",
 "page_facts": "verdict: stock\nflags: none\npairings: mango + passion fruit classic; mango + coconut classic; passion fruit + coconut classic\ntaste meters (page estimates, 0-5): sweet 5, sour 2, kick 2\nwrapper contrast: 6.5:1\nscore bands: craving 3-5, standout 3-5, name 3-5, wrapper 3-5, fit 3-5"
}

Reply:

{
 "task": "panel",
 "verdict": "stock",
 "verdict_reason": "No listed concerns hold back this tropical, sugar-sanded taffy, so it is ready to sell as is.",
 "headline": "A juicy tropical taffy this panel would shelve now",
 "scores": [
  {
   "axis": "craving",
   "score": 4,
   "why": "Tropical mango, passion fruit and coconut on sugar-sanded taffy feels juicy and craveable for a drop sweet."
  },
  {
   "axis": "standout",
   "score": 4,
   "why": "Three tropical flavours together and a sugar-sanded drop shape set this apart from plainer chewy sweets."
  },
  {
   "axis": "name",
   "score": 4,
   "why": "Sunset Chews reads warm and tropical, matching the mango and passion fruit without naming every flavour."
  },
  {
   "axis": "wrapper",
   "score": 5,
   "why": "Ink black lettering reads clearly against the tangerine wrapper with strong, comfortable contrast."
  },
  {
   "axis": "fit",
   "score": 4,
   "why": "A standard-priced tropical chew for everyone suits any age without leaning young or grown-up."
  }
 ],
 "pull": "Everyone goes for the tropical mango, passion fruit and coconut mix and the sugar-sanded crunch on this chewy drop.",
 "hesitation": "Three tropical flavours together might taste a touch similar, so the mix could feel less varied than hoped.",
 "fixes": [
  {
   "flag": 0,
   "change": "Swap the sugar-sanded finish for fizzy popping bits to add more excitement to the chew.",
   "why": "Popping texture would make the chew feel more exciting beyond simple sweetness."
  },
  {
   "flag": 0,
   "change": "Shape the taffy as a star instead of a drop to catch more eyes on the shelf.",
   "why": "A star shape stands out more than a plain drop on a crowded shelf."
  }
 ],
 "names": [
  "Tropic Taffy Trio",
  "Mango Passion Chew",
  "Mango Coconut Chew"
 ],
 "shelf_card": {
  "tagline": "Three tropical flavours in one chewy drop",
  "blurb": "A sugar-sanded chewy taffy drop with juicy mango, passion fruit and coconut, each bite soft, sweet and lightly crunchy on the outside."
 }
}

A fizzy lemon drop with a long name and pale lettering - tweak

Input:

{
 "task": "panel",
 "sweet": "Hard candy, drop shape, fizzy popping bits",
 "flavours": "lemon (citrus family), elderflower (floral family)",
 "name": "Grandma's Lemon Sherbet Fizzers",
 "tagline": "Fizz like the old days",
 "wrapper": "lemon yellow wrapper with cream lettering",
 "audience": "nostalgia (people who miss old sweet-shop sweets)",
 "price": "pocket (pocket change, 1 coin in the machine)",
 "note": "none given",
 "page_facts": "verdict: tweak\nflags: 2\nflag 1 (amber, name): the name \"Grandma's Lemon Sherbet Fizzers\" is 31 characters and 4 words; the coil label holds 18 characters and 3 words\nflag 2 (amber, wrapper): cream lettering on a lemon yellow wrapper has a contrast of 1.3:1; the page wants at least 3:1 so the name reads through the glass\npairings: lemon + elderflower classic\ntaste meters (page estimates, 0-5): sweet 3, sour 3, kick 4\nwrapper contrast: 1.3:1\nscore bands: craving 3-5, standout 3-5, name 2-3, wrapper 2-3, fit 3-5"
}

Reply:

{
 "task": "panel",
 "verdict": "tweak",
 "verdict_reason": "The verdict is a tweak because the name runs long for the machine's window and the cream lettering barely shows on the yellow wrapper.",
 "headline": "A nostalgic fizzy favorite that just needs tidying",
 "scores": [
  {
   "axis": "craving",
   "score": 4,
   "why": "Fizzy lemon and elderflower in a hard candy drop feels bright and moreish, inviting another pick."
  },
  {
   "axis": "standout",
   "score": 4,
   "why": "The floral elderflower twist with popping fizz sets this drop apart from ordinary lemon candies."
  },
  {
   "axis": "name",
   "score": 2,
   "why": "The current name is far longer than the machine's window allows, even though it is charming."
  },
  {
   "axis": "wrapper",
   "score": 2,
   "why": "Cream lettering almost disappears against the pale yellow wrapper, making the name hard to read."
  },
  {
   "axis": "fit",
   "score": 5,
   "why": "A pocket-change nostalgic fizzy lemon and elderflower drop suits sweet-shop fans perfectly, true to its simple classic style."
  }
 ],
 "pull": "People who miss old sweet-shop sweets will reach for this drop: bright lemon and elderflower with a satisfying fizzy pop.",
 "hesitation": "The name is long and may not fit cleanly on the machine's window, which could make it harder to notice fast.",
 "fixes": [
  {
   "flag": 1,
   "change": "Rename it to a short name like Lemon Fizz Drop so it reads clearly on the machine.",
   "why": "The long name is hard to read; this keeps the citrus fizz feel in fewer words."
  },
  {
   "flag": 2,
   "change": "Change the lettering to ink black so it stands out on the lemon yellow wrapper.",
   "why": "Cream lettering is too pale on yellow; dark letters will read through the glass clearly."
  }
 ],
 "names": [
  "Fizzy Lemon Drop",
  "Elderflower Fizz",
  "Hard Lemon Drop"
 ],
 "shelf_card": {
  "tagline": "Zingy lemon and elderflower, popping with fizz",
  "blurb": "A hard candy drop bursts with zingy lemon and delicate elderflower, finished with fizzy popping bits that crackle and pop on the tongue."
 }
}

A mocha chocolate aimed at kids at a treat price - tweak (two flags on one axis)

Input:

{
 "task": "panel",
 "sweet": "Filled chocolate, coin shape, smooth, no finish",
 "flavours": "coffee (roast family), milk chocolate (cocoa family)",
 "name": "Mocha Moons",
 "tagline": "none given",
 "wrapper": "cocoa brown wrapper with cream lettering",
 "audience": "kids (children, roughly 5 to 12)",
 "price": "treat (a gift-shop treat, 4 coins in the machine)",
 "note": "Party bags for a ten-year-old's birthday.",
 "page_facts": "verdict: tweak\nflags: 2\nflag 1 (amber, fit): coffee leans to grown-up tastes for a sweet aimed at kids\nflag 2 (amber, fit): a gift-shop treat price is a lot of pocket money for a sweet aimed at kids\npairings: coffee + milk chocolate classic\ntaste meters (page estimates, 0-5): sweet 3, sour 0, kick 3\nwrapper contrast: 9.2:1\nscore bands: craving 3-5, standout 3-5, name 3-5, wrapper 3-5, fit 2-3"
}

Reply:

{
 "task": "panel",
 "verdict": "tweak",
 "verdict_reason": "Coffee leans grown-up and the treat price is a lot of pocket money for kids.",
 "headline": "A promising coin that needs a kid-friendlier flavour and price",
 "scores": [
  {
   "axis": "craving",
   "score": 4,
   "why": "A smooth coin with a classic coffee and milk chocolate filled centre gives a tempting bite."
  },
  {
   "axis": "standout",
   "score": 4,
   "why": "A coffee and milk chocolate filled coin is different from the usual sweets on the shelf."
  },
  {
   "axis": "name",
   "score": 5,
   "why": "Mocha Moons pairs nicely with the coin shape and hints at the coffee and chocolate flavours."
  },
  {
   "axis": "wrapper",
   "score": 5,
   "why": "Cream lettering reads clearly on the cocoa brown wrapper for strong shelf contrast."
  },
  {
   "axis": "fit",
   "score": 2,
   "why": "Coffee leans to grown-up tastes and the treat price is steep pocket money for kids."
  }
 ],
 "pull": "Kids will reach for the smooth coin shape and its rich coffee and milk chocolate taste.",
 "hesitation": "The coffee flavour might feel too grown-up for younger kids to enjoy.",
 "fixes": [
  {
   "flag": 1,
   "change": "Swap the coffee flavour for caramel to pair with the milk chocolate without the grown-up note.",
   "why": "Caramel is a gentler flavour that still suits milk chocolate and feels right for kids."
  },
  {
   "flag": 2,
   "change": "Move the price down from treat to standard so it costs less pocket money for kids.",
   "why": "A lower price fits a kids sweet better than a gift-shop treat price."
  },
  {
   "flag": 0,
   "change": "Swap the cream lettering for lemon yellow to lift the cocoa brown wrapper even more.",
   "why": "Lemon yellow keeps strong contrast while adding a brighter pop on the shelf."
  }
 ],
 "names": [
  "Choco Coin",
  "Smooth Disc",
  "Milk Choc Coin"
 ],
 "shelf_card": {
  "tagline": "Rich coffee meets milk chocolate in every coin",
  "blurb": "A smooth filled chocolate coin combining coffee and milk chocolate in a classic match."
 }
}

A sour-dusted mint and sea-salt fudge - rethink

Input:

{
 "task": "panel",
 "sweet": "Fudge, cube shape, sour-dusted",
 "flavours": "mint (mint family), sea salt (salty family), caramel (toasted sweet family)",
 "name": "Sweet Treat",
 "tagline": "none given",
 "wrapper": "deep teal wrapper with cream lettering",
 "audience": "grownups (grown-ups)",
 "price": "standard (an everyday sweet, 2 coins in the machine)",
 "note": "I wanted something salty and fresh at once.",
 "page_facts": "verdict: rethink\nflags: 3\nflag 1 (red, craving): mint with sea salt is a clash on the page's pairing rule (mint and salty)\nflag 2 (red, craving): a sour dusting on fudge fights the creamy base\nflag 3 (amber, name): the name \"Sweet Treat\" uses only everyday sweet-shop words, so it could be anything\npairings: mint + sea salt clash; mint + caramel bold; sea salt + caramel classic\ntaste meters (page estimates, 0-5): sweet 2, sour 2, kick 4\nwrapper contrast: 5.5:1\nscore bands: craving 1-2, standout 3-5, name 2-3, wrapper 3-5, fit 3-5"
}

Reply:

{
 "task": "panel",
 "verdict": "rethink",
 "verdict_reason": "The mint and sea salt clash with each other, and the sour dusting fights the fudge base, which together call for bigger changes to this sweet.",
 "headline": "A bold salty-sweet idea that needs its clash fixed",
 "scores": [
  {
   "axis": "craving",
   "score": 1,
   "why": "Mint and sea salt clash while the sour dusting fights the fudge, both working against the pull here."
  },
  {
   "axis": "standout",
   "score": 4,
   "why": "A sour-dusted fudge cube mixing mint, sea salt and caramel is unusual on any shelf."
  },
  {
   "axis": "name",
   "score": 2,
   "why": "Sweet Treat says nothing about the mint, salt or caramel inside, just everyday words."
  },
  {
   "axis": "wrapper",
   "score": 4,
   "why": "Cream lettering reads clearly on the deep teal wrapper, giving solid shelf contrast."
  },
  {
   "axis": "fit",
   "score": 4,
   "why": "Sea salt and caramel suit a grown-up palate at an everyday price point."
  }
 ],
 "pull": "Grown-ups drawn to a sharp edge will reach for the sour-dusted cube, where mint and sea salt cut into the rich caramel.",
 "hesitation": "Mint and sea salt are a known clash, so the first bite could taste muddled rather than refreshing or balanced.",
 "fixes": [
  {
   "flag": 1,
   "change": "Swap mint for coffee, which pairs well with the sea salt and caramel already picked.",
   "why": "Mint and sea salt clash together; coffee suits the salty caramel instead."
  },
  {
   "flag": 2,
   "change": "Swap the sour dusting for a chocolate-coated finish, which suits the creamy fudge base.",
   "why": "Sour dusting clashes with a creamy fudge base; chocolate-coated finishes work together instead."
  },
  {
   "flag": 3,
   "change": "Rename to \"Caramel Salt Cube,\" using the caramel, sea salt and cube shape already picked.",
   "why": "Everyday sweet-shop words say nothing about this sweet; caramel and salt are distinct."
  }
 ],
 "names": [
  "Salty Caramel Cube",
  "Fudge Caramel Cube",
  "Salted Fudge Cube"
 ],
 "shelf_card": {
  "tagline": "Sour, salty and sweet in one cube",
  "blurb": "Chewy fudge cube dusted with a sharp sour coating, carrying cool mint, salty bite and rich caramel in every chew."
 }
}

Build the input yourself

Load the script in node (global.window = global; require("./sweetkit.js")), then:

const K = SweetKit;
const form = K.form({ base: "gummy", flav1: "raspberry", flav2: "lime", flav3: "", finish: "sour", shape: "ring",
  wrap: "grape", ink: "lemon", name: "Zing Rings", tagline: "", audience: "teens", price: "pocket", note: "" });
K.pairs(form);                                   // each flavour pair: classic, bold or clash
K.flags(form);                                   // numbered red and amber flags, each tied to a score axis
K.verdictFor(form);                              // {verdict: "stock", flags, why} - the page's rule
K.axisBand(K.flags(form), "name");               // {lo: 3, hi: 5} - the allowed score range
K.meters(form);                                  // rough sweet, sour and kick, 0-5 (estimates)
const built = K.buildInput(form);
const wire = K.toWire(built.input);              // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output));
// K.check(reply, built, form).notes             // the page's re-check of the reply
// K.md(form, reply)                             // the sweet and the panel as Markdown

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://sugar-slot.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"}
}

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":"sugar-slot"}' | jq -r '.data.token')

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}'

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": "panel", "sweet": "Chewy taffy, drop shape, sugar-sanded", "flavours": "mango (tropical family), passion fruit (tropical family), coconut (tropical family)", "name": "Sunset Chews", "tagline": "none given", "wrapper": "tangerine wrapper with ink black lettering", "audience": "everyone (anyone of any age)", "price": "standard (an everyday sweet, 2 coins in the machine)", "note": "For a stall at a school summer fair.", "page_facts": "verdict: stock\nflags: none\npairings: mango + passion fruit classic; mango + coconut classic; passion fruit + coconut classic\ntaste meters (page estimates, 0-5): sweet 5, sour 2, kick 2\nwrapper contrast: 6.5:1\nscore bands: craving 3-5, standout 3-5, name 3-5, wrapper 3-5, fit 3-5"}
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}'

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 sugar-slot:<task>:<inputHash>:a<attempt> (the one task is panel), 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="sugar-slot:panel:$(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}'

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: sugar-slot:panel:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json