← Promoted to Big
API

Drive Promoted to Big from your own code

The one metered task, pack, is available over HTTP. It takes the child's first name and the page's facts: the child's age and role (big sister, big brother or big sibling), the baby's name and when the baby arrives, who signs, what the child loves, the duties the page picked from its fixed age-safe list, the other changes at home, what stays the same, any worry noticed and the grown-ups-only jobs. It returns one approach (reassure_first, steady_anchors or celebrate), a job title, the greeting, an opening, the offer, the start line, a how-to line per duty, the things that stay the same in the child's words, a reassurance, the sign-off and a short note for the grown-up.

The division of labour first: the page owns the duty list, every pick, every fact and the order; the model owns only the wording; the page then re-checks the reply against its own picks. Lifting, carrying, feeding and bathing the baby are never a child's duty. General, playful ideas - not professional advice.

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":"promoted-to-big"}), 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, child, 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: writing the personal letter 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 and the approaches

Every run sends task: pack (the one task is pack); a missing or different one is still answered as pack. The verdict field holds the approach, by a fixed check order that stops at the first that fits: reassure_first when the worry line says anything other than none noted; steady_anchors when 2 or more other changes are ticked; otherwise celebrate. The page sends its own answer as page_verdict.

Input (every field is a string)

FieldRequiredWhat it holds
taskyesAlways pack.
childyesThe child's first name, up to 24 characters.
page_factsyesOne key | ... per line: child (name, age 2 to 8, role), baby (the name, or no name given - write: the baby, and the arrival: already here, in the next few weeks, in a few months or later on), signed_by, loves, three to five duty_<n> lines (short label and the duty), changes (count and list), one or more stays_<n> lines, worry, grown_ups_only, page_verdict and verdict_rule.
clip_notenoWhat the page shortened, if anything (a worry note over 240 characters keeps its start and end).
retry_notenoOnly on the page's one reformat retry, after an unusable reply.

Reply (one JSON object)

{"task": "pack", "verdict": "celebrate", "verdict_reason": "...", "job_title": "Big sister and Chief Singer",
 "greeting": "Dear Ruby,", "opening": "...", "offer": "...", "start_line": "...",
 "duties": [{"n": 1, "duty": "Sing a song to the baby", "how": "..."}], "stays_same": [{"n": 1, "line": "..."}],
 "reassurance": "...", "signoff": "With love, Mama and Papa", "grown_up_note": "..."}
FieldWhat it holds
verdict, verdict_reasonThe approach id by the check order above; at most 30 words on what decided it.
job_title, greetingThe role with a capital first letter, plus at most one playful specialty from what the child loves (at most 6 words); "Dear <child>,".
opening, offer, start_lineAt most 40, 40 and 25 words: the news (or, for reassure first, a gentle nod to the worry first), the offer of the job to the child, and when the job starts, with the arrival phrase as written.
dutiesExactly one entry per picked duty, in order: n, the page's duty text, and a how line of at most 18 words that never touches a grown-ups-only job.
stays_sameExactly one entry per stays_<n> line, at most 16 words each, meaning unchanged.
reassurance, signoff, grown_up_noteAt most 35 words fitted to the approach; a sign-off ending with signed_by; at most 40 words for the grown-up, ending "Stay close for every duty near the baby."

The page then checks the reply (PromoKit.check): the approach against its order, the role in the job title, the child in the greeting and the signer in the sign-off, the arrival phrase in the start line, that the job is offered to the child (never the baby), one entry per duty with the page's own text and no grown-ups-only word in a how line, one line per stays-the-same item, the reassurance fitted to the approach, pronouns, numbers the form does not have, names the form never uses, leaked field ids and the word limits.

Worked examples

These are the three free samples on the page: the exact input and a stand-in model's reply, unedited. Together they cover all three approaches - a three-year-old with one change coming (celebrate), a five-year-old with three changes at once (steady anchors), and a seven-year-old who keeps asking about time together, with the baby already here (reassure first).

Ruby, 3, one change coming - celebrate

Input:

{
 "task": "pack",
 "child": "Ruby",
 "page_facts": "child | Ruby | age 3 | becoming: big sister\nbaby | no name given - write: the baby | arrival: in a few months\nsigned_by | Mama and Papa\nloves | singing, teddies and splashing in puddles\nduty_1 | Towel passer | Pass the towel to a grown-up at the baby's bath time\nduty_2 | Song singer | Sing a song to the baby\nduty_3 | Toy picker | Pick a soft toy to show the baby\nchanges | 1 | moving to a big bed\nstays_1 | we love you just as much as ever\nstays_2 | you can tell us any feeling, even cross or sad ones\nworry | none noted\ngrown_ups_only | lifting or carrying the baby; feeding the baby; bath water and bathing; anything in the cot or crib; looking after the baby alone\npage_verdict | celebrate\nverdict_rule | reassure_first when a worry is noted; else steady_anchors when 2 or more changes are ticked; else celebrate"
}

Reply:

{
 "task": "pack",
 "verdict": "celebrate",
 "verdict_reason": "No worry was noted and only 1 change is ticked, so this is a celebrate.",
 "job_title": "Big sister and Chief Singer",
 "greeting": "Dear Ruby,",
 "opening": "Big news! You are being promoted to big sister.",
 "offer": "We are pleased to offer you the job of big sister to the baby, because you love singing.",
 "start_line": "Your job starts when the baby arrives, in a few months.",
 "duties": [
  {
   "n": 1,
   "duty": "Pass the towel to a grown-up at the baby's bath time",
   "how": "You bring the towel to a grown-up, so it is ready when the baby needs it."
  },
  {
   "n": 2,
   "duty": "Sing a song to the baby",
   "how": "You sing softly near the baby, so the baby hears your gentle voice."
  },
  {
   "n": 3,
   "duty": "Pick a soft toy to show the baby",
   "how": "You choose a toy you like and show it to the baby, so the baby sees something fun."
  }
 ],
 "stays_same": [
  {
   "n": 1,
   "line": "We love you just as much as ever."
  },
  {
   "n": 2,
   "line": "You can tell us any feeling, even cross or sad ones."
  }
 ],
 "reassurance": "Any feeling about the baby is fine, even cross or sad ones, and you can always tell Mama and Papa.",
 "signoff": "With love, Mama and Papa.",
 "grown_up_note": "Let Ruby sign or draw on the letter and pin it up. Stay close for every duty near the baby."
}

Theo, 5, three changes at once - steady anchors

Input:

{
 "task": "pack",
 "child": "Theo",
 "page_facts": "child | Theo | age 5 | becoming: big brother\nbaby | called: Pip | arrival: in the next few weeks\nsigned_by | Mum\nloves | dinosaurs, drawing and helping\nduty_1 | Welcome-card artist | Draw a welcome picture for the baby\nduty_2 | Nappy fetcher | Fetch a clean nappy when a grown-up asks\nduty_3 | Animal-noise expert | Show the baby animal pictures and make the noises\nduty_4 | Bag packer | Help pack the changing bag before an outing\nchanges | 3 | a new room or sharing a room; starting nursery or school; a relative coming to stay to help\nstays_1 | we love you just as much as ever\nstays_2 | you still get time with just you and a grown-up\nstays_3 | your special toys stay yours\nworry | none noted\ngrown_ups_only | lifting or carrying the baby; feeding the baby; bath water and bathing; anything in the cot or crib; looking after the baby alone\npage_verdict | steady_anchors\nverdict_rule | reassure_first when a worry is noted; else steady_anchors when 2 or more changes are ticked; else celebrate"
}

Reply:

{
 "task": "pack",
 "verdict": "steady_anchors",
 "verdict_reason": "No worry was noted, and 3 changes are ticked, so steady anchors was chosen.",
 "job_title": "Big brother and Chief Dinosaur",
 "greeting": "Dear Theo,",
 "opening": "We have big news for you: you are being promoted to big brother, and we could not be more proud.",
 "offer": "We are pleased to offer you the job of big brother to Pip, because you love helping.",
 "start_line": "Your job starts when Pip arrives, in the next few weeks.",
 "duties": [
  {
   "n": 1,
   "duty": "Draw a welcome picture for the baby",
   "how": "Pick happy colours and draw a picture to welcome the baby."
  },
  {
   "n": 2,
   "duty": "Fetch a clean nappy when a grown-up asks",
   "how": "When asked, bring a clean nappy to the grown-up helping the baby."
  },
  {
   "n": 3,
   "duty": "Show the baby animal pictures and make the noises",
   "how": "Point to each animal and make its sound to make the baby smile."
  },
  {
   "n": 4,
   "duty": "Help pack the changing bag before an outing",
   "how": "Help put things into the bag so everything is ready before you go out."
  }
 ],
 "stays_same": [
  {
   "n": 1,
   "line": "We love you just as much as ever."
  },
  {
   "n": 2,
   "line": "You still get time with just you and a grown-up."
  },
  {
   "n": 3,
   "line": "Your special toys stay yours."
  }
 ],
 "reassurance": "Some things are changing: a new room or sharing a room, starting nursery or school, and a relative coming to stay to help. The things that stay the same for you, stay the same.",
 "signoff": "With love, Mum.",
 "grown_up_note": "Whenever a change happens, read the things that stay the same to Theo again so it feels steady. Stay close for every duty near the baby."
}

Ada, 7, a worry about time together, the baby already here - reassure first

Input:

{
 "task": "pack",
 "child": "Ada",
 "page_facts": "child | Ada | age 7 | becoming: big sibling\nbaby | called: Juniper | arrival: already here\nsigned_by | Dad and Papa\nloves | reading, football and making lists\nduty_1 | Bag packer | Help pack the changing bag before an outing\nduty_2 | Story shower | Show the baby a picture book and say what you see\nduty_3 | News reporter | Draw or write the baby's first family newsletter\nduty_4 | Room guide | Tell the baby the names of things around the room\nduty_5 | Quiet-voice captain | Remind everyone to use quiet voices while the baby sleeps\nchanges | 1 | a grown-up going back to work\nstays_1 | you still get time with just you and a grown-up\nstays_2 | you can tell us any feeling, even cross or sad ones\nstays_3 | our bedtime story together\nworry | keeps asking whether we will still have time to read together\ngrown_ups_only | lifting or carrying the baby; feeding the baby; bath water and bathing; anything in the cot or crib; looking after the baby alone\npage_verdict | reassure_first\nverdict_rule | reassure_first when a worry is noted; else steady_anchors when 2 or more changes are ticked; else celebrate"
}

Reply:

{
 "task": "pack",
 "verdict": "reassure_first",
 "verdict_reason": "A worry was noted, so reassure first came first in the order.",
 "job_title": "Big sibling and Chief Reader",
 "greeting": "Dear Ada,",
 "opening": "We know you have been wondering whether we will still have time to read together. And the answer is right here in this letter.",
 "offer": "We are pleased to offer you the job of big sibling to Juniper, because you love reading.",
 "start_line": "Your job starts now, because Juniper is already here.",
 "duties": [
  {
   "n": 1,
   "duty": "Help pack the changing bag before an outing",
   "how": "Help pack soft things into the bag so you are ready to go out."
  },
  {
   "n": 2,
   "duty": "Show the baby a picture book and say what you see",
   "how": "Open the book near the baby and point to pictures while you talk about what you see."
  },
  {
   "n": 3,
   "duty": "Draw or write the baby's first family newsletter",
   "how": "Drawing or writing tells your family what is happening with the baby."
  },
  {
   "n": 4,
   "duty": "Tell the baby the names of things around the room",
   "how": "Point to things around the room and say their names out loud for the baby."
  },
  {
   "n": 5,
   "duty": "Remind everyone to use quiet voices while the baby sleeps",
   "how": "Use a soft voice and gently remind family members while the baby is sleeping."
  }
 ],
 "stays_same": [
  {
   "n": 1,
   "line": "You still get time with just you and a grown-up."
  },
  {
   "n": 2,
   "line": "You can tell us any feeling, even cross or sad ones."
  },
  {
   "n": 3,
   "line": "You still have our bedtime story together."
  }
 ],
 "reassurance": "Yes, you will still have time to read together, with our bedtime story staying just the same.",
 "signoff": "With love, Dad and Papa.",
 "grown_up_note": "Read this letter together at a calm moment and let Ada answer back. Stay close for every duty near the baby."
}

Build the input yourself

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

const K = PromoKit;
const built = K.buildInput({ child: "Ruby", age: 3, role: "sister", baby: "", arrival: "months", signed: "Mama and Papa",
  loves: "singing, teddies and splashing in puddles", changes: ["bed"], stays: ["love", "feelings"], worry: "" });
built.duties.map(d => d.text);  // the page's picks for age 3, loves first
built.verdict;                   // "celebrate" - no worry and only 1 change
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).notes                 // the page's re-check of the reply
// K.md(built, reply)                          // the letter 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://promoted-to-big.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":"promoted-to-big"}' | 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": "pack", "child": "Ruby", "page_facts": "child | Ruby | age 3 | becoming: big sister\n..."} - 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 task and the input: a retry with the same key never bills twice. The page uses promoted-to-big:<task>:<inputHash>:a<attempt> (the one task is pack), 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="promoted-to-big:pack:$(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: promoted-to-big:pack:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json