← RSVP By
RSVP By API
Tokens

Drive RSVP By from your own code

The one metered read is available over HTTP: give it a party's name, occasion and vibe, the twelve detail stamps (any of them blank) and free notes, and it returns a verdict, the clashes to fix first, one guest question per blank stamp with what to add, the invite written in the vibe (headline, blurb, detail lines, reply line), a day-before reminder text and answers to the questions guests are likely to send. A natural use is an event or group-chat tool that wants a ready-to-paste invite and a list of what is still missing.

The division of labour first: the page owns the sheet, the dates and the clash check; the model writes; the page re-checks the reply. The stamps, the weekday arithmetic, the hard clashes (an end before the start, a reply-by after the party, a weekday the date doesn't have) and the verdict (by the same ordered rules the model gets) come from invitekit.js, which runs in node as well as in the browser. Its check function holds each reply to the sheet: one gap entry per blank stamp and none invented, every clash answered, no weekday the dates don't have, no line for a blank stamp, no internal field names in prose. Dates and times reach the model already written out, so it never computes a weekday.

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":"rsvp-by"}), 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 such as task 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 invite 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

Every run sends task: invite - there is one lane. The verdict is decided by three ordered, non-overlapping rules; the first that matches wins:

OrderVerdictWhen
1clashpage_clashes is not empty, or two facts in the input cannot both be true (a stamp against the notes, or two stamps).
2gapsOtherwise, an essential stamp (Date, Start time, Where, RSVP by) is blank, or more than three of the other eight are.
3readyEverything else.

The declared input schema carries scalars only, so array-valued fields travel JSON-encoded as strings (InviteKit.toWire does this). Every value is a string; a blank stamp is an empty string.

Input fields

FieldTypeNotes
taskstringinvite.
namestringThe party in the host's words, up to 120 characters.
occasionstringOne of birthday, Halloween party, Friendsgiving, watch party, game night, housewarming, dinner party, holiday party, something else, or empty.
vibestringOne of cozy, chaotic fun, low-key, dressy, wholesome, or empty.
date, rsvpstringWritten out with the weekday, e.g. Saturday 31 October 2026 (the page converts its ISO dates).
start, endstringWritten out, e.g. 8:00 pm, noon. An end earlier than the start and before 6 am means after midnight.
place, access, host, food, bring, dressstringFree text, up to 200 characters each: where, getting in, hosted by, food and drinks, bring, wear.
plusstringwelcome, ask first, not this time, or empty.
kidsstringwelcome, ask first, adults only, or empty.
notesstringFree notes for guests; past 1,500 characters the middle is cut with a marker.
page_missingstring (JSON)Array of the blank stamps' labels in sheet order: Date, Start time, Wraps up, Where, Getting in, Hosted by, Food and drinks, Bring, Wear, Plus-ones, Kids, RSVP by.
page_clashesstring (JSON)Array of the hard clashes the page found, as sentences.
page_leanstringThe page's verdict from the stamps alone, by the rules above.
page_flagsstring (JSON)Array of the page's warnings.
retry_notestringOnly on a reformat retry.

The reply

The job's output.output is a string holding one JSON object: task, verdict, title, summary, clashes ([{clash, fix}], empty unless the verdict is clash), gaps ([{detail, question, fill}], one per label in page_missing, in order), invite ({headline, blurb, details: [{label, text}], rsvp}), reminder and faq ([{q, a}], 2-5; an answer the input cannot give starts with "Not on the invite yet -"). Parse it with InviteKit.parseReply, then normalize(reply), then check(reply, form), which returns {notes, lean}.

Worked examples

Replies produced against the app's prompt for the four sample parties (made-up parties, names and addresses; long fields and lists shortened; the full replies ship in example-result.js). Together they cover every verdict, including one where the reply finds a clash in the notes that the sheet alone cannot see.

costume party - ready

Input:

{
 "task": "invite",
 "name": "Haunted house party at ours",
 "occasion": "Halloween party",
 "vibe": "chaotic fun",
 "date": "Saturday 31 October 2026",
 "start": "8:00 pm",
 "end": "1:00 am",
 "place": "22 Larch Road, top floor flat",
 "access": "street parking after 6 pm; ring the bell marked Top Flat",
 "host": "Dami and Kit",
 "food": "pizza at 9, plus a punch bowl and an alcohol-free punch",
 "bring": "a snack or a drink if you like",
 "dress": "costumes encouraged - prize for the best one",
 "plus": "welcome",
 "kids": "adults only",
 "rsvp": "Tuesday 27 October 2026",
 "notes": "We have a cat who hides upstairs - please keep the bedroom doors shut. Costume contest at 11.",
 "page_missing": "[]",
 "page_clashes": "[]",
 "page_lean": "ready",
 "page_flags": "[]"
}

Reply:

{
 "task": "invite",
 "verdict": "ready",
 "title": "Haunted House Party, Ready to Go",
 "summary": "Your sheet is ready - every stamp guests need is filled in and nothing clashes. Give the costume and cat notes one more glance, then send it out so people can plan their outfits in time.",
 "clashes": [],
 "gaps": [],
 "invite": {
  "headline": "Our Haunted House Party Is ON! 🎃",
  "blurb": "It's happening: our Haunted House Party, on Halloween night itself. Dami and Kit are opening up the top floor flat for a full costume takeover, with a costume contest at 11 and a prize for the best look. Come hungry, come costumed, and come ready for chaos.",
  "details": [
   {
    "label": "When",
    "text": "Sat 31 Oct, 8:00 pm - 1:00 am"
   },
   {
    "label": "Where",
    "text": "22 Larch Road, top floor flat - street parking after 6 pm, ring the bell marked Top Flat"
   },
   {
    "label": "Hosted by",
    "text": "Dami and Kit"
   },
   "... (9 in all)"
  ],
  "rsvp": "RSVP to Dami and Kit by Tuesday 27 Oct!"
 },
 "reminder": "Tomorrow's the night - our Haunted House Party kicks off at 8:00 pm at 22 Larch Road, top floor flat. Dust off those costumes, there's a prize for the best one!",
 "faq": [
  {
   "q": "Do I need a costume?",
   "a": "Costumes are encouraged, and there's a prize for the best one - the costume contest is at 11."
  },
  {
   "q": "What time does it wrap up?",
   "a": "The party runs until 1:00 am."
  },
  "... (5 in all)"
 ]
}

Friendsgiving - gaps

Input:

{
 "task": "invite",
 "name": "Friendsgiving at our flat",
 "occasion": "Friendsgiving",
 "vibe": "cozy",
 "date": "Saturday 21 November 2026",
 "start": "4:00 pm",
 "end": "",
 "place": "our flat",
 "access": "",
 "host": "",
 "food": "turkey, gravy and pie",
 "bring": "a side dish",
 "dress": "",
 "plus": "",
 "kids": "",
 "rsvp": "",
 "notes": "We'll go round the table and each say one thing we're grateful for.",
 "page_missing": "[\"Wraps up\",\"Getting in\",\"Hosted by\",\"Wear\",\"Plus-ones\",\"Kids\",\"RSVP by\"]",
 "page_clashes": "[]",
 "page_lean": "gaps",
 "page_flags": "[]"
}

Reply:

{
 "task": "invite",
 "verdict": "gaps",
 "title": "Cozy Friendsgiving, a few blanks to fill",
 "summary": "Your Friendsgiving invite is close, but it still has several blank stamps - including the reply-by stamp - so this reads as gaps rather than ready. Fill in when you need replies, plus the wrap-up time, host, dress, plus-ones, kids and getting-in details before you send it out. The core facts - date, time, place and food - are already set.",
 "clashes": [],
 "gaps": [
  {
   "detail": "Wraps up",
   "question": "What time should we plan to head out?",
   "fill": "Add an end time so guests know when the evening wraps up."
  },
  {
   "detail": "Getting in",
   "question": "Is there parking, or how do we get in - which floor or door?",
   "fill": "Add a note on parking, the door or the floor to help guests get in."
  },
  "... (7 in all)"
 ],
 "invite": {
  "headline": "A Cozy Friendsgiving at Our Flat",
  "blurb": "You're invited to Friendsgiving at our flat - a cozy, unhurried evening of turkey, gravy and pie with the people we're thankful for. We'll go round the table and each share one thing we're grateful for, so come with a thought ready.",
  "details": [
   {
    "label": "When",
    "text": "Saturday 21 November 2026 at 4:00 pm"
   },
   {
    "label": "Where",
    "text": "Our flat"
   },
   {
    "label": "Food and drinks",
    "text": "Turkey, gravy and pie"
   },
   "... (4 in all)"
  ],
  "rsvp": "Let us know soon if you can make it!"
 },
 "reminder": "See you tomorrow at 4:00 pm at our flat - don't forget your side dish!",
 "faq": [
  {
   "q": "What time should I show up?",
   "a": "4:00 pm on Saturday 21 November 2026, at our flat."
  },
  {
   "q": "What should I bring?",
   "a": "A side dish - turkey, gravy and pie are already taken care of."
  },
  "... (5 in all)"
 ]
}

birthday dinner - clash on the sheet

Input:

{
 "task": "invite",
 "name": "Jess turns 40 - Saturday dinner",
 "occasion": "birthday",
 "vibe": "dressy",
 "date": "Friday 6 November 2026",
 "start": "7:30 pm",
 "end": "11:00 pm",
 "place": "the back room at Quillberry Kitchen, 5 Mill Street",
 "access": "two minutes' walk from the station",
 "host": "Ana",
 "food": "set menu; everyone pays for their own",
 "bring": "nothing, just yourselves",
 "dress": "smart - jackets optional",
 "plus": "ask first",
 "kids": "adults only",
 "rsvp": "Monday 9 November 2026",
 "notes": "It's a surprise - please don't mention it to Jess. The restaurant needs final numbers from me.",
 "page_missing": "[]",
 "page_clashes": "[\"Replies are due Monday 9 November 2026, after the party on Friday 6 November 2026.\",\"Your wording says Saturday, but 6 November 2026 is a Friday.\"]",
 "page_lean": "clash",
 "page_flags": "[]"
}

Reply:

{
 "task": "invite",
 "verdict": "clash",
 "title": "Jess's 40th dinner, two date clashes",
 "summary": "Your sheet is a clash: the reply-by date lands three days after the party itself, and the party's name calls it a Saturday while the date stamp says Friday 6 November 2026. Settle which date is right in each case - move the reply-by earlier and confirm the correct weekday - before you send this to guests.",
 "clashes": [
  {
   "clash": "The reply-by date (Monday 9 November 2026) comes three days after the party itself (Friday 6 November 2026), so guests would be asked to reply after it's already happened.",
   "fix": "Settle on which date is accurate, then move the reply-by date earlier than the party or adjust the party date itself, whichever is wrong."
  },
  {
   "clash": "The party's name calls it a Saturday dinner, but the date stamp gives Friday 6 November 2026 - the two don't agree on the day of the week.",
   "fix": "Figure out which day is correct and update the other one to match - either the wording in the party's name or the date stamp, not both."
  }
 ],
 "gaps": [],
 "invite": {
  "headline": "A Surprise Dinner for Jess's 40th",
  "blurb": "You're invited to a surprise dinner celebrating Jess turning 40, hosted by Ana. It's a polished evening out - and still a secret, so please don't breathe a word to Jess beforehand.",
  "details": [
   {
    "label": "When",
    "text": "Friday 6 November 2026, 7:30 pm to 11:00 pm."
   },
   {
    "label": "Where",
    "text": "The back room at Quillberry Kitchen, 5 Mill Street - two minutes' walk from the station."
   },
   {
    "label": "Hosted by",
    "text": "Ana."
   },
   "... (8 in all)"
  ],
  "rsvp": "Let Ana know as soon as you can, so they can confirm final numbers with the restaurant."
 },
 "reminder": "Tomorrow's the night for Jess's surprise 40th, 7:30 pm at the back room at Quillberry Kitchen, 5 Mill Street. It's dressy - smart, jackets optional - and still a surprise, so not a word to Jess!",
 "faq": [
  {
   "q": "Is the party on Friday or Saturday?",
   "a": "Not settled yet - the party's name calls it a Saturday dinner, but the date on the sheet says Friday 6 November 2026, so Ana still needs to confirm which one's right."
  },
  {
   "q": "When's the latest I can RSVP?",
   "a": "Not settled yet - the reply-by date on the sheet falls after the party date, so Ana needs to set a reply-by date that comes before the party."
  },
  "... (5 in all)"
 ]
}

watch party - the notes clash with a stamp

Input:

{
 "task": "invite",
 "name": "Big game watch party in the basement",
 "occasion": "watch party",
 "vibe": "low-key",
 "date": "Friday 30 October 2026",
 "start": "7:00 pm",
 "end": "11:00 pm",
 "place": "Theo's basement, 9 Birch Court",
 "access": "use the side door, it's unlocked",
 "host": "Theo",
 "food": "wings and nachos",
 "bring": "BYOB - bring whatever you're drinking",
 "dress": "your team's colours",
 "plus": "welcome",
 "kids": "welcome",
 "rsvp": "Wednesday 28 October 2026",
 "notes": "Heads up: this is a dry house now, so no alcohol please. Kids can play upstairs.",
 "page_missing": "[]",
 "page_clashes": "[]",
 "page_lean": "ready",
 "page_flags": "[]"
}

Reply:

{
 "task": "invite",
 "verdict": "clash",
 "title": "Big Game Watch Party, drinks clash",
 "summary": "This comes out as a clash, not ready, because the bring stamp asks guests to bring their own drinks while your notes say the house is now dry - the two can't both be true. Decide which one stands and update the bring stamp or the note before you send anything. Everything else on the sheet is filled in and ready to go.",
 "clashes": [
  {
   "clash": "The bring stamp tells guests to bring their own drinks, but your notes say this is now a dry house with no alcohol allowed.",
   "fix": "Decide whether alcohol is allowed and change either the bring stamp or the note to match."
  }
 ],
 "gaps": [],
 "invite": {
  "headline": "Big Game Watch Party",
  "blurb": "It's watch party time in Theo's basement - a low-key night for the big game. Kids are welcome too.",
  "details": [
   {
    "label": "When",
    "text": "Fri 30 Oct, 7:00 pm - 11:00 pm"
   },
   {
    "label": "Where",
    "text": "Theo's basement, 9 Birch Court - use the side door, it's unlocked"
   },
   {
    "label": "Hosted by",
    "text": "Theo"
   },
   "... (8 in all)"
  ],
  "rsvp": "Let Theo know by Wed 28 Oct."
 },
 "reminder": "Game's on tomorrow at 7:00 pm - Theo's basement, 9 Birch Court. Use the side door, it's unlocked.",
 "faq": [
  {
   "q": "What should I bring?",
   "a": "Not settled yet - the sheet says both bring your own drinks and no alcohol in the house, so Theo needs to decide which one stands before anyone brings a drink."
  },
  {
   "q": "Is there food?",
   "a": "Yes - wings and nachos will be there."
  },
  "... (5 in all)"
 ]
}

Build the input yourself

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

const K = InviteKit;
const form = { name: "Friendsgiving at our flat", occasion: "Friendsgiving", vibe: "cozy", notes: "",
  date: "2026-11-21", start: "16:00", end: "", place: "our flat", access: "", host: "", food: "turkey and pie",
  bring: "a side dish", dress: "", plus: "", kids: "", rsvp: "" };
console.log(K.lean(form), K.clashes(form));               // the page's verdict and its hard clashes
const wire = K.toWire(K.buildInput(form).input);           // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output));
// const { notes } = K.check(reply, form);                 // the page's re-check of the reply
// K.ics({ form, res: reply })                             // a calendar file for the guests
// stamp ids: K.STAMPS.map(s => s.id)

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://rsvp-by.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":"rsvp-by"}' | 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": "invite", "name": "Haunted house party at ours", "occasion": "Halloween party", "vibe": "chaotic fun", "date": "Saturday 31 October 2026", "start": "8:00 pm", "end": "1:00 am", "place": "22 Larch Road, top floor flat", ..., "rsvp": "Tuesday 27 October 2026", "notes": "...", "page_missing": "[]", "page_clashes": "[]", "page_lean": "ready", "page_flags": "[]"}
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 rsvp-by:<task>:<inputHash>:a<attempt> (there is one lane, invite), 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="rsvp-by:invite:$(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: rsvp-by:invite:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json