Drive Sitemap Desk from your own code

{"host": "example.com", "format": "list", "url_count": 14, "sent_count": 14, "clipped": "",
 "slash_policy": "none", "typical_max_depth": 2, "browser_status": "sound", "flags": []}

// make-body.js - build the run body with the SAME engine the web page uses.
// Save sitekit.js from https://sitemap-desk.skillsafe.ai/sitekit.js next to this file.
// Usage: node make-body.js sitemap.xml
const fs = require("fs");
const K = require("./sitekit.js");

const A = K.analyze({
  site: "Brindlecott Plumbing",
  type: "local",                  // saas, content, ecommerce, docs, hybrid or local
  goals: "Phone calls and booking requests from homeowners in the service area.",
  audiences: "Homeowners in Eugene and Springfield with an urgent or planned plumbing job.",
  key_pages: "/services\n/book",
  nav: "Header: Services, Service areas, About, Book a visit. Footer: Contact, Privacy.",
  inventory: fs.readFileSync(process.argv[2] || "sitemap.xml", "utf8")  // sitemap.xml, crawl CSV or URL list
});
const body = K.buildInput(A, { question: "" });   // a non-empty question is answered in summary
fs.writeFileSync("body.json", JSON.stringify(K.mustBeObject(body)));
console.log(A.flags.length, "flags; browser status", A.hint, "; sent", A.sent.paths.length, "of", A.sent.total);
console.log("Idempotency-Key: sitemap-desk:architect:" + K.hashInput(body) + ":a1");

{"ok": true, "data": {"job_id": "job_...", "status": "queued"}}
{"ok": false, "error": {"code": "payment_required", "message": "..."}}

# Every call is the same three things: the base URL, your bearer token,
# and a JSON body. Keep the token in a shell variable.
BASE="https://api.skillsafe.ai/v1/app-api"
SLUG="sitemap-desk"
TOKEN="$SKILLSAFE_TOKEN"   # from https://sitemap-desk.skillsafe.ai/tokens.html

call() {                  # call <path> [json-body]
  if [ -n "$2" ]; then
    curl -sS -X POST "$BASE/$1" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d "$2"
  else
    curl -sS "$BASE/$1" -H "Authorization: Bearer $TOKEN"
  fi
}

# The token page is the shortest path. It shows the token this browser holds and
# hands you a ready-made shell export:
#
#   https://sitemap-desk.skillsafe.ai/tokens.html
#   export SKILLSAFE_TOKEN="..."
#
# To mint a guest token from the command line instead. A guest token is enough
# for /me and /estimate; a run needs a personal token from signing in.
curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" -d '{"slug":"sitemap-desk"}'
# {"ok":true,"data":{"token":"…","subject_type":"guest"}}

call me
# {"ok":true,"data":{"subject_type":"user","username":"you","credits":51234}}

# body.json is the input object itself - no {"input": ...} wrapper. Build it with
# make-body.js above, or by hand. estimate does not validate it, so check the shape first:
python3 -c 'import json;b=json.load(open("body.json"));assert isinstance(b,dict) and b.get("task")=="architect" and all(isinstance(v,str) for v in b.values()) and all(b.get(k,"").strip() for k in ("site_name","inventory","facts")) and isinstance(json.loads(b["facts"]),dict)'
INPUT=$(cat body.json)

call estimate "$INPUT"
# {"ok":true,"data":{"model":"...","model_alias":"gpt-terra",
#   "markup_bps":1000,"hold_credits":...,"min_credits":...,"sponsor_enabled":false,
#   "warnings":[]}}
#
# estimate creates no job and charges nothing. hold_credits is RESERVED, not the
# price; charged_credits after the run is usually far lower.

# Always send an Idempotency-Key derived from the input. A retried request with
# the same key returns the SAME job instead of billing a second run.
KEY="sitemap-desk:architect:$(printf '%s' "$INPUT" | shasum -a 256 | cut -c1-16):a1"

JOB=$(curl -sS -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["job_id"])')

while :; do
  OUT=$(call "jobs/$JOB")
  STATUS=$(printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["status"])')
  [ "$STATUS" = "succeeded" ] && break
  [ "$STATUS" = "failed" ] && echo "$OUT" && exit 1
  sleep 2
done

# {"ok":true,"data":{"job_id":"job_...","status":"succeeded",
#   "output":{"output":"{\"lane\":\"architect\",\"site\":{...},\"status\":\"sound\", ...}"},
#   "charged_credits":...,"truncated":false}}
printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["output"]["output"])' > reply.json

# Server-sent events. `delta` events carry chunks of the reply; `done` carries the
# status, charged_credits and the truncated flag. Ignore `tick` heartbeats.
curl -N -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -H "Accept: text/event-stream" \
  -d "$INPUT"

# event: job    {"job_id":"job_..."}
# event: delta  {"text":"{\"lane\":\"architect\",\"site\":{\"name\":\"Brindlecott Plumbing\""}
# event: done   {"status":"succeeded","charged_credits":...,"truncated":false}

# reply.json holds data.output.output from step 5. Strip any fence, keep the object:
python3 - <<'EOF'
import json, re
t = open("reply.json").read().strip()
t = re.sub(r"^```(?:json)?\s*", "", t, flags=re.I)
t = re.sub(r"\s*```\s*$", "", t)
r = json.loads(t[t.index("{"):t.rindex("}") + 1])
print(r["status"], "-", r["headline"])
for f in r["findings"]:
    print(f["ref"] or "-", f["severity"], "|", f["finding"], "->", f["fix"])
for h in r["hierarchy"]:
    print("  " * h["level"] + h["path"], h["title"], "*new" if h["is_new"] else "", h["count"] or "")
for x in r["redirects"]:
    print("301", x["from"], "->", x["to"])
print([l["label"] for l in r["navigation"]["header"]], "CTA:", r["navigation"]["cta"]["label"])
EOF

# assert-reply.py - the core checks, for body.json and reply.json from the steps above.
import json, re
body = json.load(open("body.json")); facts = json.loads(body["facts"])
t = open("reply.json").read(); r = json.loads(t[t.index("{"):t.rindex("}") + 1])
S = lambda p: p if p == "/" else p.rstrip("/")
wild = lambda p: p.endswith("/*")
flags = {f["id"]: f for f in facts.get("flags", [])}
ids = [p["id"] for p in r["prescan_responses"]]
assert sorted(ids) == sorted(flags), "every flag answered exactly once"
dismissed = {p["id"] for p in r["prescan_responses"] if p["status"] == "dismissed"}
standing = [f for i, f in flags.items() if i not in dismissed]
rank = ["sound", "tidy_up", "restructure"]
floor = 2 if any(f["severity"] == "high" for f in standing) else 1 if any(f["severity"] == "medium" for f in standing) else 0
assert rank.index(r["status"]) >= floor, "status looser than the flags left standing"
covered = {x for f in r["findings"] for x in re.findall(r"F\d+", f["ref"])}
assert all(f["id"] in covered for f in standing if f["severity"] != "low")
H = r["hierarchy"]; plan = {S(h["path"]) for h in H}
assert "/" in plan, "no homepage node"
for h in H:
    if h["path"] == "/": continue
    par = S(h["parent"] or "/")
    assert par in plan, h["path"] + " has a parent outside the plan"
    assert par == "/" or (S(h["path"]) + "/").startswith(par.removesuffix("/*") + "/"), h["path"] + " does not mirror its parent"
    assert not re.search(r"[A-Z_?]|\.(html?|php|aspx?)$", h["path"]), h["path"] + " breaks the URL rules"
inv = [l.split("\t")[0] for l in body["inventory"].splitlines() if l.strip()]
under = lambda p, w: (p + "/").startswith(w.removesuffix("/*") + "/") and p != w.removesuffix("/*")
in_plan = lambda p: S(p.removesuffix("/*") if wild(p) else p) in plan or any(wild(w) and under(p, w) for w in plan)
R = r["redirects"]
for x in R:
    assert (any(under(p, x["from"]) for p in inv) if wild(x["from"]) else x["from"] in inv), "redirect from outside the inventory: " + x["from"]
    assert in_plan(x["to"]), "redirect to a page not in the plan: " + x["to"]
    assert x["from"] != x["to"], "self-redirect"
froms = [x["from"] for x in R]
assert len(froms) == len(set(froms)), "a URL is redirected twice"
assert not any(x["to"] in froms for x in R if not wild(x["to"])), "redirect chain"
nav = r["navigation"]
for l in nav["header"] + [nav["cta"]] + [l for g in nav["footer"] for l in g["links"]]:
    assert not l.get("path") or S(l["path"]) in plan, "nav link outside the plan: " + l["path"]
skip = set(facts.get("utility_urls", [])) | {l.split("\t")[0] for l in body["inventory"].splitlines() if "\tstatus=" in l}
lost = [p for p in inv if p not in skip and not in_plan(p.split("?")[0]) and not any(p == x["from"] or (wild(x["from"]) and under(p, x["from"])) for x in R)]
assert not lost, "inventory URLs neither kept nor redirected: " + ", ".join(lost[:5])

{"lane":"architect",
 "site":{"name":"...","type":"saas|content|ecommerce|docs|hybrid|local"},
 "status":"sound|tidy_up|restructure",
 "headline":"...","summary":"...",
 "findings":[{"ref":"F1, F4","severity":"high|medium|low","finding":"...","fix":"..."}],
 "hierarchy":[
  {"path":"/","title":"Homepage","parent":"","level":0,"nav":"none","priority":"high","is_new":false,"count":null},
  {"path":"/features","title":"Features","parent":"/","level":1,"nav":"header|header_dropdown|footer|sidebar|none","priority":"high|medium|low","is_new":true,"count":null},
  {"path":"/blog/*","title":"Blog posts","parent":"/blog","level":2,"nav":"none","priority":"medium","is_new":false,"count":212}],
 "redirects":[
  {"from":"/Product/Analytics","to":"/features/analytics","reason":"..."},
  {"from":"/resources/*","to":"/library/*","reason":"the whole folder moves, rest of the path kept"}],
 "navigation":{"header":[{"label":"Features","path":"/features"}],
  "cta":{"label":"Start free trial","path":"/signup"},
  "footer":[{"group":"Company","links":[{"label":"About","path":"/about"}]}],
  "breadcrumbs":"..."},
 "linking":{"hubs":[{"hub":"/features","spokes":["/features/analytics"]}],
  "cross_links":[{"from":"/features/analytics","to":"/customers/acme","anchor":"..."}],
  "orphans":[{"path":"/old-page","link_from":["/blog"]}]},
 "next_steps":["..."],
 "prescan_responses":[{"id":"F1","status":"confirmed|dismissed","reason":"..."}]}

{
 "task": "architect",
 "site_name": "Brindlecott Plumbing",
 "site_type": "local",
 "goals": "Phone calls and booking requests from homeowners in the service area.",
 "audiences": "Homeowners in Eugene and Springfield with an urgent or planned plumbing job.",
 "key_pages": "/services\n/book",
 "current_nav": "Header: Services, Service areas, About, Book a visit. Footer: Contact, Privacy.",
 "inventory": "/\n/services\n/services/drain-cleaning\n/services/water-heaters\n/services/leak-repair\n/services/emergency-plumbing\n/service-areas\n/service-areas/eugene\n/service-areas/springfield\n/about\n/reviews\n/book\n/contact\n/privacy",
 "facts": "{\"host\":\"brindlecottplumbing.example\",\"hosts\":[\"brindlecottplumbing.example\"],\"format\":\"urlset\",\"url_count\":14,\"sent_count\":14,\"clipped\":\"\",\"slash_policy\":\"none\",\"max_depth\":2,\"depth_counts\":{\"0\":1,\"1\":7,\"2\":6},\"typical_max_depth\":2,\"sections\":[{\"path\":\"/services\",\"pages\":5,\"hub\":true,\"children\":4},{\"path\":\"/service-areas\",\"pages\":3,\"hub\":true,\"children\":2},{\"path\":\"/about\",\"pages\":1,\"hub\":true,\"children\":0},{\"path\":\"/reviews\",\"pages\":1,\"hub\":true,\"children\":0},{\"path\":\"/book\",\"pages\":1,\"hub\":true,\"children\":0},{\"path\":\"/contact\",\"pages\":1,\"hub\":true,\"children\":0},{\"path\":\"/privacy\",\"pages\":1,\"hub\":true,\"children\":0}],\"folders_without_hub\":[],\"has_inlinks\":false,\"orphans\":[],\"key_pages\":[{\"path\":\"/services\",\"found\":true,\"depth\":1},{\"path\":\"/book\",\"found\":true,\"depth\":1}],\"expected_missing\":[],\"browser_status\":\"sound\",\"flags\":[]}",
 "question": ""
}

{
 "host": "brindlecottplumbing.example",
 "hosts": [
  "brindlecottplumbing.example"
 ],
 "format": "urlset",
 "url_count": 14,
 "sent_count": 14,
 "clipped": "",
 "slash_policy": "none",
 "max_depth": 2,
 "depth_counts": {
  "0": 1,
  "1": 7,
  "2": 6
 },
 "typical_max_depth": 2,
 "sections": [
  {
   "path": "/services",
   "pages": 5,
   "hub": true,
   "children": 4
  },
  {
   "path": "/service-areas",
   "pages": 3,
   "hub": true,
   "children": 2
  },
  {
   "path": "/about",
   "pages": 1,
   "hub": true,
   "children": 0
  },
  {
   "path": "/reviews",
   "pages": 1,
   "hub": true,
   "children": 0
  },
  {
   "path": "/book",
   "pages": 1,
   "hub": true,
   "children": 0
  },
  {
   "path": "/contact",
   "pages": 1,
   "hub": true,
   "children": 0
  },
  {
   "path": "/privacy",
   "pages": 1,
   "hub": true,
   "children": 0
  }
 ],
 "folders_without_hub": [],
 "has_inlinks": false,
 "orphans": [],
 "key_pages": [
  {
   "path": "/services",
   "found": true,
   "depth": 1
  },
  {
   "path": "/book",
   "found": true,
   "depth": 1
  }
 ],
 "expected_missing": [],
 "browser_status": "sound",
 "flags": []
}

{
 "lane": "architect",
 "site": {
  "name": "Brindlecott Plumbing",
  "type": "local"
 },
 "status": "sound",
 "headline": "The 14-page structure is already flat, consistent and within two levels, so no URL should change; the most valuable move is to put Book a visit in a separate rightmost header CTA and cross-link every service page with the Eugene and Springfield area pages.",
 "summary": "The site is in good shape: every page sits at depth 1 or 2, both folders (/services and /service-areas) have hub pages, all paths are lowercase, hyphenated and follow one no-trailing-slash style, and both key pages (/services and …",
 "findings": [
  {
   "ref": "",
   "severity": "low",
   "finding": "The current header lists Book a visit alongside ordinary sections, and Reviews and Contact are missing from it even though phone calls and bookings are the site's goals and reviews are the main trust signal for a local trade.",
   "fix": "Header: Services, Service areas, Reviews, About, Contact, with Book a visit as a separate button at the far right."
  },
  {
   "ref": "",
   "severity": "low",
   "finding": "The footer holds only Contact and Privacy, so the service and area pages that a homeowner scans for at the bottom of a page are not reachable from it.",
   "fix": "Group the footer into Services, Service areas and Company columns, linking all four service pages, both area pages, and About, Reviews, Contact and Privacy."
  }
 ],
 "hierarchy": [
  {
   "path": "/",
   "title": "Homepage",
   "parent": "",
   "level": 0,
   "nav": "none",
   "priority": "high",
   "is_new": false,
   "count": null
  },
  {
   "path": "/services",
   "title": "Services",
   "parent": "/",
   "level": 1,
   "nav": "header",
   "priority": "high",
   "is_new": false,
   "count": null
  },
  {
   "path": "/services/emergency-plumbing",
   "title": "Emergency plumbing",
   "parent": "/services",
   "level": 2,
   "nav": "footer",
   "priority": "high",
   "is_new": false,
   "count": null
  },
  {
   "path": "/service-areas",
   "title": "Service areas",
   "parent": "/",
   "level": 1,
   "nav": "header",
   "priority": "high",
   "is_new": false,
   "count": null
  },
  {
   "path": "/service-areas/eugene",
   "title": "Eugene",
   "parent": "/service-areas",
   "level": 2,
   "nav": "footer",
   "priority": "high",
   "is_new": false,
   "count": null
  },
  {
   "path": "/book",
   "title": "Book a visit",
   "parent": "/",
   "level": 1,
   "nav": "header",
   "priority": "high",
   "is_new": false,
   "count": null
  }
 ],
 "redirects": [],
 "navigation": {
  "header": [
   {
    "label": "Services",
    "path": "/services"
   },
   {
    "label": "Service areas",
    "path": "/service-areas"
   },
   {
    "label": "Reviews",
    "path": "/reviews"
   },
   {
    "label": "About",
    "path": "/about"
   },
   {
    "label": "Contact",
    "path": "/contact"
   }
  ],
  "cta": {
   "label": "Book a visit",
   "path": "/book"
  },
  "footer": [
   {
    "group": "Service areas",
    "links": [
     {
      "label": "Eugene",
      "path": "/service-areas/eugene"
     },
     {
      "label": "Springfield",
      "path": "/service-areas/springfield"
     }
    ]
   }
  ],
  "breadcrumbs": "Show breadcrumbs on level-2 pages only, mirroring the URL, for example Home > Services > Water heaters and Home > Service areas > Eugene; level-1 pages do not need them."
 },
 "linking": {
  "hubs": [
   {
    "hub": "/service-areas",
    "spokes": [
     "/service-areas/eugene",
     "/service-areas/springfield"
    ]
   }
  ],
  "cross_links": [
   {
    "from": "/service-areas/eugene",
    "to": "/services/emergency-plumbing",
    "anchor": "emergency plumbing in Eugene"
   },
   {
    "from": "/service-areas/springfield",
    "to": "/services/water-heaters",
    "anchor": "water heater repair and replacement in Springfield"
   }
  ],
  "orphans": []
 },
 "next_steps": [
  "Keep all 14 URLs unchanged; no redirects are needed and the no-trailing-slash style is already consistent.",
  "Rebuild the header as Services, Service areas, Reviews, About, Contact, with Book a visit as a separate rightmost button on every page."
 ],
 "prescan_responses": []
}