← Paywall Desk / API
Tokens

Drive Paywall Desk from your own code

The page does its free work in the browser: it reads the copy of an in-app paywall or upgrade screen (buttons in [brackets]) and its context, names the trigger point, finds which of the seven paywall components are on the screen, classifies every button, checks a stated annual saving against the prices, computes the funnel rates and raises flags PW-01..PW-20. Its two paid lanes are available over HTTP. You send one JSON object with task set to "audit" or "redesign", and the model replies with one JSON object. The easiest way to build the facts string is the page itself: Paykit.buildInput(lane, Paykit.analyze(screen, {context, trigger, question}), {auditHandoff}) in paykit.js, which also runs under Node.

Base URL: https://api.skillsafe.ai/v1/app-api. Every call sends Content-Type: application/json and, once you have a token, Authorization: Bearer <token>. Both lanes run on gpt-terra with a 10% publisher markup. A run needs a signed-in (user) token and is metered: the platform holds the estimate's hold_credits while the run is in flight and then charges only what it used (charged_credits). /estimate is free. A plain-text summary is at /llms.txt.

The response envelope

Every response is {"data": ..., "error": null} on success or {"data": null, "error": {"code", "message"}} on failure.

Error codes

HTTPcodemeaning
400VALIDATION_ERRORThe body is not a JSON object, or a field is the wrong type. Every field of the run input is a string.
401UNAUTHORIZEDNo token, or an expired one: get a new one (step 2).
402INSUFFICIENT_CREDITSThe balance is below the run's minimum. Top up at skillsafe.ai/account/billing/.
403FORBIDDENA guest token tried a metered run: sign in for a personal token.
404NOT_FOUNDUnknown job id.
429RATE_LIMITEDBack off and retry with the same Idempotency-Key.

The task field: two lanes

taskwhat the model does
"audit"The paywall audit: whether it is in scope (an in-app moment, not a public pricing page); the trigger point; the moment (what the user feels, whether value came before the ask); the seven components (headline, value_demo, comparison, pricing, social_proof, cta, escape_hatch) each strong, weak or missing with a fix; the issues (dark patterns, conversion killers, timing, frequency, pricing, copy) with the page's flag ids; the frequency verdict and rules; the funnel read and its leak; 3 to 6 fixes in order; a verdict ship, fix_first, rebuild or out_of_scope.
"redesign"The screen rewritten for its trigger: headline, subhead, value demonstration, a free-versus-paid comparison, the price line from your prices, social proof (or a placeholder), a call to action that names the benefit and a neutral way out; 2 to 4 variants; when, never-when, per-session cap and a cool-down in days; trial reminders at 7, 3 and 1 days for a trial; what happens after the upgrade; 2 to 4 tests with their metrics.

Input fields (all strings)

fieldwhencontent
taskrequiredaudit or redesign
screenrequiredThe screen's copy, verbatim, buttons in [brackets]. Past 6,000 characters the page cuts the middle on line boundaries and leaves a [paywall-desk: ...] marker.
factsrequiredA JSON string: summary, trigger (type, basis, evidence), components (found, evidence, note for each of the seven), found, buttons (text, kind cta|escape|other, generic, shaming), cta, escape, prices (amount, currency, period, billed_annually, raw, source), plans, annual (basis, monthly, annual_total, annual_per_month, twelve_months, saving_amount, saving_pct, stated_pct, matches), funnel (impressions, clicks, upgrades, free_users, stated_rate, ctr, completion, overall, free_to_paid, reach, biggest_drop), scope, flags, notes. It is Paykit.factsOf(A).
contextoptionalThe product, what is free and paid, prices, what triggers the screen, when and how often, numbers. Cut past 4,000 characters.
triggeroptionalfeature_gate, usage_limit, trial_expiration, time_based or tier_upgrade, when the user chose it.
questionoptionalWhat the user wants to know.
audit_handoffredesign onlyA JSON string of an audit's trigger, verdict, missing[], weak[], issues[{flag, issue, fix}] and fixes[], for the same input.
retry_noteoptionalOnly on a reformat retry: what was wrong with the previous reply.

The reply contracts

Both lanes share an envelope: task, headline, questions[], summary.

task: "audit"

scope{in_scope, note}, trigger{type: feature_gate|usage_limit|trial_expiration|time_based|tier_upgrade|unclear, why, evidence[]}, moment{user_state, value_before_ask: yes|no|unclear, why}, components[{component, status: strong|weak|missing, finding, evidence[], fix}] (exactly seven, in order), issues[{flag, kind: dark_pattern|conversion_killer|timing|frequency|pricing|copy, severity: high|medium|low, issue, evidence[], fix}], frequency{verdict: ok|too_often|unknown, rules[]}, numbers{read, leak: impression_to_click|click_to_upgrade|unknown}, fixes[] (3 to 6), verdict (ship|fix_first|rebuild|out_of_scope).

task: "redesign"

source (audit handoff|from the input), trigger, screen{headline, subhead, value_demo, comparison[{feature, free, paid}], pricing, social_proof, cta, escape_hatch, note}, variants[{element: headline|cta|value_demo|pricing, text, angle: benefit|loss|social|usage}] (2 to 4), rules{show_when[], never_when[], per_session, cooldown}, sequence[{when, channel: email|in-app|push, message}] (trial expiration only), after_upgrade[], tests[{test, hypothesis, metric, variant}] (2 to 4), metrics[].

Worked examples

These are the page's own bundled examples (invented products and numbers), with the input as app.js builds it and the saved model reply the page replays for free.

Audit: a project-limit wall with a lone "Upgrade" button

Input (screen and facts shortened here):

{
 "task": "audit",
 "screen": "You've reached your project limit\n\nFree accounts can have 3 projects.\n\n[Upgrade]\n",
 "facts": "(a JSON string; decoded: trigger usage_limit (read from the context), 2 of 7 components - missing: value_demo, comparison, pricing, social_proof, escape_hatch, cta \"Upgrade\", escape null, prices $12/month, $120/year, $24/month, annual saving 16.7%, funnel ctr 6.47%, completion 13.14%, flags PW-01, PW-03, PW-04, PW-05, PW-06, PW-09, PW-07, PW-08)",
 "context": "Tasquarrow - project management for small agencies. Free plan: 3 projects, 2 members, no time tracking. Pro: $12/month per seat, or $120/year per seat. Team: $24/month per seat.\nThe modal appears when a free user clicks \"New project\" with 3 projects already open. It blocks the new-project form; the only button is Upgrade, and the user has to press Escape or reload to get back to their board.\nLast 30 days: 4,820 paywa... (571 characters in all)",
 "question": "Why do so few people upgrade at the 4th project?"
}

Reply:

{
 "task": "audit",
 "scope": {
  "in_scope": true,
  "note": ""
 },
 "trigger": {
  "type": "usage_limit",
  "why": "The modal fires when a free user clicks New project with 3 projects already open, the Free plan's project cap.",
  "evidence": [
   "The modal appears when a free user clicks \"New project\" with 3 projects already open",
   "Free accounts can have 3 projects."
  ]
 },
 "moment": {
  "user_state": "The user is mid-task, starting a new project for their agency, usually right after inviting a second teammate. The modal stops them cold, so they are frustrated and their attention is on the work, not on plans.",
  "value_before_ask": "yes",
  "why": "The wall is hit after real use: three projects already open and a teammate invited, typically in week 2."
 },
 "components": [
  {
   "component": "headline",
   "status": "weak",
   "finding": "The headline only states the limit and says nothing about what Pro would let the team do next.",
   "evidence": [
    "You've reached your project limit"
   ],
   "fix": "Lead with the benefit, for example \"Keep every client project in one place with Pro\"."
  },
  {
   "component": "value_demo",
   "status": "missing",
   "finding": "Nothing shows what the user has built or what Pro adds, such as more projects, more members or time tracking.",
   "evidence": [],
   "fix": "Show the user's three current projects and an empty slot for the fourth they were about to create."
  },
  {
   "component": "comparison",
   "status": "missing",
   "finding": "The user cannot see what Free and Pro differ on, even though the context names the three limits.",
   "evidence": [],
   "fix": "Add a short Free versus Pro table: projects, members and time tracking."
  },
  {
   "component": "pricing",
   "status": "missing",
   "finding": "
... (shortened here; the page shows it whole)

Redesign: the same wall, carrying the audit

Input (with the audit handed over):

{
 "task": "redesign",
 "screen": "You've reached your project limit\n\nFree accounts can have 3 projects.\n\n[Upgrade]\n",
 "facts": "(a JSON string; decoded: trigger usage_limit (read from the context), 2 of 7 components - missing: value_demo, comparison, pricing, social_proof, escape_hatch, cta \"Upgrade\", escape null, prices $12/month, $120/year, $24/month, annual saving 16.7%, funnel ctr 6.47%, completion 13.14%, flags PW-01, PW-03, PW-04, PW-05, PW-06, PW-09, PW-07, PW-08)",
 "context": "Tasquarrow - project management for small agencies. Free plan: 3 projects, 2 members, no time tracking. Pro: $12/month per seat, or $120/year per seat. Team: $24/month per seat.\nThe modal appears when a free user clicks \"New project\" with 3 projects already open. It blocks the new-project form; the only button is Upgrade, and the user has to press Escape or reload to get back to their board.\nLast 30 days: 4,820 paywa... (571 characters in all)",
 "question": "Why do so few people upgrade at the 4th project?",
 "audit_handoff": "{\"trigger\":\"usage_limit\",\"verdict\":\"rebuild\",\"missing\":[\"value_demo\",\"comparison\",\"pricing\",\"social_proof\",\"escape_hatch\"],\"weak\":[\"headline\",\"cta\"],\"issues\":[{\"flag\":\"PW-01\",\"issue\":\"The modal has no escape hatch, so it works as a hard block on the free plan.\",\"fix\":\"Add a \\\"Not now\\\" button that closes the modal and ..."
}

Reply:

{
 "task": "redesign",
 "source": "audit handoff",
 "trigger": "usage_limit",
 "screen": {
  "headline": "Keep every client project on one board with Pro",
  "subhead": "Your Free plan holds 3 projects; Pro lets your team open the next one now, without closing anything.",
  "value_demo": "Show the user's own board with their 3 projects plus a greyed-in 4th card titled with what they were creating, and a time tracking column switched on: \"This is your board on Pro.\"",
  "comparison": [
   {
    "feature": "Projects",
    "free": "3 projects",
    "paid": "[Pro project limit]"
   },
   {
    "feature": "Members",
    "free": "2 members",
    "paid": "[Pro member limit]"
   },
   {
    "feature": "Time tracking",
    "free": "Not included",
    "paid": "[Pro time tracking]"
   }
  ],
  "pricing": "Pro: $12/month per seat, or $120/year per seat (save $24 a seat, 16.7%).",
  "social_proof": "[customer quote from an agency on Pro] or \"[number of agencies on Pro] agencies run their client work on Tasquarrow Pro\"",
  "cta": "Create my 4th project with Pro",
  "escape_hatch": "Not now, back to my board",
  "note": "Prefer to stay on Free? Archive a project to make room, and nothing you have built is lost."
 },
 "variants": [
  {
   "element": "headline",
   "text": "Your team is growing. Give every client its own project.",
   "angle": "usage"
  },
  {
   "element": "cta",
   "text": "Unlock more projects for my team",
   "angle": "benefit"
  },
  {
   "element": "value_demo",
   "text": "Show the user's 3 project names with a line: \"Your 4th project is one step away; don't squeeze it into an old one.\"",
   "angle": "loss"
  },
  {
   "element": "pricing",
   "text": "Pro from $10 a seat per month, billed $120/year per seat.",
   "angle": "benefit"
  }
 ],
 "rules": {
  "s
... (shortened here; the page shows it whole)

Audit: a trial-expired screen converting at 2%

Input:

{
 "task": "audit",
 "screen": "Your trial has expired\n\nYour 14-day free trial of Quillorn Pro has ended. To keep using Quillorn, choose a plan.\n\nMonthly - $15/month\nAnnual - $144/year (save 25%)\n\n[Choose a plan]\n[Log out]\n",
 "facts": "(a JSON string; decoded: trigger trial_expiration (chosen on the page), 3 of 7 components - missing: value_demo, comparison, social_proof, escape_hatch, cta \"Choose a plan\", escape null, prices $15/month, $144/year, annual saving 20%, funnel read, flags PW-01, PW-04, PW-05, PW-06, PW-09, PW-15, PW-18, PW-19, PW-08)",
 "context": "Quillorn - a writing app for newsletter writers. 14-day free trial of Pro, no card required. After the trial, the account drops to Free (3 drafts, no scheduling, no custom domain).\nUsers see this full-screen page the first time they open the app after day 14. There is no email or in-app reminder before the trial ends.\nTrial users who reach day 14: 2,300 a month. Upgrade rate from this screen is 2%.\nTrial users write ... (480 characters in all)",
 "trigger": "trial_expiration"
}

Reply:

{
 "task": "audit",
 "scope": {
  "in_scope": true,
  "note": ""
 },
 "trigger": {
  "type": "trial_expiration",
  "why": "The trigger was chosen on the page, and the screen fires the first time the user opens the app after the 14-day Pro trial ends.",
  "evidence": [
   "Your 14-day free trial of Quillorn Pro has ended",
   "the first time they open the app after day 14"
  ]
 },
 "moment": {
  "user_state": "A newsletter writer opens Quillorn to keep working on drafts and is stopped by a full-screen wall with no warning, so they are surprised and mid-task.",
  "value_before_ask": "yes",
  "why": "The ask comes after a full trial in which users write on average 9 drafts and schedule 4 issues, so value came first; the problem is the surprise, not the timing."
 },
 "components": [
  {
   "component": "headline",
   "status": "weak",
   "finding": "The headline states the lock, not what the writer keeps by upgrading.",
   "evidence": [
    "Your trial has expired"
   ],
   "fix": "Lead with the benefit, such as \"Keep scheduling your newsletter with Quillorn Pro\"."
  },
  {
   "component": "value_demo",
   "status": "missing",
   "finding": "Nothing shows the drafts and scheduled issues the writer created during the trial.",
   "evidence": [],
   "fix": "Show the user's own trial usage: [drafts written] drafts and [issues scheduled] scheduled issues, plus what is affected on Free."
  },
  {
   "component": "comparison",
   "status": "missing",
   "finding": "The screen never says the account drops to Free or what Free keeps, so it reads as a full lockout.",
   "evidence": [],
   "fix": "Add a short Free versus Pro table: 3 drafts, no scheduling and no custom domain on Free against Pro."
  },
  {
   "component": "pricing",
   "status": "weak",
   "finding": "Both prices ar
... (shortened here; the page shows it whole)

Audit: a fitness paywall with guilt-trip copy and a restarting timer

Input:

{
 "task": "audit",
 "screen": "[Hero image: athlete mid-sprint]\nUnlock your best body with Stridevane Premium\n\nPersonalized plans, advanced stats, and 400+ guided workouts.\nJoin 2 million athletes\n\nOFFER ENDS IN 09:59\n$59.99/year - just $4.99/month (save 70%)\n$9.99/month\n\n[Start my 7-day free trial]\nNo thanks, I don't want to get fit\n",
 "facts": "(a JSON string; decoded: trigger unclear (not read), 6 of 7 components - missing: comparison, cta \"Start my 7-day free trial\", escape \"No thanks, I don't want to get fit\", prices $59.99/year, $4.99/month, $9.99/month, annual saving 50%, funnel none, flags PW-02, PW-03, PW-10, PW-11, PW-09, PW-15, PW-16)",
 "context": "Stridevane - a mobile fitness app (iOS and Android). The paywall shows on the first launch, straight after the onboarding quiz, before the user has done a workout.\nThe close X appears after 5 seconds in the top corner, in light grey.\nIt shows again every app open until they subscribe or close it 3 times.\nThe countdown restarts at 10 minutes every time the paywall opens.\n",
 "question": "Is this paywall hurting us?"
}

Reply:

{
 "task": "audit",
 "scope": {
  "in_scope": true,
  "note": ""
 },
 "trigger": {
  "type": "time_based",
  "why": "The page's scan said unclear, but the context says it fires on a moment in the app's lifecycle (first launch, after the onboarding quiz, then every app open), not at a feature gate, a usage limit or a trial end, so time-based is the closest type.",
  "evidence": [
   "The paywall shows on the first launch, straight after the onboarding quiz",
   "It shows again every app open until they subscribe or close it 3 times."
  ]
 },
 "moment": {
  "user_state": "A brand-new user has just answered the onboarding quiz and expects to see their plan or start a first workout; instead they hit a full-screen ask before Stridevane has shown them anything.",
  "value_before_ask": "no",
  "why": "PW-10: the context says it shows before the user has done a workout, so there is no aha moment yet to build the ask on."
 },
 "components": [
  {
   "component": "headline",
   "status": "strong",
   "finding": "It leads with what the user gets and names the plan, Stridevane Premium.",
   "evidence": [
    "Unlock your best body with Stridevane Premium"
   ],
   "fix": ""
  },
  {
   "component": "value_demo",
   "status": "weak",
   "finding": "A stock hero image of an athlete tells rather than shows; the user sees nothing of their own plan or stats.",
   "evidence": [
    "[Hero image: athlete mid-sprint]"
   ],
   "fix": "Replace the hero with a preview of the personalized plan built from the user's quiz answers, with the Premium parts visibly locked."
  },
  {
   "component": "comparison",
   "status": "missing",
   "finding": "Nothing says what the free app keeps and what only Premium adds, so the user cannot tell what they lose by saying no.",
   "evidence": [],
   "fix": "
... (shortened here; the page shows it whole)

Redesign: a feature gate for Advanced Analytics

Input:

{
 "task": "redesign",
 "screen": "Advanced Analytics is a Pro feature\n\n[Lock icon]\n\nUpgrade to Pro to use Advanced Analytics.\n\n[Upgrade to Pro - $29/mo]\n[Close]\n",
 "facts": "(a JSON string; decoded: trigger feature_gate (chosen on the page), 4 of 7 components - missing: value_demo, comparison, social_proof, cta \"Upgrade to Pro - $29/mo\", escape \"Close\", prices $29/mo, $29/month, $290/year, annual saving 16.7%, funnel none, flags PW-06, PW-09, PW-08)",
 "context": "Tallymorrow - a dashboard tool for Shopify stores. Free: the overview dashboard, 30 days of history, 1 store. Pro ($29/month or $290/year): Advanced Analytics (cohort retention, LTV by channel, product affinity), 2 years of history, 5 stores, scheduled email reports.\nThe gate opens when a free user clicks the \"Advanced Analytics\" tab in the sidebar.\nAbout 1,400 stores on Pro. Pro users open Advanced Analytics on 68% ... (440 characters in all)",
 "trigger": "feature_gate"
}

Reply:

{
 "task": "redesign",
 "source": "from the input",
 "trigger": "feature_gate",
 "screen": {
  "headline": "See which channels bring your most valuable customers",
  "subhead": "Advanced Analytics adds cohort retention, LTV by channel and product affinity to your Tallymorrow dashboard.",
  "value_demo": "Show a blurred preview of the LTV by channel and cohort retention charts built from this store's own last 30 days, with the caption: \"Your store's channels, ranked by lifetime value. Unlock to see the full numbers.\"",
  "comparison": [
   {
    "feature": "Advanced Analytics (cohort retention, LTV by channel, product affinity)",
    "free": "Not included",
    "paid": "Included"
   },
   {
    "feature": "History",
    "free": "30 days",
    "paid": "2 years"
   },
   {
    "feature": "Stores",
    "free": "1 store",
    "paid": "5 stores"
   },
   {
    "feature": "Scheduled email reports",
    "free": "Not included",
    "paid": "Included"
   }
  ],
  "pricing": "Pro: $29/month, or $290/year billed annually.",
  "social_proof": "About 1,400 stores on Pro. Pro users open Advanced Analytics on 68% of weekly sessions.",
  "cta": "Start seeing LTV by channel",
  "escape_hatch": "Continue with Free",
  "note": "Your overview dashboard stays free. [cancellation terms]"
 },
 "variants": [
  {
   "element": "headline",
   "text": "Find out which customers come back and why",
   "angle": "benefit"
  },
  {
   "element": "headline",
   "text": "Join about 1,400 stores on Pro",
   "angle": "social"
  },
  {
   "element": "cta",
   "text": "Unlock Advanced Analytics for $29/month",
   "angle": "benefit"
  },
  {
   "element": "pricing",
   "text": "$290/year for Pro, or $29/month",
   "angle": "benefit"
  }
 ],
 "rules": {
  "show_when": [
   "A free user clicks the \"Advanced 
... (shortened here; the page shows it whole)

The page re-checks the reply; the API does not

The page holds every reply to account (recon.js): for an audit, the trigger you chose kept, seven components in order, none called present that the page found missing without a quote and none called strong that the page faults, every high-severity flag carried and never downgraded, value before ask never "yes" when the page flagged an early prompt, frequency never "ok" when flagged, the funnel leak equal to the page's, no "ship" while a high flag stands, and a public page left unoptimised. For a redesign, every screen element written, a benefit headline, a call to action that is not generic, a neutral way out, comparison rows from your features, only your prices and only the real saving, a cool-down in days, reminders at 7, 3 and 1 days for a trial, and tests with metrics. In both, quotes are checked word for word and no price, count, rate, duration or social-proof number may be invented. Over the API you get the model's reply as it is; run the same checks yourself with Recon.reconcile in recon.js, or paste the same input into the page.

Step 1 — a tiny client helper

One function that sends JSON and unwraps the envelope.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://paywall-desk.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":"paywall-desk"}' | 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 reads gpt-5.6-terra and model_alias gpt-terra.

# input.json: the run input object - {"task": "audit", "screen": "...", "context": "...", "facts": "..."}
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 paywall-desk:<lane>:<inputHash>:a<attempt>. The job's output.output is the reply text; truncated: true means the balance cut it short.

KEY="paywall-desk:audit:$(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 lane's contract
echo "$J" | jq '.data | {charged_credits, truncated}'

Step 6 — POST /run-stream (redesign)

The same run as Server-Sent Events. redesign.json is a redesign input, with audit_handoff when it follows an audit.

# 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: paywall-desk:redesign:$(shasum -a 256 redesign.json | cut -c1-16):a1" --data @redesign.json