← Patch the Hull
API

Drive Patch the Hull from your own code

The one metered task, patch-plan, is available over HTTP. It takes one website's answers - a short label, the PHP version as the hosting panel shows it, hosting, who changes the server, backup, whether a short outage is fine, and whether visitors log in or pay - and returns a patch-night runbook: 3 to 6 steps naming who does each one, what to do if it stalls, how to recover, and a note for the person who changes the server.

The division of labour first: the page decides; the model words it. The page reads the version, picks the verdict against the fixed builds published on 21 October 2026 for CVE-2026-109618 and CVE-2026-109619, works out the target, whose job the server steps are and whether a note is needed, and sends those as facts. The model never changes the verdict. Not professional security advice.

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":"patch-the-hull"}), 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, site, facts) 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 reasons are metered and need 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 verdicts

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

FieldRequiredWhat it holds
taskyesAlways patch-plan.
siteyesOne line: site: ... | version as given: ... | hosting: ... | who changes the server: ... | backup: ... | a short outage: ... | visitors log in or pay: ... | notes: ..., with "not given" for blanks.
factsyesThe page's lines: the verdict id and its reason, the target, the version it read (flagged when it looks like a distribution or panel build), whose job the server steps are, whether a note is needed and for whom, and the published fixed builds.
retry_notenoOnly on a reformat retry: why the previous reply was unusable.

The verdict, first match wins: no full version the page can read (blank, unreadable, a line that never existed, a line above 8.5, or 8.2 to 8.5 without its build number) is find-version; a line older than 5.4 is upgrade-line; 8.2 to 8.5 at or past the fixed build (8.2.35, 8.3.36, 8.4.27, 8.5.12) is patched, below it update-now; 7.4, 8.0 and 8.1 (source patches only) are backport-or-upgrade; 5.4 to 7.3 (no fix) are upgrade-line.

The reply

One JSON object, no prose around it:

{"task": "patch-plan", "verdict": "update-now", "headline": "...", "steps": [{"who": "host", "do": "...", "check": "..."}], "escalate": "...", "recover": "...", "note": "...", "closing": "..."}
FieldWhat it holds
verdictThe verdict id from facts, copied exactly.
headlineOne sentence, at most 24 words, on what the verdict means for this site.
steps[]3 to 6 steps in order: who (you, web person or host), do (one action, at most 40 words) and check (how that person knows it is done, at most 20 words).
escalate, recoverWhat to do if a step stalls, and if the site misbehaves after the change.
noteA message of at most 100 words for the person who changes the server; empty when the owner changes it.
closingOne sentence that agrees with the verdict.

The page then checks the reply (HullKit.check) - the verdict against its own, the step count, who each step is for, the note, build numbers that are neither published fixed builds nor yours, time or day words you did not give, talk of attacks you did not mention, products you did not name, and contact details or public posting - and lists anything it finds under "The page's check".

Worked examples - all five verdicts

These are the 5 free samples on the page: the exact input the page sends and the reply that replays for free. Together they cover all five verdicts.

Bakery orders - verdict: update now

Input:

{
 "task": "patch-plan",
 "site": "site: Bakery order site | version as given: 8.3.14 | hosting: Shared hosting (a control panel) | who changes the server: The hosting company | backup: Yes, never tried restoring | a short outage: Needs a quiet slot | visitors log in or pay: Yes | notes: customers pay for cake orders on it",
 "facts": "verdict: update-now (8.3.14 is below the fixed build 8.3.36)\ntarget: 8.3.36 or later\nversion read: 8.3.14\nserver steps belong to: host\nnote for the person who changes the server: write one, addressed to the hosting company\npublished fixed builds: 8.2.35, 8.3.36, 8.4.27, 8.5.12; 7.4, 8.0 and 8.1 source patches only; 5.4 to 7.3 no fix"
}

Reply:

{
 "task": "patch-plan",
 "verdict": "update-now",
 "headline": "The Bakery order site is running PHP 8.3.14, which is below the fixed build, so it needs updating to 8.3.36 or later.",
 "steps": [
  {
   "who": "you",
   "do": "Tell the hosting company the Bakery order site's PHP needs to move from 8.3.14 to 8.3.36 or later, share the prepared note, and agree a quiet slot for the change.",
   "check": "The hosting company has confirmed the target build and a quiet slot."
  },
  {
   "who": "host",
   "do": "Update the site's PHP to 8.3.36 or later during the agreed quiet slot.",
   "check": "The hosting control panel shows PHP 8.3.36 or later."
  },
  {
   "who": "you",
   "do": "After the change, open the main pages and place a test cake order to confirm payment still works.",
   "check": "The main pages load and the test order payment goes through."
  },
  {
   "who": "you",
   "do": "Tell the hosting company the checks passed, or describe any problems you find instead.",
   "check": "The hosting company has your confirmation or problem report."
  }
 ],
 "escalate": "If the hosting company does not act or the quiet slot passes without a change, contact them again and ask for a new quiet slot and a status update.",
 "recover": "If the site misbehaves after the change, ask the hosting company to restore it from the backup and confirm the PHP version again before trying the update once more.",
 "note": "To the hosting company: the Bakery order site is on PHP 8.3.14, which is below the fixed build. Please update it to 8.3.36 or later. Customers pay for cake orders on this site, so please check that ordering and payment still work after the change. A backup already exists; please make sure it stays safe during the update. Please agree a quiet slot for the change with the site owner first, since a short outage is not fine. Thank you.",
 "closing": "Moving the Bakery order site to PHP 8.3.36 or later closes the known gap once the hosting company completes the update."
}

Choir newsletter - verdict: backport or move up

Input:

{
 "task": "patch-plan",
 "site": "site: Choir newsletter site | version as given: 7.4.33 | hosting: Managed hosting | who changes the server: A web person (freelancer or agency) | backup: Yes, and a restore has worked | a short outage: A short outage is fine | visitors log in or pay: No | notes: a freelancer built it and still looks after it",
 "facts": "verdict: backport-or-upgrade (line 7.4 got a source patch but no official fixed build)\ntarget: a 7.4 build carrying the backported fix, or a move to 8.2.35, 8.3.36, 8.4.27, 8.5.12 or later\nversion read: 7.4.33\nserver steps belong to: web person\nnote for the person who changes the server: write one, addressed to the web person\npublished fixed builds: 8.2.35, 8.3.36, 8.4.27, 8.5.12; 7.4, 8.0 and 8.1 source patches only; 5.4 to 7.3 no fix"
}

Reply:

{
 "task": "patch-plan",
 "verdict": "backport-or-upgrade",
 "headline": "The Choir newsletter site's PHP line only has a source patch, so it needs a backported build or a move to a fixed build.",
 "steps": [
  {
   "who": "you",
   "do": "Send your web person the note below, asking them to choose a backported build of the current PHP line or a move to one of the newer fixed builds.",
   "check": "Your web person confirms they got the note and picked one of the two options."
  },
  {
   "who": "web person",
   "do": "If moving to a newer line, check the site's own software works with it first; if staying on the current line, prepare the backported build instead.",
   "check": "The software check is finished or the backported build is ready."
  },
  {
   "who": "web person",
   "do": "Apply the backported build or move the server to the chosen fixed build; a short outage during this step is fine.",
   "check": "The PHP build number now matches the option you chose."
  },
  {
   "who": "you",
   "do": "Open the site's main pages to make sure they load normally after the change.",
   "check": "The main pages open without errors."
  }
 ],
 "escalate": "If your web person does not act, contact the hosting company to ask whether they can apply the change instead.",
 "recover": "If the site behaves oddly after the change, ask your web person to restore it from the existing backup and confirm the main pages work again.",
 "note": "To the web person: our PHP version is 7.4.33, on a line that only has a source-level patch, not an official build. Please either prepare a 7.4 build with the backported fix, or move the site to one of the newer fixed builds: 8.2.35, 8.3.36, 8.4.27, 8.5.12, or later. If you move to a newer line, please check the site's own software works with it first. A short outage during the change is fine. Please confirm once the build is updated.",
 "closing": "Choosing a backported build or a move to a newer fixed build will bring the Choir newsletter site onto a supported PHP build."
}

Family photo blog - verdict: move to a supported line

Input:

{
 "task": "patch-plan",
 "site": "site: Family photo blog | version as given: 5.6.40 | hosting: Our own server or VPS | who changes the server: Me | backup: No backup | a short outage: A short outage is fine | visitors log in or pay: No | notes: I set the server up myself years ago",
 "facts": "verdict: upgrade-line (line 5.6 is in the affected range and got no fix)\ntarget: a move to a supported line: 8.2.35, 8.3.36, 8.4.27, 8.5.12 or later\nversion read: 5.6.40\nserver steps belong to: you\nnote for the person who changes the server: none (they change it themselves)\npublished fixed builds: 8.2.35, 8.3.36, 8.4.27, 8.5.12; 7.4, 8.0 and 8.1 source patches only; 5.4 to 7.3 no fix"
}

Reply:

{
 "task": "patch-plan",
 "verdict": "upgrade-line",
 "headline": "The Family photo blog is running PHP 5.6, a line with no fix, so it needs to move to a newer supported line.",
 "steps": [
  {
   "who": "you",
   "do": "Make a backup of the site and its files before you change anything on the server.",
   "check": "A backup copy of the site exists that you have confirmed."
  },
  {
   "who": "you",
   "do": "Check whether the site's own software still works on a newer PHP line, and update it first if it does not.",
   "check": "The site's own software is confirmed to work, or has been updated."
  },
  {
   "who": "you",
   "do": "Move the server to one of the supported lines - 8.2.35, 8.3.36, 8.4.27, 8.5.12 or later; a short outage during this step is fine.",
   "check": "The server reports one of the new build numbers instead of 5.6.40."
  },
  {
   "who": "you",
   "do": "Confirm the new PHP build is active on the server after the move.",
   "check": "The reported build matches the one you moved to."
  },
  {
   "who": "you",
   "do": "Open the main pages of the Family photo blog and check that they load as expected.",
   "check": "The main pages open and look the same as before."
  }
 ],
 "escalate": "Since you are the one who changes the server, if you get stuck on a step, pause and work out the issue fully before moving on, rather than guessing.",
 "recover": "If the Family photo blog does not work properly after the move, stop making further changes and check the site's own software for errors until you find the cause.",
 "note": "",
 "closing": "Moving the Family photo blog to a newer supported PHP line is the way to address the line with no fix."
}

Allotment society - verdict: fixed build

Input:

{
 "task": "patch-plan",
 "site": "site: Allotment society site | version as given: 8.4.27 | hosting: Shared hosting (a control panel) | who changes the server: The hosting company | backup: Yes, and a restore has worked | a short outage: A short outage is fine | visitors log in or pay: Yes | notes: members log in to book plots",
 "facts": "verdict: patched (8.4.27 is at or past the fixed build 8.4.27)\ntarget: stay on 8.4.27 or later\nversion read: 8.4.27\nserver steps belong to: host\nnote for the person who changes the server: write one, addressed to the hosting company\npublished fixed builds: 8.2.35, 8.3.36, 8.4.27, 8.5.12; 7.4, 8.0 and 8.1 source patches only; 5.4 to 7.3 no fix"
}

Reply:

{
 "task": "patch-plan",
 "verdict": "patched",
 "headline": "The Allotment society site is already on PHP build 8.4.27, a published fixed build, so no update is required.",
 "steps": [
  {
   "who": "you",
   "do": "Check the PHP version shown in the hosting control panel for the Allotment society site and confirm it reads build 8.4.27 or later.",
   "check": "The control panel shows PHP build 8.4.27 or later."
  },
  {
   "who": "you",
   "do": "Check that backups of the Allotment society site continue to be made and that a test restore still works.",
   "check": "A backup exists and a test restore has worked."
  },
  {
   "who": "you",
   "do": "Send the note below to the hosting company so they know to keep the site on its current fixed build.",
   "check": "The note has been sent to the hosting company."
  },
  {
   "who": "host",
   "do": "Keep the Allotment society site on PHP build 8.4.27, or move it only to a later published fixed build, during any server work.",
   "check": "The hosting company confirms this in writing."
  },
  {
   "who": "you",
   "do": "Check php.net's release page for the 8.4 line for any new security releases after build 8.4.27.",
   "check": "You have looked at php.net's 8.4 release list."
  }
 ],
 "escalate": "If the hosting company does not reply to the note or confirm the build in writing, contact the hosting company again and ask for a written reply.",
 "recover": "If anything on the site, such as the page where members log in to book plots, stops working, ask the hosting company to restore the latest backup, which has worked when tested.",
 "note": "To the hosting company: the Allotment society site's PHP version has been checked and is already on build 8.4.27, which is a published fixed build, so no update is needed. Please keep the site on build 8.4.27, or move it only to a later published fixed build if any server changes are made. Please confirm this in writing. Thank you.",
 "closing": "The Allotment society site is on a fixed PHP build, and following these steps will help keep it that way."
}

Book swap - verdict: find the version

Input:

{
 "task": "patch-plan",
 "site": "site: Book swap site | version as given: the panel just says 8.x | hosting: Not sure | who changes the server: Not sure | backup: Not sure | a short outage: Not sure | visitors log in or pay: Yes | notes: volunteers took it over from someone else",
 "facts": "verdict: find-version (no version number the page could read)\ntarget: the full three-part version number, from the hosting panel or whoever runs the server\nversion read: none\nserver steps belong to: you (first find out who changes the server)\nnote for the person who changes the server: write one, addressed to the hosting company or web person, whichever changes it\npublished fixed builds: 8.2.35, 8.3.36, 8.4.27, 8.5.12; 7.4, 8.0 and 8.1 source patches only; 5.4 to 7.3 no fix"
}

Reply:

{
 "task": "patch-plan",
 "verdict": "find-version",
 "headline": "The Book swap site's PHP version is not yet known well enough to say whether it needs an update.",
 "steps": [
  {
   "who": "you",
   "do": "Work out who changes the server for the site, such as the hosting company or someone who helps with it, since that is not sure yet.",
   "check": "You know who to contact if a server change turns out to be needed."
  },
  {
   "who": "you",
   "do": "Check the hosting control panel's PHP settings page yourself for the full three-part version number, such as 8.x.xx, rather than just the line, 8.x.",
   "check": "You see a three-part number, or the page does not show one."
  },
  {
   "who": "you",
   "do": "If the panel does not show the full number, send a short note to whoever changes the server asking for it.",
   "check": "You have sent the note, or you already have the number."
  },
  {
   "who": "you",
   "do": "Find out whether a backup of the site exists, or ask for one to be made, since you are not sure one is in place.",
   "check": "You know a backup exists, or one has just been made."
  },
  {
   "who": "you",
   "do": "Once you have the full version number, compare it with the published fixed builds (8.2.35, 8.3.36, 8.4.27, 8.5.12) to see whether it is at, above or below one of them.",
   "check": "You know whether the version is at, above or below a fixed build."
  },
  {
   "who": "you",
   "do": "Once any future change is made, check that the pages where visitors log in or pay still work as before.",
   "check": "Those pages load and let visitors log in or pay as usual."
  }
 ],
 "escalate": "If whoever changes the server does not reply, contact the hosting company directly to ask about the version and who can make changes to it.",
 "recover": "If the site misbehaves after any future change, tell whoever changes the server so they can look into it and undo what they changed if needed.",
 "note": "Hello. This note is for whoever changes the server for the Book swap site. I'm trying to find out the PHP version it is running, since the hosting panel only shows a partial number. Could you tell me the full three-part version number, such as 8.x.xx, and let me know whether you are able to make a server change if one turns out to be needed? Please do not send any passwords or login details, just the version number and your answer. Thank you for your help.",
 "closing": "Finding the full version number is the first step toward knowing what, if anything, the Book swap site needs next."
}

Build the input yourself

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

const K = HullKit;
const form = K.form({ site: "Club booking site", version: "8.2.20", hosting: "shared", updater: "host",
  backup: "tested", downtime: "quiet", visitors: "yes", notes: "" });
const built = K.buildInput(form);       // built.facts holds the verdict, its reason, the target and whose job the server steps are
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, K.title(form))    // the runbook as Markdown

The answer keys: hosting is shared, managed, server or unsure; updater is host, webperson, me or unsure; backup is tested, untested, none or unsure; downtime is ok, quiet or unsure; visitors is yes, no or unsure.

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://patch-the-hull.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":"patch-the-hull"}' | 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": "patch-plan", "site": "site: Bakery order site | version as given: 8.3.14 | ...", "facts": "...", ...}
# - 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 patch-the-hull:<task>:<inputHash>:a<attempt> (the one task is patch-plan), 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="patch-the-hull:patch-plan:$(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: patch-the-hull:patch-plan:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json