← Pieced Together
API

Drive Pieced Together from your own code

The one metered task, piece, is available over HTTP. It takes line_count, lines - one numbered line per email, sender then subject, already redacted - and redacted, a note of what the page replaced. It returns the interest groups an ad system could build from the lines (each with its line numbers, a sensitive flag, what it gives away, the ad that would follow and one way to hide it), the loose lines, a verdict - open_book, half_done or few_pieces - a headline and a closing line.

The division of labour first: the page redacts addresses, links and long numbers and makes its own quick keyword guess; the model reads meaning and writes the words; the page then re-checks the reply: every sent line placed exactly once, the group order (largest first, then lowest first line), the verdict against the run's own groups, the sensitive flags and the word limits. Build lines the same way (see "Build the input yourself") so redaction always happens before sending.

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":"pieced-together"}), 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, line_count, lines, redacted) 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: a read 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 and the verdicts

Every run sends task: piece (the one task is piece); a missing or different one is still answered as piece. Each sent line is placed once - in one interest group, or in loose when it names no interest (password resets, sign-in alerts, codes, welcome notes, receipts and shipping updates that name nothing, statements, topic-less newsletters). A group is clear when it holds two or more lines. The verdict is checked in this order, first match wins: open_book (three or more clear groups), half_done (one or two clear groups, or two or more single-line groups), few_pieces (everything else).

Input (every field is a string)

FieldRequiredWhat it holds
taskyesAlways piece.
line_countyesHow many lines are sent, 3 to 40, as text.
linesyesOne numbered line per email (N. sender - subject), up to 140 characters each. Numbers may skip when the person pulled lines out. Redact first: addresses become [email], links [link], long numbers [number].
redactedyesWhat was replaced, e.g. 1 address replaced with placeholders in the page, or none.
retry_notenoOnly on the page's one reformat retry, after an unusable reply.

Reply (one JSON object)

{"task": "piece", "verdict": "half_done", "headline": "...",
 "segments": [{"name": "...", "lines": [2, 3], "sensitive": false, "gives_away": "...", "ad": "...", "hide": "..."}, ...],
 "loose": [1, 4], "closing": "..."}
FieldWhat it holds
verdict, headlineopen_book, half_done or few_pieces; and a headline of at most 14 words that agrees with it.
segmentsAt most 6, largest first (ties: lowest first line). Each: name (at most 4 words, never a company), lines (ascending), sensitive (true for health, pregnancy or young children, money trouble, a job search, faith, politics, sexuality or dating), gives_away (at most 22 words, citing the lines), ad (at most 14 words, no brands) and hide (one practical step, at most 22 words).
looseThe line numbers in no group, ascending.
closingOne line of at most 18 words, addressed to the reader, that agrees with the verdict.

The page then checks the reply (PieceKit.check) - every sent line placed once, the verdict against the run's own groups, the order, the sensitive flags and the word limits - and lists any disagreement under "The page's check".

Worked examples

These are the three free samples on the page: the exact input and a stand-in model's reply, unedited. Together they cover every verdict - a busy week (open book), a quiet inbox (half done) and mostly resets and receipts (a few pieces). All senders are made up.

A busy week - open book

Input:

{
 "task": "piece",
 "line_count": "12",
 "lines": "1. Coastline Air - Your boarding pass for Friday's flight\n2. Harbour Hotel - Booking confirmed: 2 nights\n3. Riverside Run Club - Saturday long run moved to 8am\n4. Trailhead Outfitters - Your trail running shoes have shipped\n5. Little Sprouts Nursery - Photos from this week's playgroup\n6. Bump and Beyond - Week 20: what to expect\n7. Paws Corner - Time to reorder kibble for Biscuit\n8. Greenleaf Vets - Reminder: annual booster due\n9. Account security - New sign-in to your account ([email])\n10. City Library - 2 books due back on Monday\n11. Weekend Deals - 40% off sofas this weekend only\n12. Half Marathon Entries - Your race number is ready",
 "redacted": "1 address replaced with placeholders in the page"
}

Reply:

{
 "task": "piece",
 "verdict": "open_book",
 "headline": "Running, travel, starting a family and a pet all stand out clearly.",
 "segments": [
  {
   "name": "Distance runner",
   "lines": [
    3,
    4,
    12
   ],
   "sensitive": false,
   "gives_away": "Lines 3, 4 and 12: a run club, trail running shoes and a race number point to distance running.",
   "ad": "ads for running gear and local races",
   "hide": "Unsubscribe from the run club, shoe retailer and race entry emails."
  },
  {
   "name": "Trip planner",
   "lines": [
    1,
    2
   ],
   "sensitive": false,
   "gives_away": "Lines 1 and 2: a boarding pass and a hotel booking point to a trip away.",
   "ad": "ads for flights and hotel deals",
   "hide": "Unsubscribe from the airline and hotel booking emails."
  },
  {
   "name": "Starting a family",
   "lines": [
    5,
    6
   ],
   "sensitive": true,
   "gives_away": "Lines 5 and 6: nursery playgroup photos and a pregnancy update point to a young family.",
   "ad": "ads for baby and parenting products",
   "hide": "Use a separate email for parenting and pregnancy newsletters."
  },
  {
   "name": "Pet care",
   "lines": [
    7,
    8
   ],
   "sensitive": false,
   "gives_away": "Lines 7 and 8: kibble for Biscuit and a booster reminder point to owning a pet.",
   "ad": "ads for pet food and vet services",
   "hide": "Unsubscribe from the pet food and vet reminder emails."
  },
  {
   "name": "Library user",
   "lines": [
    10
   ],
   "sensitive": false,
   "gives_away": "Line 10: two library books due back point to reading.",
   "ad": "ads for books and reading apps",
   "hide": "Unsubscribe from the library's due-date email reminders."
  },
  {
   "name": "Furniture shopper",
   "lines": [
    11
   ],
   "sensitive": false,
   "gives_away": "Line 11: a sofa discount points to furniture shopping.",
   "ad": "ads for furniture and home deals",
   "hide": "Unsubscribe from the weekend deals emails."
  }
 ],
 "loose": [
  9
 ],
 "closing": "These lines reveal several clear interests about you, but small changes could keep more private."
}

A quiet inbox - half done

Input:

{
 "task": "piece",
 "line_count": "8",
 "lines": "1. Account security - Verify your new device\n2. Northside Books - Your preorder ships Tuesday\n3. Book Club Circle - This month's novel and meeting notes\n4. Parcel Tracking - Your parcel is out for delivery\n5. Monthly Statement - Your statement is ready at [link]\n6. Photo Backup - Your storage is almost full\n7. Garden Centre - Spring bulbs are back in stock\n8. Receipt - Thanks for your order",
 "redacted": "1 link replaced with placeholders in the page"
}

Reply:

{
 "task": "piece",
 "verdict": "half_done",
 "headline": "A reading interest stands out, with little else in focus.",
 "segments": [
  {
   "name": "Book lover",
   "lines": [
    2,
    3
   ],
   "sensitive": false,
   "gives_away": "Line 2's book preorder and line 3's book club novel together point to an interest in reading.",
   "ad": "ads for new book releases and book clubs",
   "hide": "Unsubscribe from the bookstore and the book club mailing lists."
  },
  {
   "name": "Gardener",
   "lines": [
    7
   ],
   "sensitive": false,
   "gives_away": "Line 7's spring bulb restock alert suggests an interest in gardening.",
   "ad": "ads for gardening supplies and spring plants",
   "hide": "Unsubscribe from the garden centre's restock alerts."
  }
 ],
 "loose": [
  1,
  4,
  5,
  6,
  8
 ],
 "closing": "Your lines show a reading interest and a gardening hint, but plenty about you stays unclear."
}

Mostly resets and receipts - a few pieces

Input:

{
 "task": "piece",
 "line_count": "6",
 "lines": "1. Password reset - Your reset code [number]\n2. Order update - Your order has shipped\n3. Newsletter - Our October update\n4. Account security - Unusual sign-in attempt blocked\n5. Welcome - Thanks for creating an account\n6. Clay Corner Studio - Your Thursday wheel class is booked",
 "redacted": "1 long number replaced with placeholders in the page"
}

Reply:

{
 "task": "piece",
 "verdict": "few_pieces",
 "headline": "Mostly blank, just one pottery class booking shows through.",
 "segments": [
  {
   "name": "Pottery wheel class",
   "lines": [
    6
   ],
   "sensitive": false,
   "gives_away": "Line 6: a booked wheel class points to an interest in pottery.",
   "ad": "ads for pottery studios and craft classes",
   "hide": "Unsubscribe from Clay Corner Studio's emails or use a separate address for class bookings."
  }
 ],
 "loose": [
  1,
  2,
  3,
  4,
  5
 ],
 "closing": "There's not much for an ad system to piece together about you here beyond a pottery class."
}

Build the input yourself

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

const K = PieceKit, A = PieceArt;
const built = K.buildInput({ text: "Town Pool - Lane times for next week\nCorner Bakery - Your stamp card is full\nPassword reset - Your code #482913", hidden: [] });
built.parsed.rows.map(r => r.text);     // redacted: the code became [number]
built.prescan.verdict;                  // the page's quick keyword guess
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 finished picture 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://pieced-together.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":"pieced-together"}' | 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": "piece", "line_count": "2", "lines": "1. ...
2. ..."} - 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 pieced-together:<task>:<inputHash>:a<attempt> (the one task is piece), 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="pieced-together:piece:$(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: pieced-together:piece:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json