← Raise a Glass
API
Tokens

Drive Raise a Glass from your own code

Both metered lanes are available over HTTP. write takes the occasion, who is at the table, a tone, a target length and a few true details, and returns ready (a toast in five beats: open, story, bridge, thanks, raise) or needs-details (questions to answer first). tune takes a draft split into numbered sentences and returns ready, trim or rework, with every cut and edit itemised and the tuned toast in five beats. A natural use is a family group-chat bot that collects a line from each person during November and drafts the toast the night before.

The division of labour first: the page owns the clock, the flags and the cake; the model writes the words; the page re-checks the reply. The detail reader, the draft splitter and the clipping come from toastkit.js, which runs in node as well as in the browser. Speaking time is never asked of the model - ToastKit.secs(words) estimates it at 130 words a minute, and ToastKit.targetWords(seconds) turns a 30, 45, 60 or 90 second target into a word budget. ToastKit.check holds each reply to the input: five beats in order, ids that exist, cut sentences really gone from the toast, length against the target, and no capitalised name, number or pronoun that the input does not hold.

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":"raise-a-glass"}), 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, target_seconds) 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: both lanes are metered and need 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 verdicts

Every run sends task: write or tune. A missing or unknown task becomes tune when a draft is present, otherwise write. Verdicts are decided by ordered, non-overlapping rules - the first that applies wins:

TaskOrderVerdictWhen
write1needs-detailsFewer than two usable details (a specific thing someone did, said, made or brought, a moment, a first, a reason to thank them). No beats; asks holds two or three questions.
write2readyOtherwise: five beats within 15% of target_words.
tune1reworkA sentence teases someone about body, weight, looks, age, money, work troubles, love life, divorce, religion, politics, health or drinking, or touches avoid - or no sentence holds a specific detail.
tune2trimMore than 15% over target_words, or a sentence apologises for the toast, is an inside joke, repeats itself or lists names with no reasons.
tune3readyOtherwise. No notes; the draft's sentences come back unchanged in five beats.

The declared input schema carries scalars only, so the array-valued fields (details, draft, page_flags) travel JSON-encoded as strings (ToastKit.toWire does this). Every value is a string.

Input fields

FieldTypeNotes
taskstringwrite or tune. Required.
occasionstringAs typed - "Thanksgiving dinner", "Friendsgiving". Up to 80 characters.
speaker, tablestringWho gives the toast; the names at the table, commas (up to 24). Both may be empty.
tonestringwarm, funny, heartfelt or short-and-sweet.
target_seconds, target_wordsstring30, 45, 60 or 90; the word budget at 130 words a minute (65, 98, 130, 195). target_seconds is required.
detailsstring (JSON)write: [{id, who, text}] - ids D1.., up to 12 details of up to 240 characters; who from a "Name:" prefix.
draft, draft_words, page_flagsstring (JSON), string, string (JSON)tune: [{id, text, words}] - ids S1.., up to 40 sentences; the total words; [{ref, flag}] with flags apology, inside-joke, tease:<word>, avoid:<word>, long - the page's guesses, which the model judges for itself.
avoidstringTopics to stay away from, commas; may be empty.
clip_note, retry_notestringWhat the page cut, when it cut something; and only on a reformat retry, what was wrong.

The reply

The job's output.output is a string holding one JSON object: task, verdict, title, summary, beats ([{kind, text, uses}] - exactly five, kind in the order open, story, bridge, thanks, raise, uses the detail or sentence ids it draws on; [] for needs-details), notes (tune: [{ref, action, why, edit}], action cut or edit; write: []) and asks (needs-details only). Parse with ToastKit.parseReply, then normalize(reply, task), then check(reply, form), which returns the page's notes.

Worked examples

Replies produced against the app's prompt for the five sample tables (made-up people; long fields shortened; the full replies ship in example-result.js). Together they cover every verdict of both lanes.

write - Thanksgiving dinner, four true details, 60 s: ready

Input:

{
 "task": "write",
 "occasion": "Thanksgiving dinner",
 "speaker": "Maya",
 "table": "Maya, Grandpa Lou, Priya, Sam, Theo",
 "tone": "warm",
 "target_seconds": "60",
 "target_words": "130",
 "details": "[{\"id\":\"D1\",\"who\":\"Grandpa Lou\",\"text\":\"drove up through the snow to be here\"},{\"id\":\"D2\",\"who\":\"Priya\",\"text\":\"baked her first ever pie for tonight - lopsided, and proud of it\"},{\"id\":\"D3\",\"who\":\"Sam\",\"text\":\"started as a volunteer firefighter this spring\"},{\"id\":\"D4\",\"who\":\"Theo\",\"text\":\"drew a name card for every seat at the table\"}]",
 "avoid": ""
}

Reply:

{
 "task": "write",
 "verdict": "ready",
 "title": "A Thanksgiving toast for this table",
 "summary": "This gives you a five-beat toast built on four specific details: Grandpa Lou driving through the snow, Priya baking her first pie, Sam starting as a volunteer firefighter, and Theo making name cards for every seat. It begins by gathering the table, centers on Grandpa Lou's drive through the snow, thanks Priya, Sam, and Theo by name, and ends with everyone raising a glass. There are enough specific details here to build the whole toast without guessing at anything.",
 "beats": [
  {
   "kind": "open",
   "text": "We're gathered around this table tonight for Thanksgiving dinner, and I'm grateful every one of you is here with us.",
   "uses": []
  },
  {
   "kind": "story",
   "text": "Grandpa Lou, you drove up through the snow just to be here with us tonight.",
   "uses": [
    "D1"
   ]
  },
  {
   "kind": "bridge",
   "text": "That's what this table is built on: people who show up for each other, through the snow or anything else.",
   "uses": [
    "D1"
   ]
  },
  {
   "kind": "thanks",
   "text": "Priya, thank you for baking your first ever pie for tonight, lopsided and proud of it. Sam, thank you for starting as a volunteer firefighter this spring. And Theo, thank you for drawing a name card for every seat at this table.",
   "uses": [
    "D2",
    "D3",
    "D4"
   ]
  },
  {
   "kind": "raise",
   "text": "So tonight, let's raise a glass together. To this table, and to everyone who shows up for it.",
   "uses": []
  }
 ],
 "notes": [],
 "asks": []
}

write - Friendsgiving, "everyone is great" and logistics: needs-details

Input:

{
 "task": "write",
 "occasion": "Friendsgiving",
 "speaker": "",
 "table": "Jess, Omar, Kai, Lena",
 "tone": "funny",
 "target_seconds": "30",
 "target_words": "65",
 "details": "[{\"id\":\"D1\",\"who\":\"\",\"text\":\"everyone is great\"},{\"id\":\"D2\",\"who\":\"\",\"text\":\"thanks for coming\"},{\"id\":\"D3\",\"who\":\"\",\"text\":\"dinner at 7\"},{\"id\":\"D4\",\"who\":\"\",\"text\":\"Omar\"}]",
 "avoid": ""
}

Reply:

{
 "task": "write",
 "verdict": "needs-details",
 "title": "A toast for Friendsgiving",
 "summary": "This toast isn't ready yet because none of the details given are specific enough to build a story or thanks around. Right now there's a general compliment, a thank-you with no reason, a dinner time, and a bare name. A few concrete moments or reasons would give the toast something to say.",
 "beats": [],
 "notes": [],
 "asks": [
  "What's something specific someone made, brought, or did that you could mention?",
  "Is there a particular moment you'd like the toast to picture?",
  "Who do you most want to thank, and what's the specific reason?"
 ]
}

tune - a kind holiday-lunch draft, on time for 45 s: ready

Input:

{
 "task": "tune",
 "occasion": "our family's holiday lunch",
 "speaker": "Mira",
 "table": "Nana Rose, Dev, Mira, Jun",
 "tone": "heartfelt",
 "target_seconds": "45",
 "target_words": "98",
 "draft": "[{\"id\":\"S1\",\"text\":\"Before we eat, I want to say something.\",\"words\":8},{\"id\":\"S2\",\"text\":\"This year Nana Rose taught me to make the dumplings we are about to eat.\",\"words\":15},{\"id\":\"S3\",\"text\":\"They came out in every shape you can imagine, and Nana said every one of them was perfect.\",\"words\":18},{\"id\":\"S4\",\"text\":\"That is what this table does - it makes r ... (709 characters)",
 "draft_words": "90",
 "page_flags": "[]",
 "avoid": ""
}

Reply:

{
 "task": "tune",
 "verdict": "ready",
 "title": "To every shape at this table",
 "summary": "Your draft already lands: the story about learning Nana Rose's dumplings, in every shape, carries into thanks that name Dev and Jun, and the close already raises a glass before its 'To' line. Nothing here needs cutting or rewording, so the beats below are your own sentences, grouped in order.",
 "beats": [
  {
   "kind": "open",
   "text": "Before we eat, I want to say something.",
   "uses": [
    "S1"
   ]
  },
  {
   "kind": "story",
   "text": "This year Nana Rose taught me to make the dumplings we are about to eat. They came out in every shape you can imagine, and Nana said every one of them was perfect.",
   "uses": [
    "S2",
    "S3"
   ]
  },
  {
   "kind": "bridge",
   "text": "That is what this table does - it makes room for every shape.",
   "uses": [
    "S4"
   ]
  },
  {
   "kind": "thanks",
   "text": "Thank you, Nana, for the recipe and the patience. Thank you, Dev and Jun, for driving through the night to be here.",
   "uses": [
    "S5",
    "S6"
   ]
  },
  {
   "kind": "raise",
   "text": "So please raise a glass. To Nana Rose, and to every shape at this table!",
   "uses": [
    "S7",
    "S8"
   ]
  }
 ],
 "notes": [],
 "asks": []
}

tune - a Friendsgiving draft, long, with an apology and an inside joke: trim

Input:

{
 "task": "tune",
 "occasion": "Friendsgiving",
 "speaker": "",
 "table": "Bea, Carlos, Dana, Eli, Fern",
 "tone": "funny",
 "target_seconds": "30",
 "target_words": "65",
 "draft": "[{\"id\":\"S1\",\"text\":\"Okay, I'm not good at speeches, so bear with me.\",\"words\":10},{\"id\":\"S2\",\"text\":\"I just want to say a few words before the food gets cold.\",\"words\":13},{\"id\":\"S3\",\"text\":\"Bea, you organised this whole thing in a group chat of forty-three messages and somehow nobody brought two salads.\",\"words\":20},{\"id\":\"S4\",\"text\":\"Carlos, you carved the ... (928 characters)",
 "draft_words": "118",
 "page_flags": "[{\"ref\":\"S1\",\"flag\":\"apology\"},{\"ref\":\"S6\",\"flag\":\"inside-joke\"}]",
 "avoid": ""
}

Reply:

{
 "task": "tune",
 "verdict": "trim",
 "title": "A toast for Bea's Friendsgiving",
 "summary": "This adds a short opening line and a short bridge line, since the draft had nothing to open on or to turn the story into meaning, and keeps everything else the draft already does well: Bea's chaotic group chat, the thank-yous for Carlos, Dana, Eli and Fern, and the closing toast to Bea's group chat and everyone at the table. It also drops the opening apology, the stalling line about the food, an aside not everyone at the table would follow, the general thank-you line now covered by name, and the trailing sign-off, leaving a toast that's short and easy to say.",
 "beats": [
  {
   "kind": "open",
   "text": "Happy Friendsgiving, everyone.",
   "uses": []
  },
  {
   "kind": "story",
   "text": "Bea, you organised this whole thing in a group chat of forty-three messages and somehow nobody brought two salads.",
   "uses": [
    "S3"
   ]
  },
  {
   "kind": "bridge",
   "text": "That's this table for you.",
   "uses": []
  },
  {
   "kind": "thanks",
   "text": "Carlos, you carved the bird like a surgeon. Dana, Eli and Fern, you brought the folding chairs, the playlist and the pie.",
   "uses": [
    "S4",
    "S5"
   ]
  },
  {
   "kind": "raise",
   "text": "Raise your glasses. To Bea's group chat and to all of us!",
   "uses": [
    "S9",
    "S10"
   ]
  }
 ],
 "notes": [
  {
   "ref": "S1",
   "action": "cut",
   "why": "it apologises for the toast, which isn't needed",
   "edit": ""
  },
  {
   "ref": "S2",
   "action": "cut",
   "why": "a stalling line with no detail to keep",
   "edit": ""
  },
  {
   "ref": "S6",
   "action": "cut",
   "why": "an aside the whole table wouldn't get",
   "edit": ""
  },
  "... (5 in all)"
 ],
 "asks": []
}

tune - a Thanksgiving draft that teases about a diet and a vote: rework

Input:

{
 "task": "tune",
 "occasion": "Thanksgiving dinner",
 "speaker": "",
 "table": "Uncle Ray, Aunt June, Kim, Leo",
 "tone": "funny",
 "target_seconds": "45",
 "target_words": "98",
 "draft": "[{\"id\":\"S1\",\"text\":\"Happy Thanksgiving, everybody.\",\"words\":3},{\"id\":\"S2\",\"text\":\"Uncle Ray finally fits in his chair after that diet, so that's something to be thankful for.\",\"words\":17},{\"id\":\"S3\",\"text\":\"Aunt June made the stuffing from Grandma's recipe again, and it tasted like every Thanksgiving I remember.\",\"words\":17},{\"id\":\"S4\",\"text\":\"And let's be h ... (545 characters)",
 "draft_words": "61",
 "page_flags": "[{\"ref\":\"S2\",\"flag\":\"tease:finally fits\"},{\"ref\":\"S4\",\"flag\":\"tease:voted\"}]",
 "avoid": "politics"
}

Reply:

{
 "task": "tune",
 "verdict": "rework",
 "title": "A toast for Thanksgiving dinner",
 "summary": "This toast keeps Aunt June's stuffing as its story and turns Kim's table-setting into a direct thank-you; since the draft had no line turning that story into what it means for the table, a short one was added before the thanks. Two lines had to go: the one about Uncle Ray's chair teased him, and the one about Leo's vote touched a topic you asked to avoid. Because of that, this toast needed more than small changes to be ready.",
 "beats": [
  {
   "kind": "open",
   "text": "Happy Thanksgiving, everybody.",
   "uses": [
    "S1"
   ]
  },
  {
   "kind": "story",
   "text": "Aunt June made the stuffing from Grandma's recipe again, and it tasted like every Thanksgiving I remember.",
   "uses": [
    "S3"
   ]
  },
  {
   "kind": "bridge",
   "text": "That's what this table gives us.",
   "uses": []
  },
  {
   "kind": "thanks",
   "text": "Thank you, Kim, for setting the table with the good plates.",
   "uses": [
    "S5"
   ]
  },
  {
   "kind": "raise",
   "text": "So let's raise a glass. To family!",
   "uses": [
    "S6"
   ]
  }
 ],
 "notes": [
  {
   "ref": "S2",
   "action": "cut",
   "why": "This teases Uncle Ray about his weight.",
   "edit": ""
  },
  {
   "ref": "S4",
   "action": "cut",
   "why": "This brings up politics, a topic you asked to avoid.",
   "edit": ""
  },
  {
   "ref": "S5",
   "action": "edit",
   "why": "Turns the detail into a direct thank-you.",
   "edit": "Thank you, Kim, for setting the table with the good plates."
  }
 ],
 "asks": []
}

Build the input yourself

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

const K = ToastKit;
const form = K.form({ lane: "tune", occasion: "Thanksgiving dinner", table: "Ray, June, Kim", length: "45", avoid: "politics",
  draft: "Happy Thanksgiving, everybody. Kim set the table with the good plates. To family!" });
console.log(K.flags(form), K.lean(form), K.draft(form).secs);    // the flags, the page's lean, the estimated seconds
const wire = K.toWire(K.buildInput("tune", form).input);          // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output), "tune");
// const { notes } = K.check(reply, form);                         // the page's re-check of the reply
// K.secs(K.beatWords(reply))                                      // the tuned toast's estimated seconds

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://raise-a-glass.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":"raise-a-glass"}' | 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": "write", "occasion": "Thanksgiving dinner", "speaker": "Maya", "tone": "warm", "target_seconds": "60", "target_words": "130", "details": "[{\"id\":\"D1\",\"who\":\"Grandpa Lou\",\"text\":\"drove up through the snow to be here\"},{\"id\":\"D2\",\"who\":\"Priya\",\"text\":\"baked a pie for the first time - lopsided, and proud of it\"}, ...]"}
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 raise-a-glass:<task>:<inputHash>:a<attempt> (the lanes are write and tune), 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="raise-a-glass:write:$(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: raise-a-glass:write:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json