← Quite Overcome
API

Drive Quite Overcome from your own code

The one metered task, remark, is available over HTTP. It takes 1 to 6 moments as the page's week lines - the moment, what it was like, how much it moved you from 1 to 5 and the page's lead voice - plus the totals, the average, the reading and the keepsake. It returns, for every moment, a remark from a voice of sense and a remark from a voice of sensibility, then a headline, a keepsake step and a closing.

The division of labour first: a fixed rule on the page decides every lead (sense, sensibility or even), the week's reading and the keepsake; the model only writes the words. After a run the page checks that the reply copied every one of those and kept to the house rules.

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":"quite-overcome"}), 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, week) 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: the written remarks are metered and needs a personal sign-in.
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 input and the readings

Every run sends task: remark (the one task is remark); a missing or different one is still answered as remark. Each moment's lead: moved 4 or 5 - sensibility; moved 1 or 2 - sense; moved 3 - even. The reading is the average moved score rounded to 1 decimal place: below 2.0 composed, 2.0 to 2.9 moved, 3.0 to 3.9 transported, 4.0 or more overcome. The keepsake is the moment with the highest moved score, the earliest on a tie.

FieldRequiredWhat it holds
taskyesAlways remark.
weekyesThe page's lines: a house rules: line, a totals: line (moments, lead counts, average, reading, keepsake), then 1 line per moment such as item 3 | an old song on the radio | what it was like: sang along badly | moved: 3 of 5 | lead: even.
retry_notenoOnly on the page's single reformat retry.

The reply is one JSON object:

{"task": "remark", "reading": "transported", "headline": "...", "items": [{"item": "1", "lead": "sensibility", "sense": "...", "sensibility": "..."}], "keepsake": {"item": "1", "step": "..."}, "closing": "..."}
FieldWhat it holds
readingCopied from the totals line.
headlineThe reading in plain words with how many moments there were, at most 16 words.
items1 per moment in order: item (its number), lead (copied), sense (the composed voice, with the moved score as "N of 5", at most 18 words) and sensibility (the rapturous voice, at most 22 words).
keepsakeitem (copied from the totals line) and step (a small way to have that moment again, at most 18 words).
closingA light sentence in which both voices agree on the week, at most 20 words.

The page then checks the reply (SwoonKit.check) and lists any disagreement under "The page's check".

Worked examples - every reading

These are the four free samples on the page: the exact input the page sends and the reply that replays for free.

A flat week, sense leads every moment - fair and composed

Input:

{
 "task": "remark",
 "week": "house rules: lead per moment - moved 4 or 5 of 5: sensibility | moved 1 or 2 of 5: sense | moved 3 of 5: even | reading: the average moved score rounded to 1 decimal place - below 2.0: composed, 2.0 to 2.9: moved, 3.0 to 3.9: transported, 4.0 or more: overcome | keepsake: the moment with the highest moved score, the earliest on a tie\ntotals: 3 moments | sense leads: 3 | sensibility leads: 0 | even: 0 | average moved: 1.7 of 5 | reading: composed | keepsake: item 2 (moved 2 of 5)\nitem 1 | the 8:10 bus | what it was like: late again, stood the whole way | moved: 1 of 5 | lead: sense\nitem 2 | a new stapler at work | what it was like: it staples | moved: 2 of 5 | lead: sense\nitem 3 | lunch at my desk | what it was like: cheese sandwich, fine | moved: 2 of 5 | lead: sense"
}

Reply:

{
 "task": "remark",
 "reading": "composed",
 "headline": "Fair and composed, 3 ordinary moments from your week.",
 "items": [
  {
   "item": "1",
   "lead": "sense",
   "sense": "The 8:10 bus ran late, and you stood the whole way, 1 of 5, plainly an ordinary start.",
   "sensibility": "I confess the standing and the lateness left little chance to swoon, though even a long wait keeps its small, quiet worth."
  },
  {
   "item": "2",
   "lead": "sense",
   "sense": "A new stapler at work simply does its job, 2 of 5, a useful, ordinary thing.",
   "sensibility": "I grant a stapler that merely staples offers no raptures, yet there's a small comfort in a job neatly done."
  },
  {
   "item": "3",
   "lead": "sense",
   "sense": "Lunch at your desk was a cheese sandwich, 2 of 5, a plain, ordinary meal.",
   "sensibility": "I'll own that a cheese sandwich eaten at your desk raised no raptures, yet a quiet meal still deserves its plain due."
  }
 ],
 "keepsake": {
  "item": "2",
  "step": "Keep the new stapler at work within reach, ready to staple again."
 },
 "closing": "We agree: a steady, composed week, nothing dramatic, each small moment worth noting as it was."
}

Rain, a washing machine and a kitten photo - gently moved

Input:

{
 "task": "remark",
 "week": "house rules: lead per moment - moved 4 or 5 of 5: sensibility | moved 1 or 2 of 5: sense | moved 3 of 5: even | reading: the average moved score rounded to 1 decimal place - below 2.0: composed, 2.0 to 2.9: moved, 3.0 to 3.9: transported, 4.0 or more: overcome | keepsake: the moment with the highest moved score, the earliest on a tie\ntotals: 4 moments | sense leads: 2 | sensibility leads: 1 | even: 1 | average moved: 2.5 of 5 | reading: moved | keepsake: item 3 (moved 4 of 5)\nitem 1 | rain on the window | what it was like: heard it while reading in bed | moved: 3 of 5 | lead: even\nitem 2 | the washing machine | what it was like: finished its cycle without drama | moved: 1 of 5 | lead: sense\nitem 3 | a text with a kitten photo | what it was like: a tiny grey kitten asleep in a slipper | moved: 4 of 5 | lead: sensibility\nitem 4 | queue at the post office | what it was like: a long wait, nobody spoke | moved: 2 of 5 | lead: sense"
}

Reply:

{
 "task": "remark",
 "reading": "moved",
 "headline": "Gently moved, 4 ordinary moments from your week.",
 "items": [
  {
   "item": "1",
   "lead": "even",
   "sense": "Rain on the window, heard while reading in bed, 3 of 5, a fair, quiet moment.",
   "sensibility": "I'll own the rain's patter, heard while reading in bed, made a modest, pleasant music, nothing more, nothing less."
  },
  {
   "item": "2",
   "lead": "sense",
   "sense": "The washing machine finished its cycle without drama, 1 of 5, plainly a routine, ordinary moment.",
   "sensibility": "I confess a washing machine finishing without drama stirs little to swoon over, though quiet, uneventful endings have their own small calm."
  },
  {
   "item": "3",
   "lead": "sensibility",
   "sense": "A text with a kitten asleep in a slipper, 4 of 5, truly a delightful little moment.",
   "sensibility": "Oh, a tiny grey kitten asleep in a slipper, what a small, perfect wonder to find waiting in a text!"
  },
  {
   "item": "4",
   "lead": "sense",
   "sense": "The queue at the post office was a long, silent wait, 2 of 5, simply ordinary.",
   "sensibility": "I'll admit a long, silent wait at the post office left little to swoon over, though stillness can hold its quiet grace."
  }
 ],
 "keepsake": {
  "item": "3",
  "step": "Look again at that text, that tiny grey kitten asleep in a slipper, whenever you'd like."
 },
 "closing": "We agree: a gently moved week, lifted brightest by the kitten asleep in a slipper."
}

Toast and a park tied for the keepsake - transported

Input:

{
 "task": "remark",
 "week": "house rules: lead per moment - moved 4 or 5 of 5: sensibility | moved 1 or 2 of 5: sense | moved 3 of 5: even | reading: the average moved score rounded to 1 decimal place - below 2.0: composed, 2.0 to 2.9: moved, 3.0 to 3.9: transported, 4.0 or more: overcome | keepsake: the moment with the highest moved score, the earliest on a tie\ntotals: 4 moments | sense leads: 1 | sensibility leads: 2 | even: 1 | average moved: 3.3 of 5 | reading: transported | keepsake: item 1 (moved 4 of 5)\nitem 1 | toast with good butter | what it was like: warm, salty, eaten standing up | moved: 4 of 5 | lead: sensibility\nitem 2 | a walk home through the park | what it was like: leaves everywhere, smelled of woodsmoke | moved: 4 of 5 | lead: sensibility\nitem 3 | an old song on the radio | what it was like: sang along badly | moved: 3 of 5 | lead: even\nitem 4 | paying the gas bill | what it was like: done, at least | moved: 2 of 5 | lead: sense"
}

Reply:

{
 "task": "remark",
 "reading": "transported",
 "headline": "Transported, 4 moments from your week.",
 "items": [
  {
   "item": "1",
   "lead": "sensibility",
   "sense": "Toast with good butter, warm and salty, eaten standing up, 4 of 5, genuinely good.",
   "sensibility": "Oh, warm, salty toast eaten standing up, what a small, perfect pleasure to savor right where you stood!"
  },
  {
   "item": "2",
   "lead": "sensibility",
   "sense": "A walk home through the park, leaves everywhere, smelling of woodsmoke, 4 of 5, truly good.",
   "sensibility": "Oh, leaves everywhere and the air rich with woodsmoke, what a small, glorious world to walk home through!"
  },
  {
   "item": "3",
   "lead": "even",
   "sense": "An old song on the radio, sung along badly, 3 of 5, a fair, pleasant moment.",
   "sensibility": "I'll grant that singing along badly to an old song on the radio was no rapture, just a modest, cheerful middle ground."
  },
  {
   "item": "4",
   "lead": "sense",
   "sense": "Paying the gas bill, done at least, 2 of 5, plainly an ordinary task.",
   "sensibility": "I confess paying the gas bill, done at least, stirred little to swoon over, though finishing a task has its quiet relief."
  }
 ],
 "keepsake": {
  "item": "1",
  "step": "Make toast with good butter again, warm and salty, and eat it standing up."
 },
 "closing": "We agree: a transported week, warmed by good toast and a woodsmoke-scented walk through the park."
}

A choir and a sunset - quite overcome

Input:

{
 "task": "remark",
 "week": "house rules: lead per moment - moved 4 or 5 of 5: sensibility | moved 1 or 2 of 5: sense | moved 3 of 5: even | reading: the average moved score rounded to 1 decimal place - below 2.0: composed, 2.0 to 2.9: moved, 3.0 to 3.9: transported, 4.0 or more: overcome | keepsake: the moment with the highest moved score, the earliest on a tie\ntotals: 3 moments | sense leads: 0 | sensibility leads: 3 | even: 0 | average moved: 4.7 of 5 | reading: overcome | keepsake: item 1 (moved 5 of 5)\nitem 1 | a choir in the train station | what it was like: stopped me in my tracks | moved: 5 of 5 | lead: sensibility\nitem 2 | a perfect cup of tea | what it was like: strong, and the mug was warm | moved: 4 of 5 | lead: sensibility\nitem 3 | a sunset from the office window | what it was like: pink and orange over the car park | moved: 5 of 5 | lead: sensibility"
}

Reply:

{
 "task": "remark",
 "reading": "overcome",
 "headline": "Quite overcome, 3 radiant moments from your week.",
 "items": [
  {
   "item": "1",
   "lead": "sensibility",
   "sense": "A choir in the train station stopped you in your tracks, 5 of 5, truly wonderful.",
   "sensibility": "Oh, a choir in the train station that stopped you in your tracks, what a glorious, unlooked-for grace!"
  },
  {
   "item": "2",
   "lead": "sensibility",
   "sense": "A perfect cup of tea, strong, with a warm mug, 4 of 5, genuinely lovely.",
   "sensibility": "Oh, a cup of tea so strong, its mug so warm, what a small, perfect comfort!"
  },
  {
   "item": "3",
   "lead": "sensibility",
   "sense": "A sunset from the office window, pink and orange over the car park, 5 of 5, simply glorious.",
   "sensibility": "Oh, pink and orange spilling over the car park, what a small, radiant wonder to catch from an office window!"
  }
 ],
 "keepsake": {
  "item": "1",
  "step": "Stand again in the train station and let the choir stop you in your tracks."
 },
 "closing": "We agree: an overcome week, from a stopping choir to a perfect tea to a glorious sunset."
}

Build the input yourself

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

const K = SwoonKit;
const built = K.buildInput(K.form({ items: [
  { text: "first coffee", detail: "hot, in the quiet before work", moved: 4 },
  { text: "a long meeting", detail: "slides and more slides", moved: 1 }] }));
built.input.week;                       // the page's lines: rules, totals, reading and one line per moment
const wire = K.toWire(built.input);     // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output));
// built.facts.reading                  // the reading the page's rule gives
// K.check(reply, built).notes          // the page's re-check of the reply
// K.md(built, reply, "my week")        // the remarks 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://quite-overcome.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":"quite-overcome"}' | 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": "remark", "week": "house rules: lead per moment - moved 4 or 5 of 5: sensibility ...
totals: 4 moments | sense leads: 1 | sensibility leads: 2 | even: 1 | average moved: 3.3 of 5 | reading: transported | keepsake: item 1 (moved 4 of 5)
item 1 | toast with good butter | what it was like: warm, salty, eaten standing up | moved: 4 of 5 | lead: sensibility
..."}
# - see the field table
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 quite-overcome:<task>:<inputHash>:a<attempt> (the one task is remark), 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="quite-overcome:remark:$(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: quite-overcome:remark:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json