← Attested at Home
Dictionary API
Tokens

Drive Attested at Home from your own code

The one metered task, compile, is available over HTTP. It takes a household's word notes - one word per line, numbered [1], [2] and so on, with the page's quick reading of each line - and returns a verdict on the dictionary (a slim pamphlet, wants citations, or ready for the press), one entry per word (a respelling, a part of speech, one or two senses, the quoted use with its speaker and time, and any origin the notes give), up to three word-making habits of the household, up to three questions for the household, a title and a short preface.

The division of labour first: the page owns the line reading, the attestation rule and the verdict rule; the model owns the entries, the habits and the questions; the page re-checks the reply. All of it comes from wordkit.js, which you can run yourself (see Build the input yourself). Attested at Home never corrects a word.

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":"attested-at-home"}), 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, count, words, prescan) 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: compiling a dictionary 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 statuses and the verdict

Every run sends task: compile; a missing or different one is still answered as compile. Each entry gets one status, checked in order: reconstructed if the line gives no meaning or is marked uncertain outside its quotes (a question mark, "not sure", "I think", "maybe", "something like", "we forget", "can't remember", "no idea", "sort of"); otherwise attested if a quoted use contains the headword; otherwise described. Each entry's pos is one of noun, verb, adjective, adverb, interjection, phrase or unknown.

The verdict is checked in order, first match wins: thin (shown as "a slim pamphlet") if there are fewer than 4 entries; otherwise uncited ("wants citations") if attested entries are fewer than half; otherwise ready ("ready for the press").

The input

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

FieldRequiredWhat it holds
taskyesAlways compile.
householdnoThe household's or dictionary's name, up to 40 characters. May be empty.
countyesHow many numbered words follow.
wordsyesThe notes, one word per line, each starting [n]. Up to 40 lines; a line over 280 characters keeps its start and end with [...] where the middle was cut.
prescanyesThe page's reading, one line per word: <n> | <headword> | <status> | quote: yes/no. The model keeps the headword spelling and applies the status rule itself.
clip_notenoWhat the page shortened, if anything.
retry_notenoSent only on the page's single reformat retry.

The reply

The reply is one JSON object in job.output.output. The page parses it with WordKit.parseReply and WordKit.normalize (a cut-off stream is closed by WordKit.closeJson and whatever parsed is shown).

{"task": "compile", "verdict": "thin | uncited | ready", "verdict_reason": "...", "title": "...", "preface": "...",
 "entries": [{"n": 1, "headword": "...", "say": "SNAK-oh", "pos": "noun | verb | adjective | adverb | interjection | phrase | unknown",
              "status": "attested | described | reconstructed", "senses": ["..."],
              "citation": {"quote": "...", "speaker": "...", "when": "..."}, "origin": "..."}],
 "patterns": [{"name": "...", "how": "...", "examples": ["...", "..."]}],
 "questions": ["..."]}
FieldWhat it holds
entriesOne per numbered line, same n and headword. say a hyphenated respelling with the stressed syllable in capitals; senses one or two definitions of at most 20 words; citation copied from the notes for an attested word, otherwise null; origin only when the notes give one, otherwise empty.
patternsZero to three word-making habits, each shown by two to four headwords.
questionsOne to three questions that each name a headword and ask for what its entry lacks.
title, preface"A Dictionary of" plus the household's name (or "A Household Dictionary"), and a two-sentence preface.

The page then checks the reply against the notes (WordKit.check): the verdict against the reply's own counts and the page's reading, one entry per word with the same spelling, known statuses, every attested word carrying its quote, quotes, speakers and times word for word from the notes, origins sharing words with the notes, habits shown by two headwords, questions naming a headword, no he or she for anyone, and no internal field name in the prose.

Worked examples, one per verdict

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

The Harbour Row flat - ready for the press (ready)

Input:

{
 "task": "compile",
 "household": "the Harbour Row flat",
 "count": "7",
 "words": "[1] blankie burrito - wrapping yourself in the sofa blanket so only your face shows. \"I'm in full blankie burrito, bring me tea\" (Mia, every Sunday)\n[2] snacko: any snack eaten standing at the open fridge. \"Just a quick snacko\" (Dad)\n[3] bedso = bedtime, said to the twins. \"Teeth, then bedso\" (Jonah)\n[4] the wobbles - the hour before dinner when everyone is hungry and cross. \"Careful, it's the wobbles\" (Mia)\n[5] glumph - the noise the old washing machine makes when it changes cycle. \"There goes the glumph\" (Ade, since we moved in)\n[6] crinkler - the TV remote, named after the crinkly plastic cover Gran put on it\n[7] flumpet - something to do with being tired? We forget who started it.",
 "prescan": "1 | blankie burrito | attested | quote: yes\n2 | snacko | attested | quote: yes\n3 | bedso | attested | quote: yes\n4 | the wobbles | attested | quote: yes\n5 | glumph | attested | quote: yes\n6 | crinkler | described | quote: no\n7 | flumpet | reconstructed | quote: no"
}

Reply:

{
 "task": "compile",
 "verdict": "ready",
 "verdict_reason": "Five of seven words have a quoted use.",
 "title": "A Dictionary of the Harbour Row flat",
 "preface": "This dictionary sets down the words one household has made for itself, each entry built only from what was written down about it. Read it the way you would read any family's private language, and add to it whenever a word earns its place.",
 "entries": [
  {
   "n": 1,
   "headword": "blankie burrito",
   "say": "BLAN-kee buh-REE-toh",
   "pos": "phrase",
   "status": "attested",
   "senses": [
    "Wrapping yourself in the sofa blanket so only your face shows"
   ],
   "citation": {
    "quote": "I'm in full blankie burrito, bring me tea",
    "speaker": "Mia",
    "when": "every Sunday"
   },
   "origin": ""
  },
  {
   "n": 2,
   "headword": "snacko",
   "say": "SNAK-oh",
   "pos": "noun",
   "status": "attested",
   "senses": [
    "Any snack eaten standing at the open fridge"
   ],
   "citation": {
    "quote": "Just a quick snacko",
    "speaker": "Dad",
    "when": ""
   },
   "origin": ""
  },
  {
   "n": 3,
   "headword": "bedso",
   "say": "BED-soh",
   "pos": "noun",
   "status": "attested",
   "senses": [
    "Bedtime, said to the twins"
   ],
   "citation": {
    "quote": "Teeth, then bedso",
    "speaker": "Jonah",
    "when": ""
   },
   "origin": ""
  },
  {
   "n": 4,
   "headword": "the wobbles",
   "say": "the WOB-uhlz",
   "pos": "phrase",
   "status": "attested",
   "senses": [
    "The hour before dinner when everyone is hungry and cross"
   ],
   "citation": {
    "quote": "Careful, it's the wobbles",
    "speaker": "Mia",
    "when": ""
   },
   "origin": ""
  },
  {
   "n": 5,
   "headword": "glumph",
   "say": "GLUMF",
   "pos": "noun",
   "status": "attested",
   "senses": [
    "The noise the old washing machine makes when it changes cycle"
   ],
   "citation": {
    "quote": "There goes the glumph",
    "speaker": "Ade",
    "when": "since we moved in"
   },
   "origin": ""
  },
  {
   "n": 6,
   "headword": "crinkler",
   "say": "CRINK-ler",
   "pos": "noun",
   "status": "described",
   "senses": [
    "The TV remote"
   ],
   "citation": null,
   "origin": "named after the crinkly plastic cover Gran put on it"
  },
  {
   "n": 7,
   "headword": "flumpet",
   "say": "FLUM-pet",
   "pos": "unknown",
   "status": "reconstructed",
   "senses": [
    "Meaning uncertain, something to do with being tired"
   ],
   "citation": null,
   "origin": ""
  }
 ],
 "patterns": [
  {
   "name": "Shared -o ending",
   "how": "Some coined words simply add an -o sound to the end, as if that alone makes a thing official.",
   "examples": [
    "snacko",
    "bedso"
   ]
  },
  {
   "name": "Ordinary words given new meanings",
   "how": "An everyday word keeps its usual sound but is pointed at a new target, like a mood or a wrap.",
   "examples": [
    "blankie burrito",
    "the wobbles"
   ]
  }
 ],
 "questions": [
  "What does flumpet actually mean, beyond something to do with being tired?",
  "Has anyone ever actually said crinkler out loud, and if so, what were the words?"
 ]
}

The Moss family - wants citations (uncited)

Input:

{
 "task": "compile",
 "household": "the Moss family",
 "count": "6",
 "words": "[1] spudge - to squash up on the sofa to make room for one more\n[2] toast weather: a grey, drizzly day that only toast can fix\n[3] the long way round - any story Grandad starts that takes twenty minutes to reach the point\n[4] nubbins - the last crusts of a loaf. \"Who ate all the nubbins?\" (Priya)\n[5] oojamaflip: whatever object you can't name right now\n[6] squizzle - maybe a sneeze and a giggle at once? not sure",
 "prescan": "1 | spudge | described | quote: no\n2 | toast weather | described | quote: no\n3 | the long way round | described | quote: no\n4 | nubbins | attested | quote: yes\n5 | oojamaflip | described | quote: no\n6 | squizzle | reconstructed | quote: no"
}

Reply:

{
 "task": "compile",
 "verdict": "uncited",
 "verdict_reason": "only one of six words has a quoted use",
 "title": "A Dictionary of the Moss family",
 "preface": "This dictionary sets down the words a household has made its own, so they are not lost to memory or to time. Use it to settle an old argument, explain a saying to a visitor, or simply enjoy how this family talks.",
 "entries": [
  {
   "n": 1,
   "headword": "spudge",
   "say": "SPUJ",
   "pos": "verb",
   "status": "described",
   "senses": [
    "to squash up on the sofa to make room for one more"
   ],
   "citation": null,
   "origin": ""
  },
  {
   "n": 2,
   "headword": "toast weather",
   "say": "TOHST WETH-er",
   "pos": "phrase",
   "status": "described",
   "senses": [
    "a grey, drizzly day that only toast can fix"
   ],
   "citation": null,
   "origin": ""
  },
  {
   "n": 3,
   "headword": "the long way round",
   "say": "thuh LONG WAY ROWND",
   "pos": "phrase",
   "status": "described",
   "senses": [
    "any story Grandad starts that takes twenty minutes to reach the point"
   ],
   "citation": null,
   "origin": ""
  },
  {
   "n": 4,
   "headword": "nubbins",
   "say": "NUB-inz",
   "pos": "noun",
   "status": "attested",
   "senses": [
    "the last crusts of a loaf"
   ],
   "citation": {
    "quote": "Who ate all the nubbins?",
    "speaker": "Priya",
    "when": ""
   },
   "origin": ""
  },
  {
   "n": 5,
   "headword": "oojamaflip",
   "say": "OO-juh-muh-flip",
   "pos": "noun",
   "status": "described",
   "senses": [
    "whatever object you can't name right now"
   ],
   "citation": null,
   "origin": ""
  },
  {
   "n": 6,
   "headword": "squizzle",
   "say": "SKWIZ-uhl",
   "pos": "unknown",
   "status": "reconstructed",
   "senses": [
    "Meaning uncertain, maybe a sneeze and a giggle at once"
   ],
   "citation": null,
   "origin": ""
  }
 ],
 "patterns": [
  {
   "name": "Everyday phrases, private meaning",
   "how": "An ordinary phrase keeps its usual words but is given a meaning that only this household uses.",
   "examples": [
    "toast weather",
    "the long way round"
   ]
  }
 ],
 "questions": [
  "What does squizzle really mean - is it truly a sneeze and a giggle together, or something else?",
  "Has anyone said spudge out loud so there's a quote to put in its entry?",
  "Does anyone remember actual words for toast weather, so a quote can be added?"
 ]
}

A three-word start - a slim pamphlet (thin)

Input:

{
 "task": "compile",
 "household": "",
 "count": "3",
 "words": "[1] wiggle-waggle - the dog's whole-body hello when we get home. \"Look at that wiggle-waggle!\" (Tomás)\n[2] scronch - to scrunch your nose up at a bad smell\n[3] brumbly?",
 "prescan": "1 | wiggle-waggle | attested | quote: yes\n2 | scronch | described | quote: no\n3 | brumbly | reconstructed | quote: no"
}

Reply:

{
 "task": "compile",
 "verdict": "thin",
 "verdict_reason": "Three words so far - a dictionary wants at least four.",
 "title": "A Household Dictionary",
 "preface": "This little dictionary gathers the words a household has made its own, keeping each one's sense and story side by side. Read it as a work in progress, to be added to as more words and their stories come to light.",
 "entries": [
  {
   "n": 1,
   "headword": "wiggle-waggle",
   "say": "WIG-uhl-WAG-uhl",
   "pos": "noun",
   "status": "attested",
   "senses": [
    "the dog's whole-body hello when we get home"
   ],
   "citation": {
    "quote": "Look at that wiggle-waggle!",
    "speaker": "Tomás",
    "when": ""
   },
   "origin": ""
  },
  {
   "n": 2,
   "headword": "scronch",
   "say": "SKRONCH",
   "pos": "verb",
   "status": "described",
   "senses": [
    "to scrunch your nose up at a bad smell"
   ],
   "citation": null,
   "origin": ""
  },
  {
   "n": 3,
   "headword": "brumbly",
   "say": "BRUM-blee",
   "pos": "unknown",
   "status": "reconstructed",
   "senses": [
    "Meaning uncertain"
   ],
   "citation": null,
   "origin": ""
  }
 ],
 "patterns": [],
 "questions": [
  "What does brumbly actually mean, and when would you use it?",
  "Is there a moment you could quote where someone said scronch out loud?",
  "Who in the house first said wiggle-waggle, and where did it come from?"
 ]
}

Build the input yourself

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

const K = WordKit;
const form = K.form({ household: "Flat 2", notes: "snacko: a snack eaten at the open fridge. \"Just a quick snacko\" (Dad)\nthe wobbles - the cross hour before dinner\nflumpet - something to do with being tired?" });
K.entries(form).list;                            // [{n: 1, headword: "snacko", status: "attested", ...}, ...]
const built = K.buildInput(form);
built.page;                                      // "thin" - fewer than four words
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 dictionary 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://attested-at-home.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":"attested-at-home"}' | 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": "compile", "household": "the Moss family", "count": "6", "words": "[1] spudge - to squash up on the sofa ...\n...", "prescan": "1 | spudge | described | quote: no\n..."}
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 attested-at-home:<task>:<inputHash>:a<attempt> (the one task is compile), 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="attested-at-home:compile:$(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: attested-at-home:compile:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json