← Kin Chronicle / API
Tokens

Drive Kin Chronicle from your own code

The gap-question pass the page runs is available over HTTP. A natural use is a family tree you already keep elsewhere - a GEDCOM export, a spreadsheet of remembered dates, a folder of interview notes: a script turns it into lanes and dated events, asks what to ask next, and after the next visit to a relative sends a follow-up that checks which questions the new events answer.

Be clear about the split first: the model never sees your files, only the lane and event lines you build. The caller parses the fuzzy dates (c. 1950, spring 1962, before 1945, 1940 - 1945) into decimal-year ranges, computes the facts (gaps per lane, contradictions, coverage) and sends them along. The reply names lanes and events by id; refusing a question that names a lane you do not have, or a date outside the span, is the caller's job. Context events are general history and must be shown as context, unverified, never as facts about the family. The page's own date parser, checks and input builder ship as plain scripts you can load in node - see the end of the examples.

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":"kin-chronicle"}), so no slug header is needed afterwards. Send it as Authorization: Bearer …. The run body is the input object: never wrap it as {"input": {…}} — that returns 200, warns unknown field 'input', and hides every field from the model.

Errors:

StatusCodeMeaning
400validation_errorThe body is not a JSON object.
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: gap passes 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 comes first

One system prompt serves two tasks. task picks the contract; anything else is read as gaps and the reply's meta line says so.

taskWhenQuestion lines carry
gapsThe first pass over a timeline: where it is thin, what to ask a relative or look up, why the flagged contradictions might have happened, what general history was going on.No status.
followupAfter you added answers (new events) since the last pass. Needs previous_json.status on every question: answered / open for each earlier qid that was not dismissed, new for new ones.

Every run body is a JSON object of string fields (the declared input schema; task, title, kind, today, span, lanes, events and facts_json are required, and /estimate warns when one is missing):

FieldWhat it holds
task"gaps" or "followup".
titleWhat the timeline is about, e.g. The Okavume-Quellby family.
kindfamily, house, club, care, career or free.
todayThe current year, e.g. 2026.
spanThe timeline's extent, 1908 - 2026. Every date in the reply must fall inside it.
lanesOne line per lane: <lane id> | <name> | <kind> | <details>. Kinds: person, place, thread, context. Details such as parents: L2, L3; born c. 1941; died 2015.
eventsOne line per event, in date order: <event id> | <lane ids> | <date label> [<from> - <to>] | <type> | <title> | <place> | <extra>. The bracket is the date's range in decimal years (? for an open end). extra may hold people:, source:, conf: strong|moderate|speculative, note: and CONTEXT-UNVERIFIED on an accepted context event. The page sends at most a fixed number of events and leaves a marker line such as (... 14 events in L2 between 1961 and 1974 not sent).
erasOptional: <era id> | <label> | <date range>, named periods the user drew.
facts_jsonJSON string: counts, min_gap_years, gaps (per lane: lane, from, to, years), contradictions (kind order, parent_age, place, duplicate or age; level conflict or check; lane, ids, text), anchors_missing, undated ids and coverage per lane.
previous_jsonfollowup only. JSON string: the last pass's questions (qid, lane, from, to, text, state open/answered/dismissed, answered_by, events_in_range), explanations (xid, ids), context (cid, title, state accepted/dismissed/pending) and events_added_since.
clip_noteWhat was not sent, in words; empty when nothing was cut.
retry_noteOnly on a reformat retry, when the previous reply could not be read.

The reply text is JSON Lines - one object per line, so a reply cut short still yields every whole line:

{"k":"meta","task":"gaps","summary":"..."}
{"k":"q","qid":"q1","lane":"L4","from":"1913","to":"1934","ask":"relative","who":"cousin Ifeoma","text":"...","why":"...","hint":"","status":"open|answered|new (followup only)"}
{"k":"q","qid":"q2","lane":"L6","from":"1938","to":"1983","ask":"record","who":"","text":"...","why":"...","hint":"1939 Register; electoral rolls for Bootle"}
{"k":"x","xid":"x1","ids":["e8","e7"],"kind":"order","text":"...","resolve":"..."}
{"k":"ctx","cid":"c1","lane":"L2","date":"1960","title":"...","scope":"local|national|world","why":"..."}
{"k":"end"}

A gaps reply has no status fields; a followup reply gives every question one.

Worked examples

The bundled Okavume-Quellby example on the page (an invented three-generation family between Enugu and Liverpool), as the exact run bodies the page builds: the first pass, then a follow-up after four answers were added.

gaps: the Okavume-Quellby family, first pass

Input (seven lanes, 27 events; the checks found two conflicts, one place check and nine gaps):

{
 "task": "gaps",
 "title": "The Okavume-Quellby family",
 "kind": "family",
 "today": "2026",
 "span": "1908 - 2026",
 "lanes": "(lines - shown below)",
 "events": "(lines - shown below)",
 "eras": "(lines - shown below)",
 "facts_json": "(a JSON string - decoded below)",
 "clip_note": ""
}

lanes:

L1 | Ada Okavume-Quellby | person | parents: L2, L3; born 2 Feb 1968; sex: F
L2 | Grace Quellby (née Okavume) | person | parents: L4, L5; born c. 1941; died 2015; sex: F
L3 | Thomas Quellby | person | parents: L6; born 14 Mar 1938; died Nov 2001; sex: M
L4 | Samuel Okavume | person | born c. 1910; died 1959; sex: M
L5 | Comfort Okavume | person | born before 1920; sex: F
L6 | Edith Quellby | person | born 1912; died c. 1985; sex: F
L7 | Liverpool homes | place

events:

e1 | L4 | c. 1910 [1908.00 - 1913.00] | birth | Born | Nsukka | source: Family memory (Grace); conf: speculative
e11 | L6 | 1912 [1912.00 - 1913.00] | birth | Born (baptism register) | Bootle | source: Parish register; conf: strong
e12 | L6 | 1914 [1914.00 - 1915.00] | birth | Born (1939 Register) | Bootle | source: 1939 Register; conf: moderate
e2 | L5 | before 1920 [? - 1920.00] | birth | Born | Enugu area | conf: speculative
e3 | L4,L5 | c. 1936 [1934.00 - 1939.00] | marriage | Married | Enugu | conf: speculative; note: A church wedding, remembered by Grace's cousin Ifeoma.
e4 | L4 | 1938 – 1958 [1938.00 - 1959.00] | work | Headmaster, St Mary's school | Enugu | source: School centenary booklet; conf: moderate
e13 | L3,L6 | 14 Mar 1938 [1938.20 - 1938.20] | birth | Born | Liverpool | source: Birth certificate; conf: strong
e5 | L2,L5 | c. 1941 [1939.00 - 1944.00] | birth | Born | Enugu | conf: speculative; note: Grace always said she was born 'the year the rains failed'.
e14 | L3 | 1955 – 1964 [1955.00 - 1965.00] | work | Merchant Navy, Elder Dempster Lines | at sea | source: Discharge book; conf: strong
e6 | L2 | 1956 – 1960 [1956.00 - 1961.00] | education | Nursing school | Enugu | conf: moderate
e7 | L4 | 1959 [1959.00 - 1960.00] | death | Died | Enugu | source: Grave marker (photo); conf: moderate
e15 | L3 | Jun 1960 [1960.42 - 1960.50] | other | Ship docks at Lagos | Lagos | source: Discharge book; conf: strong
e16 | L3 | Jun 1960 [1960.42 - 1960.50] | other | Sister Jean's wedding | Liverpool | conf: speculative; note: Is he in the wedding photo? Jean says yes.
e8 | L4,L2 | Mar 1961 [1961.16 - 1961.25] | other | Letter from Samuel to Grace | Enugu | source: Letter, family papers; conf: moderate; note: In the tin box of papers, signed 'your father'.
e10 | L2 | 1962 – 1990 [1962.00 - 1991.00] | work | Nurse, Walton Hospital | Liverpool | conf: strong
e9 | L2 | spring 1962 [1962.16 - 1962.41] | migration | Sails to Liverpool | Liverpool | source: Passenger list (seen online); conf: moderate
e18 | L3 | 1965 – 1983 [1965.00 - 1984.00] | work | Docker, Gladstone Dock | Bootle | conf: moderate
e19 | L7,L2,L3 | 1966 – 1979 [1966.00 - 1980.00] | residence | 12 Corvell Road | Kirkdale, Liverpool | conf: strong
e17 | L2,L3 | Sep 1966 [1966.67 - 1966.75] | marriage | Married | Liverpool | source: Marriage certificate; conf: strong
e20 | L1,L2,L3 | 2 Feb 1968 [1968.09 - 1968.09] | birth | Born | Liverpool | source: Birth certificate; conf: strong
e21 | L2 | 1975 [1975.00 - 1976.00] | other | Trip home to Enugu | Enugu | conf: speculative
e22 | L7,L2 | 1979 – 2015 [1979.00 - 2016.00] | residence | 40 Pellin Lane | Litherland | conf: strong
e23 | L6 | c. 1985 [1983.00 - 1988.00] | death | Died | Bootle | conf: speculative
e24 | L1 | 1986 – 1989 [1986.00 - 1990.00] | education | University | Leeds | conf: strong
e25 | L1 | 1990s [1990.00 - 2000.00] | move | Moved to London for work | London | conf: moderate
e26 | L3 | Nov 2001 [2001.83 - 2001.92] | death | Died | Liverpool | source: Death certificate; conf: strong
e27 | L2 | 2015 [2015.00 - 2016.00] | death | Died | Litherland | source: Funeral order of service; conf: strong

eras:

E1 | Before Liverpool | 1936 – 1962
E2 | Corvell Road | 1966 – 1979
E3 | Pellin Lane | 1979 – 2015

facts_json, decoded:

{
 "counts": {
  "lanes": 7,
  "people": 6,
  "events": 27,
  "dated": 27,
  "undated": 0,
  "context": 0
 },
 "min_gap_years": 10,
 "gaps": [
  {
   "gid": "g1",
   "lane": "L6",
   "from": "1938",
   "to": "1983",
   "years": 44.8,
   "open": false
  },
  {
   "gid": "g2",
   "lane": "L1",
   "from": "2000",
   "to": "2026",
   "years": 26,
   "open": true
  },
  {
   "gid": "g3",
   "lane": "L6",
   "from": "1915",
   "to": "1938",
   "years": 23.2,
   "open": false
  },
  {
   "gid": "g4",
   "lane": "L4",
   "from": "1913",
   "to": "1934",
   "years": 21,
   "open": false
  },
  {
   "gid": "g5",
   "lane": "L1",
   "from": "1968",
   "to": "1986",
   "years": 17.9,
   "open": false
  },
  {
   "gid": "g6",
   "lane": "L3",
   "from": "1984",
   "to": "2001",
   "years": 17.8,
   "open": false
  },
  {
   "gid": "g7",
   "lane": "L3",
   "from": "1938",
   "to": "1955",
   "years": 16.8,
   "open": false
  },
  {
   "gid": "g8",
   "lane": "L5",
   "from": "1920",
   "to": "1934",
   "years": 14,
   "open": false
  },
  {
   "gid": "g9",
   "lane": "L2",
   "from": "1944",
   "to": "1956",
   "years": 12,
   "open": false
  }
 ],
 "contradictions": [
  {
   "cid": "k1",
   "kind": "order",
   "level": "conflict",
   "lane": "L4",
   "ids": [
    "e8",
    "e7"
   ],
   "text": "Letter from Samuel to Grace (Mar 1961) is after Samuel Okavume died (1959)."
  },
  {
   "cid": "k2",
   "kind": "duplicate",
   "level": "conflict",
   "lane": "L6",
   "ids": [
    "e11",
    "e12"
   ],
   "text": "Edith Quellby has two birth dates: 1912 and 1914 - they cannot both be right."
  },
  {
   "cid": "k3",
   "kind": "place",
   "level": "check",
   "lane": "L3",
   "ids": [
    "e15",
    "e16"
   ],
   "text": "Thomas Quellby is in Lagos and Liverpool at the same time (Jun 1960, Jun 1960)."
  }
 ],
 "anchors_missing": [
  {
   "lane": "L5",
   "what": "death",
   "text": "Comfort Okavume (born before 1920) has no death date."
  }
 ],
 "undated": [],
 "coverage": {
  "L1": 0.29,
  "L2": 0.87,
  "L3": 0.52,
  "L4": 0.64,
  "L5": 0.52,
  "L6": 0.16,
  "L7": 1
 }
}

followup: the same family after four answers were added

Input (previous_json carries the first pass - five questions, one dismissed, two explanations, three context proposals - and the events added since; the accepted context event sits in events marked CONTEXT-UNVERIFIED):

{
 "task": "followup",
 "title": "The Okavume-Quellby family",
 "kind": "family",
 "today": "2026",
 "span": "1908 - 2026",
 "lanes": "(lines - shown below)",
 "events": "(lines - shown below)",
 "eras": "(lines - shown below)",
 "facts_json": "(a JSON string - decoded below)",
 "clip_note": "",
 "previous_json": "(a JSON string - decoded below)"
}

lanes:

L1 | Ada Okavume-Quellby | person | parents: L2, L3; born 2 Feb 1968; sex: F
L2 | Grace Quellby (née Okavume) | person | parents: L4, L5; born c. 1941; died 2015; sex: F
L3 | Thomas Quellby | person | parents: L6; born 14 Mar 1938; died Nov 2001; sex: M
L4 | Samuel Okavume | person | born c. 1910; died 1959; sex: M
L5 | Comfort Okavume | person | born before 1920; sex: F
L6 | Edith Quellby | person | born 1912; died c. 1985; sex: F
L7 | Liverpool homes | place

events:

e1 | L4 | c. 1910 [1908.00 - 1913.00] | birth | Born | Nsukka | source: Family memory (Grace); conf: speculative
e11 | L6 | 1912 [1912.00 - 1913.00] | birth | Born (baptism register) | Bootle | source: Parish register; conf: strong
e12 | L6 | 1914 [1914.00 - 1915.00] | birth | Born (1939 Register) | Bootle | source: 1939 Register; conf: moderate
e2 | L5 | before 1920 [? - 1920.00] | birth | Born | Enugu area | conf: speculative
e30 | L4 | 1931 – 1935 [1931.00 - 1936.00] | education | Teacher training college | Awka | source: Told by cousin Ifeoma, 2026; conf: speculative
e3 | L4,L5 | c. 1936 [1934.00 - 1939.00] | marriage | Married | Enugu | conf: speculative; note: A church wedding, remembered by Grace's cousin Ifeoma.
e4 | L4 | 1938 – 1958 [1938.00 - 1959.00] | work | Headmaster, St Mary's school | Enugu | source: School centenary booklet; conf: moderate
e13 | L3,L6 | 14 Mar 1938 [1938.20 - 1938.20] | birth | Born | Liverpool | source: Birth certificate; conf: strong
e5 | L2,L5 | c. 1941 [1939.00 - 1944.00] | birth | Born | Enugu | conf: speculative; note: Grace always said she was born 'the year the rains failed'.
e29 | L3 | 1953 – 1955 [1953.00 - 1956.00] | work | Apprentice fitter, Bibby's | Liverpool | source: Told by his sister Jean, 2026; conf: moderate
e14 | L3 | 1955 – 1964 [1955.00 - 1965.00] | work | Merchant Navy, Elder Dempster Lines | at sea | source: Discharge book; conf: strong
e6 | L2 | 1956 – 1960 [1956.00 - 1961.00] | education | Nursing school | Enugu | conf: moderate
e7 | L4 | 1959 [1959.00 - 1960.00] | death | Died | Enugu | source: Grave marker (photo); conf: moderate
e15 | L3 | Jun 1960 [1960.42 - 1960.50] | other | Ship docks at Lagos | Lagos | source: Discharge book; conf: strong
e16 | L3 | Jun 1960 [1960.42 - 1960.50] | other | Sister Jean's wedding | Liverpool | conf: speculative; note: Is he in the wedding photo? Jean says yes.
e32 | L2 | 1 Oct 1960 [1960.75 - 1960.75] | context | Nigerian independence | Nigeria | CONTEXT-UNVERIFIED
e8 | L4,L2 | Mar 1961 [1961.16 - 1961.25] | other | Letter from Samuel to Grace | Enugu | source: Letter, family papers; conf: moderate; note: In the tin box of papers, signed 'your father'.
e10 | L2 | 1962 – 1990 [1962.00 - 1991.00] | work | Nurse, Walton Hospital | Liverpool | conf: strong
e9 | L2 | spring 1962 [1962.16 - 1962.41] | migration | Sails to Liverpool | Liverpool | source: Passenger list (seen online); conf: moderate
e18 | L3 | 1965 – 1983 [1965.00 - 1984.00] | work | Docker, Gladstone Dock | Bootle | conf: moderate
e19 | L7,L2,L3 | 1966 – 1979 [1966.00 - 1980.00] | residence | 12 Corvell Road | Kirkdale, Liverpool | conf: strong
e17 | L2,L3 | Sep 1966 [1966.67 - 1966.75] | marriage | Married | Liverpool | source: Marriage certificate; conf: strong
e20 | L1,L2,L3 | 2 Feb 1968 [1968.09 - 1968.09] | birth | Born | Liverpool | source: Birth certificate; conf: strong
e28 | L1 | 1972 – 1979 [1972.00 - 1980.00] | education | St Mary's primary school | Kirkdale | source: Ada's own memory; conf: moderate
e21 | L2 | 1975 [1975.00 - 1976.00] | other | Trip home to Enugu | Enugu | conf: speculative
e22 | L7,L2 | 1979 – 2015 [1979.00 - 2016.00] | residence | 40 Pellin Lane | Litherland | conf: strong
e23 | L6 | c. 1985 [1983.00 - 1988.00] | death | Died | Bootle | conf: speculative
e24 | L1 | 1986 – 1989 [1986.00 - 1990.00] | education | University | Leeds | conf: strong
e25 | L1 | 1990s [1990.00 - 2000.00] | move | Moved to London for work | London | conf: moderate
e26 | L3 | Nov 2001 [2001.83 - 2001.92] | death | Died | Liverpool | source: Death certificate; conf: strong
e31 | L1 | 2003 [2003.00 - 2004.00] | marriage | Married Daniel Varnoley | London | source: Marriage certificate; conf: strong
e27 | L2 | 2015 [2015.00 - 2016.00] | death | Died | Litherland | source: Funeral order of service; conf: strong

eras:

E1 | Before Liverpool | 1936 – 1962
E2 | Corvell Road | 1966 – 1979
E3 | Pellin Lane | 1979 – 2015

facts_json, decoded:

{
 "counts": {
  "lanes": 7,
  "people": 6,
  "events": 32,
  "dated": 32,
  "undated": 0,
  "context": 1
 },
 "min_gap_years": 10,
 "gaps": [
  {
   "gid": "g1",
   "lane": "L6",
   "from": "1938",
   "to": "1983",
   "years": 44.8,
   "open": false
  },
  {
   "gid": "g2",
   "lane": "L6",
   "from": "1915",
   "to": "1938",
   "years": 23.2,
   "open": false
  },
  {
   "gid": "g3",
   "lane": "L1",
   "from": "2004",
   "to": "2026",
   "years": 22,
   "open": true
  },
  {
   "gid": "g4",
   "lane": "L4",
   "from": "1913",
   "to": "1931",
   "years": 18,
   "open": false
  },
  {
   "gid": "g5",
   "lane": "L3",
   "from": "1984",
   "to": "2001",
   "years": 17.8,
   "open": false
  },
  {
   "gid": "g6",
   "lane": "L3",
   "from": "1938",
   "to": "1953",
   "years": 14.8,
   "open": false
  },
  {
   "gid": "g7",
   "lane": "L5",
   "from": "1920",
   "to": "1934",
   "years": 14,
   "open": false
  },
  {
   "gid": "g8",
   "lane": "L2",
   "from": "1944",
   "to": "1956",
   "years": 12,
   "open": false
  }
 ],
 "contradictions": [
  {
   "cid": "k1",
   "kind": "order",
   "level": "conflict",
   "lane": "L4",
   "ids": [
    "e8",
    "e7"
   ],
   "text": "Letter from Samuel to Grace (Mar 1961) is after Samuel Okavume died (1959)."
  },
  {
   "cid": "k2",
   "kind": "duplicate",
   "level": "conflict",
   "lane": "L6",
   "ids": [
    "e11",
    "e12"
   ],
   "text": "Edith Quellby has two birth dates: 1912 and 1914 - they cannot both be right."
  },
  {
   "cid": "k3",
   "kind": "place",
   "level": "check",
   "lane": "L3",
   "ids": [
    "e15",
    "e16"
   ],
   "text": "Thomas Quellby is in Lagos and Liverpool at the same time (Jun 1960, Jun 1960)."
  }
 ],
 "anchors_missing": [
  {
   "lane": "L5",
   "what": "death",
   "text": "Comfort Okavume (born before 1920) has no death date."
  }
 ],
 "undated": [],
 "coverage": {
  "L1": 0.52,
  "L2": 0.87,
  "L3": 0.55,
  "L4": 0.7,
  "L5": 0.52,
  "L6": 0.16,
  "L7": 1
 }
}

previous_json, decoded:

{
 "questions": [
  {
   "qid": "q1",
   "lane": "L4",
   "from": "1913",
   "to": "1934",
   "text": "Where did Samuel go to school, and how did he come to train as a teacher before St Mary's?",
   "state": "open",
   "answered_by": "",
   "events_in_range": [
    "e30"
   ]
  },
  {
   "qid": "q2",
   "lane": "L3",
   "from": "1938",
   "to": "1955",
   "text": "What did Thomas do between leaving school and joining Elder Dempster in 1955?",
   "state": "open",
   "answered_by": "",
   "events_in_range": [
    "e29"
   ]
  },
  {
   "qid": "q3",
   "lane": "L1",
   "from": "1968",
   "to": "1986",
   "text": "Which schools did Ada go to while the family lived on Corvell Road?",
   "state": "open",
   "answered_by": "",
   "events_in_range": [
    "e28"
   ]
  },
  {
   "qid": "q4",
   "lane": "L1",
   "from": "2000",
   "to": "2026",
   "text": "What has Ada done since moving to London - work, homes, marriage?",
   "state": "open",
   "answered_by": "",
   "events_in_range": [
    "e31"
   ]
  },
  {
   "qid": "q5",
   "lane": "L6",
   "from": "1938",
   "to": "1983",
   "text": "Where did Edith live and work after Thomas was born in 1938?",
   "state": "dismissed",
   "answered_by": "",
   "events_in_range": []
  }
 ],
 "explanations": [
  {
   "xid": "x1",
   "ids": [
    "e8",
    "e7"
   ]
  },
  {
   "xid": "x2",
   "ids": [
    "e11",
    "e12"
   ]
  }
 ],
 "context": [
  {
   "cid": "c1",
   "title": "Nigerian independence",
   "state": "accepted"
  },
  {
   "cid": "c2",
   "title": "Liverpool Blitz",
   "state": "dismissed"
  },
  {
   "cid": "c3",
   "title": "Nigerian Civil War",
   "state": "pending"
  }
 ],
 "events_added_since": [
  "e28",
  "e29",
  "e30",
  "e31",
  "e32"
 ]
}

The page builds the input and checks the reply; the API does not

Over the API you get questions, explanations and context proposals as JSON Lines. Parsing fuzzy dates, building lanes, events and facts_json, and refusing a line that names a lane or event you do not have (or a date outside span) is the caller's job. The page's own code is plain scripts you can load in node after global.window = {}: chron.js (Kin.parseDate(text) for the fuzzy dates, Kin.buildInput(task, doc) builds this exact run body with clipping and marker lines, Kin.contradictions(doc), Kin.gaps(doc) and Kin.coverage(doc) are the facts) and io.js (CSV and a GEDCOM subset in and out, the Markdown interview sheet).

Step 1 — a tiny client helper

One function that sends JSON and unwraps the envelope. Replace YOUR_TOKEN with the token from /tokens.html, or leave it and mint a guest token in step 2.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="YOUR_TOKEN"   # from https://kin-chronicle.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":"kin-chronicle"}' | 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 (not wrapped in {"input": ...}). hold_credits is a reservation, not the price; min_credits is what the balance must cover; model_alias reads gpt-terra and model the concrete model it resolves to; markup_bps is 1000 (a 10% markup on the model cost).

# input.json: the run input object - {"task": "gaps", "title": "...", "kind": "family", "today": "2026", "span": "1908 - 2026", "lanes": "L1 | ...", "events": "e1 | ...", "facts_json": "{...}"}
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 kin-chronicle-<task>-<inputHash>-a<attempt>. The job's output.output is the JSON Lines reply text; truncated: true means the balance cut it short, and every whole line before the cut still parses.

KEY="kin-chronicle-$(jq -r .task input.json)-$(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.jsonl   # JSON Lines: meta, q, x, ctx, end
jq -c 'select(.k == "q") | {qid, lane, from, to, ask, text}' reply.jsonl
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: kin-chronicle-$(jq -r .task input.json)-$(shasum -a 256 input.json | cut -c1-16)-a1" --data @input.json