← Ticks and Crosses
API

Drive Ticks and Crosses from your own code

The one metered task, dress, is available over HTTP. It takes a logic-grid puzzle the page has already dealt - the lists, the clues and the first step hints, all in plain words - plus a voice, and returns the clues and hints worded in that voice, with a title and a one-line introduction.

The division of labour first: the page deals and solves the puzzle; the model only words it. The page reads three or four lists (the first items of every list go together, and so on), keeps back any item that looks like an email, phone number, handle or link, deals true clues in a seeded order and keeps only the ones its deduction-only solver needs, so the puzzle has exactly one answer. After the reply it re-checks every worded clue - it must name its own items and no others and keep its kind - and keeps the plain wording for any clue that drifts. Your code can do the same with the engine files (gridkit.js, replykit.js).

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": "..." } }

The token is minted for this app (the guest call takes {"slug":"ticks-and-crosses"}), 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, voice, setting, lists, clues, clue_count, steps, step_count) 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: wording the clues is metered and needs a personal sign-in.
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 input and the rules

Every run sends task: dress (the one task is dress); a missing or different one is still answered as dress. All fields are strings.

FieldRequiredWhat it holds
taskyesAlways dress.
voiceyesplain, cosy, grand or brisk.
settingyesA few words about where or when (up to 80 characters), or none given.
listsyesOne line per list, Name: item, item, item, each list sorted so the answer order never leaks. Three or four lists of three to five items.
cluesyesOne line per clue, C1 (kind): plain clue. Kinds: goes with, not, either-or, one-and-the-other. Build it with GridKit.buildInput.
clue_countyesHow many clues, as a string.
stepsyesUp to six step hints, H1 (look at clue N): A goes with B. or H1 (rule: ...): A goes with B.
step_countyesHow many steps, as a string.
retry_notenoOnly on a reformat retry: why the previous reply was unusable.

The kinds keep their logic: goes with has no negative word, not has exactly one, either-or keeps or and never says both or neither, and one-and-the-other keeps one and the other with the same grouping.

The reply

One JSON object:

{"task": "dress", "voice": "plain", "title": "...", "intro": "...", "clues": [{"id": "C1", "text": "..."}], "hints": [{"id": "H1", "text": "..."}]}
FieldWhat it holds
title2-6 words, no item names.
introOne or two sentences on what to work out, no item names.
clues[]One per clue id, in order: the clue worded in the voice, naming exactly its own items.
hints[]One per step id, in order: points at clue N or the rule, then states that step's placement.

The page reads the reply with ReplyKit.normalize and checks it with ReplyKit.check(reply, puzzle), which lists, under "The page's check", every clue or hint that lost an item, named an extra one, flipped its kind, added a number word or an internal id, and every item name in the title or introduction - and returns the view the page shows, with plain wording wherever a worded clue failed.

Worked examples - every sample

These are the free samples on the page: the exact input the page sends and the reply that replays for free. Together they cover all three sizes (three lists of three, four of four, three of five), three voices and all four kinds of clue.

Breakfast mugs

Input:

{
 "task": "dress",
 "voice": "cosy",
 "setting": "Saturday breakfast",
 "lists": "Person: Ana, Ben, Cy\nMug: blue mug, chipped mug, striped mug\nDrink: cocoa, coffee, mint tea",
 "clues": "C1 (either-or): Mint tea goes with either Ben or Cy.\nC2 (either-or): Ben goes with either coffee or mint tea.\nC3 (not): Chipped mug does not go with mint tea.\nC4 (either-or): Blue mug goes with either Ana or Cy.\nC5 (one-and-the-other): Of Ana and Ben, one goes with blue mug and the other with chipped mug.",
 "clue_count": "5",
 "steps": "H1 (look at clues 4 and 5): blue mug goes with Ana.\nH2 (look at clue 5): chipped mug goes with Ben.\nH3 (rule: striped mug has only one place left): striped mug goes with Cy.\nH4 (look at clues 1 and 3): mint tea goes with Cy.\nH5 (look at clue 2): coffee goes with Ben.\nH6 (rule: cocoa has only one place left): cocoa goes with Ana.",
 "step_count": "6"
}

Reply:

{
 "task": "dress",
 "voice": "cosy",
 "title": "Saturday breakfast mugs and drinks",
 "intro": "On Saturday breakfast, work out which person settles with which mug, and which drink comes with each of them.",
 "clues": [
  {
   "id": "C1",
   "text": "Mint tea settles with either Ben or Cy."
  },
  {
   "id": "C2",
   "text": "Ben settles with either coffee or mint tea."
  },
  {
   "id": "C3",
   "text": "Chipped mug does not settle with mint tea."
  },
  {
   "id": "C4",
   "text": "Blue mug settles with either Ana or Cy."
  },
  {
   "id": "C5",
   "text": "Of Ana and Ben, one settles with blue mug and the other with chipped mug."
  }
 ],
 "hints": [
  {
   "id": "H1",
   "text": "Look at clues 4 and 5, and with what you have so far, blue mug settles with Ana."
  },
  {
   "id": "H2",
   "text": "Look at clue 5, and with what you have so far, chipped mug settles with Ben."
  },
  {
   "id": "H3",
   "text": "Since striped mug has only one place left, and with what you have so far, striped mug settles with Cy."
  },
  {
   "id": "H4",
   "text": "Look at clues 1 and 3, and with what you have so far, mint tea settles with Cy."
  },
  {
   "id": "H5",
   "text": "Look at clue 2, and with what you have so far, coffee settles with Ben."
  },
  {
   "id": "H6",
   "text": "Since cocoa has only one place left, and with what you have so far, cocoa settles with Ana."
  }
 ]
}

A wet Monday at work

Input:

{
 "task": "dress",
 "voice": "grand",
 "setting": "a wet Monday at the office",
 "lists": "Colleague: Dana, Eli, Fran, Gus\nLunch: noodles, salad, soup, wrap\nSeat: corner seat, door seat, middle seat, window seat\nUmbrella: blue, green, red, yellow",
 "clues": "C1 (either-or): Red goes with either window seat or door seat.\nC2 (one-and-the-other): Of Dana and Eli, one goes with soup and the other with noodles.\nC3 (either-or): Wrap goes with either blue or green.\nC4 (not): Noodles does not go with door seat.\nC5 (not): Salad does not go with door seat.\nC6 (goes with): Wrap goes with middle seat.\nC7 (either-or): Green goes with either soup or noodles.\nC8 (not): Fran does not go with wrap.\nC9 (either-or): Dana goes with either middle seat or window seat.\nC10 (not): Dana does not go with green.",
 "clue_count": "10",
 "steps": "H1 (look at clues 7 and 10): green goes with Eli.\nH2 (rule: Fran has only one Lunch item left): salad goes with Fran.\nH3 (rule: Gus has only one Lunch item left): wrap goes with Gus.\nH4 (look at clue 3): blue goes with Gus.\nH5 (look at clue 6): middle seat goes with Gus.\nH6 (look at clue 9): window seat goes with Dana.",
 "step_count": "6"
}

Reply:

{
 "task": "dress",
 "voice": "grand",
 "title": "A wet Monday at the office",
 "intro": "Hear now: on a wet Monday at the office, it falls to you to determine which Colleague is paired with which Lunch, which Seat and which Umbrella.",
 "clues": [
  {
   "id": "C1",
   "text": "Red shall belong with either the window seat or the door seat."
  },
  {
   "id": "C2",
   "text": "Of Dana and Eli, one shall be joined with soup and the other with noodles."
  },
  {
   "id": "C3",
   "text": "Wrap shall belong with either blue or green."
  },
  {
   "id": "C4",
   "text": "Noodles shall never go with the door seat."
  },
  {
   "id": "C5",
   "text": "Salad shall never go with the door seat."
  },
  {
   "id": "C6",
   "text": "Wrap shall belong with the middle seat."
  },
  {
   "id": "C7",
   "text": "Green shall belong with either soup or noodles."
  },
  {
   "id": "C8",
   "text": "Fran shall never go with wrap."
  },
  {
   "id": "C9",
   "text": "Dana shall belong with either the middle seat or the window seat."
  },
  {
   "id": "C10",
   "text": "Dana shall never go with green."
  }
 ],
 "hints": [
  {
   "id": "H1",
   "text": "Look now to clues 7 and 10: with what you have so far, green goes with Eli."
  },
  {
   "id": "H2",
   "text": "Thus Fran has only one Lunch item left, and with what you have so far, salad goes with Fran."
  },
  {
   "id": "H3",
   "text": "Thus Gus has only one Lunch item left, and with what you have so far, wrap goes with Gus."
  },
  {
   "id": "H4",
   "text": "Look now to clue 3: with what you have so far, blue goes with Gus."
  },
  {
   "id": "H5",
   "text": "Look now to clue 6: with what you have so far, the middle seat goes with Gus."
  },
  {
   "id": "H6",
   "text": "Look now to clue 9: with what you have so far, the window seat goes with Dana."
  }
 ]
}

The reading corner

Input:

{
 "task": "dress",
 "voice": "brisk",
 "setting": "the reading corner",
 "lists": "Reader: Hal, Ida, Jo, Kit, Lou\nBook: atlas, cookbook, diary, novel, poems\nSnack: apple, crisps, grapes, nuts, toast",
 "clues": "C1 (either-or): Lou goes with either novel or poems.\nC2 (not): Jo does not go with apple.\nC3 (either-or): Poems goes with either toast or nuts.\nC4 (one-and-the-other): Of diary and novel, one goes with nuts and the other with grapes.\nC5 (either-or): Ida goes with either diary or cookbook.\nC6 (one-and-the-other): Of Ida and Kit, one goes with nuts and the other with crisps.\nC7 (either-or): Novel goes with either nuts or crisps.",
 "clue_count": "7",
 "steps": "H1 (look at clue 1): poems goes with Lou.\nH2 (look at clue 3): toast goes with Lou.\nH3 (rule: Jo has only one Snack item left): grapes goes with Jo.\nH4 (look at clue 4): diary goes with Jo.\nH5 (look at clue 5): cookbook goes with Ida.\nH6 (rule: novel has only one place left): novel goes with Kit.",
 "step_count": "6"
}

Reply:

{
 "task": "dress",
 "voice": "brisk",
 "title": "Reading corner match",
 "intro": "In the reading corner, match each Reader to a Book and a Snack.",
 "clues": [
  {
   "id": "C1",
   "text": "Lou goes with either novel or poems."
  },
  {
   "id": "C2",
   "text": "Jo does not go with apple."
  },
  {
   "id": "C3",
   "text": "Poems goes with either toast or nuts."
  },
  {
   "id": "C4",
   "text": "Of diary and novel, one goes with nuts and the other with grapes."
  },
  {
   "id": "C5",
   "text": "Ida goes with either diary or cookbook."
  },
  {
   "id": "C6",
   "text": "Of Ida and Kit, one goes with nuts and the other with crisps."
  },
  {
   "id": "C7",
   "text": "Novel goes with either nuts or crisps."
  }
 ],
 "hints": [
  {
   "id": "H1",
   "text": "Look at clue 1. With what you have so far, poems goes with Lou."
  },
  {
   "id": "H2",
   "text": "Look at clue 3. With what you have so far, toast goes with Lou."
  },
  {
   "id": "H3",
   "text": "Jo has only one Snack item left. With what you have so far, grapes goes with Jo."
  },
  {
   "id": "H4",
   "text": "Look at clue 4. With what you have so far, diary goes with Jo."
  },
  {
   "id": "H5",
   "text": "Look at clue 5. With what you have so far, cookbook goes with Ida."
  },
  {
   "id": "H6",
   "text": "Novel has only one place left. With what you have so far, novel goes with Kit."
  }
 ]
}

Build the input yourself

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

const G = GridKit, R = ReplyKit;
const built = G.buildInput(G.form({ lists: "Person: Ana, Ben, Cy\nDrink: cocoa, coffee, tea\nMug: blue, red, white", voice: "plain", seed: "1" }));  // built.ok is false, with built.note, until the lists are usable
const wire = G.toWire(built.input);   // POST this to /estimate and /run
// then: const reply = R.normalize(R.parseReply(job.output.output));
// R.check(reply, built.puz).notes    // the page's re-check of every clue and hint

Form keys: lists (one list per line, items in matching order), setting, voice and seed (the deal number; New clues adds one). The marks on the grid are the page's business and are not sent.

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://ticks-and-crosses.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":"ticks-and-crosses"}' | 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": "dress", "voice": "plain", "setting": "none given", "lists": "Person: Ana, Ben, Cy\nDrink: cocoa, coffee, tea\nMug: blue, red, white", "clues": "C1 (not): Ana does not go with coffee.\n...", "clue_count": "4", "steps": "H1 (look at clue 1): ...", "step_count": "4"}
# - 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 lane and the input: a retry with the same key never bills twice. The page uses ticks-and-crosses:<task>:<inputHash>:a<attempt> (the one task is dress), 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="ticks-and-crosses:dress:$(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: ticks-and-crosses:dress:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json