← Pitch Desk / API
Tokens

Drive Pitch Desk from your own code

The page does its free work in the browser: it reads a story (notes, numbers, quotes or a draft pitch email) and optional notes on the journalist against the seven-item pitch quality bar (beat match, news hook, a complete story, a specific subject line, under 150 words, no banned words, a clear ask), counts the signals for seven story angles, measures a draft's subject line and body, and raises flags PD-01..PD-18. Its two paid lanes are available over HTTP. You send one JSON object with task set to "angle" or "pitch", and the model replies with one JSON object. The easiest way to build the facts string is the page itself: Pitchkit.buildInput(lane, Pitchkit.analyze(story, {target, ask}), {angle, angleHandoff}) in pitchkit.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
"angle"The story check: the story restated in plain language; a verdict (pitch it, not yet or skip PR for now); the angle it bends toward (founding, goliath, enemy, data, customer, newsjack, trend, or none) with quotes; the hook; why it matters to the journalist's readers; the seven-item quality bar graded pass, fail or unknown with quotes; what is missing and how to get it this week; the pitch template to use; and two or three subject lines under 50 characters.
"pitch"The pitch email: a subject under 50 characters that predicts the headline, a body of 150 words or fewer from greeting to sign-off with [placeholders] for what only the sender knows, one clear ask (copied from the body), the story facts it rests on, follow-ups on day 3 and day 7 that each bring something new, and what to check before sending.

Input fields (all strings)

fieldwhencontent
taskrequiredangle or pitch
storyrequiredThe story, verbatim: notes, numbers, quotes, a draft pitch. Past 12,000 characters the page cuts the middle on a line boundary and leaves a [pitch-desk: ...] marker.
factsrequiredA JSON string: summary, has_pitch, subject (text, chars, deleted, prefix), body_words, bar (id, status: met|unclear|not met, why, evidence with line, label, quote, where), angles (id, hits, evidence), angle_hint, signals, banned, killers, target (given, name, recent_pieces, no_pitches), numbers, flags (uid, id, sev, ref, name), notes. It is Pitchkit.factsOf(A).
targetoptionalNotes on the journalist, up to 4,000 characters: name, outlet, beat, recent pieces one per line.
askoptionalinterview, exclusive, embargo, quote, oped, data or call.
anglepitch onlyOne of the seven angle ids. Without it the run pitches the story check's angle, or the strongest the story supports.
angle_handoffpitch onlyA JSON string of a story check's verdict, angle{id}, hook{text}, reader_why, template and missing[{item}], for the same story.
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: "angle"

story_plain{what, who, when, proof}, verdict (pitch it|not yet|skip PR for now), verdict_why, angle{id, why, evidence[]}, hook{text, evidence[]}, reader_why, bar[{id, status: pass|fail|unknown, evidence[], note}] (seven, in order: beat, hook, complete, subject, length, vocabulary, ask), missing[{item, why, get}], template (data|exclusive|oped|customer|trend|newsjack), subject_ideas[].

task: "pitch"

angle, template, source (given|angle handoff|picked from the story), subject, body, ask{type, text}, facts_used[{quote, as}], follow_ups[{day: 3|7, text, new}], before_sending[].

Worked examples

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

Story check: a deploy-data report with a reporter in mind

Input (story and facts shortened here):

{
 "task": "angle",
 "story": "# Story notes: the Friday deploy\n\nQuenbrook CI is a four-person company that runs build pipelines for small engineering teams.\n\nLast month we analyzed 41,212 production deploys from 1,180 teams that use Quenbrook (anonymized, opt-in).\n\nWhat we found:\n- 31% of all production deploys happen on a Friday, more than any other day.\n- Friday deploys are rolled back 2.4 times as often as Tuesday deploys.\n- Teams with fewer than 10 engineers ship 44% of their deploys after 3pm on Fridays.\n\nOur report, \"T... (836 characters in all)",
 "facts": "(a JSON string; decoded: has_pitch false, bar beat met; hook met; complete met; subject unclear; length unclear; vocabulary met; ask met, angle hint data, journalist named true with 3 recent pieces, flags none)",
 "target": "Dorsa Kelvane, DevOps reporter at The Brakewell Ledger\nRecent pieces:\n- \"Why platform teams are quietly killing the on-call rotation\" (Feb 27)\n- \"The hidden cost of flaky tests, by the numbers\" (Feb 12)\n- \"Inside the four-person startups selling to engineers\" (Jan 30)"
}

Reply:

{
 "task": "angle",
 "story_plain": {
  "what": "Quenbrook CI analyzed production deploys from its customers and is publishing a report on when teams deploy and how often Friday deploys are rolled back.",
  "who": "Quenbrook CI, a four-person company; Maelis Vandrot, co-founder and CTO, who ran the analysis.",
  "when": "The report goes live on March 18; the analysis was done last month.",
  "proof": "41,212 production deploys from 1,180 teams: 31% happen on a Friday, Friday deploys are rolled back 2.4 times as often as Tuesday deploys, and teams with fewer than 10 engineers ship 44% of their deploys after 3pm on Fridays."
 },
 "verdict": "pitch it",
 "verdict_why": "This is a proprietary data story with a publish date, a named analyst willing to explain the method and a quotable line that cuts against the obvious reading. The reporter's recent pieces sit on this beat.",
 "angle": {
  "id": "data",
  "why": "The story is proprietary numbers on a habit every engineering team argues about, packaged with a method and raw counts; Quenbrook is the source, not the headline.",
  "evidence": [
   "Last month we analyzed 41,212 production deploys from 1,180 teams that use Quenbrook (anonymized, opt-in).",
   "31% of all production deploys happen on a Friday, more than any other day."
  ]
 },
 "hook": {
  "text": "The Friday Deploy report publishes on March 18 with its method and raw counts, so a reporter can run the numbers first.",
  "evidence": [
   "Our report, \"The Friday Deploy\", goes live on March 18 with the method and the raw counts."
  ]
 },
 "reader_why": "DevOps readers live with the \"never deploy on Friday\" rule; hard numbers on how often it is broken, what it costs in rollbacks and why small teams do it anyway give them a data point for their own release policy.",
 
... (shortened here; the page shows it whole)

Pitch: the same story, carrying the check

Input (with the story check handed over):

{
 "task": "pitch",
 "story": "# Story notes: the Friday deploy\n\nQuenbrook CI is a four-person company that runs build pipelines for small engineering teams.\n\nLast month we analyzed 41,212 production deploys from 1,180 teams that use Quenbrook (anonymized, opt-in).\n\nWhat we found:\n- 31% of all production deploys happen on a Friday, more than any other day.\n- Friday deploys are rolled back 2.4 times as often as Tuesday deploys.\n- Teams with fewer than 10 engineers ship 44% of their deploys after 3pm on Fridays.\n\nOur report, \"T... (836 characters in all)",
 "facts": "(a JSON string; decoded: has_pitch false, bar beat met; hook met; complete met; subject unclear; length unclear; vocabulary met; ask met, angle hint data, journalist named true with 3 recent pieces, flags none)",
 "target": "Dorsa Kelvane, DevOps reporter at The Brakewell Ledger\nRecent pieces:\n- \"Why platform teams are quietly killing the on-call rotation\" (Feb 27)\n- \"The hidden cost of flaky tests, by the numbers\" (Feb 12)\n- \"Inside the four-person startups selling to engineers\" (Jan 30)",
 "angle_handoff": "{\"verdict\":\"pitch it\",\"angle\":{\"id\":\"data\"},\"hook\":{\"text\":\"The Friday Deploy report publishes on March 18 with its method and raw counts, so a reporter can run the numbers first.\"},\"reader_why\":\"DevOps readers live with the \\\"never deploy on Friday\\\" rule; hard numbers on how often it is broken, what it costs in rollb..."
}

Reply:

{
 "task": "pitch",
 "angle": "data",
 "template": "data",
 "source": "angle handoff",
 "subject": "Data: 31% of deploys happen on a Friday",
 "body": "Hi Dorsa,\n\nYour piece \"The hidden cost of flaky tests, by the numbers\" is why I'm writing: we have numbers on another release habit.\n\nQuenbrook CI analyzed 41,212 production deploys from 1,180 teams. 31% of all production deploys happen on a Friday, and Friday deploys are rolled back 2.4 times as often as Tuesday deploys.\n\nFor your readers, that is the never-deploy-on-Friday rule tested against real pipelines, and broken more than any other day.\n\nMaelis Vandrot, our co-founder and CTO, ran the analysis: \"Small teams aren't reckless. They ship on Friday because it's the only day nobody books meetings.\"\n\nMethod: [the method in two lines]. Our report, \"The Friday Deploy\", goes live on March 18 with the raw counts, and I can send it under embargo until [day, time, timezone].\n\nCould Maelis walk you through the method before March 18?\n\n[your name]\nQuenbrook CI",
 "ask": {
  "type": "interview",
  "text": "Could Maelis walk you through the method before March 18?"
 },
 "facts_used": [
  {
   "quote": "Our report, \"The Friday Deploy\", goes live on March 18 with the method and the raw counts.",
   "as": "hook"
  },
  {
   "quote": "Last month we analyzed 41,212 production deploys from 1,180 teams that use Quenbrook (anonymized, opt-in).",
   "as": "method"
  },
  {
   "quote": "31% of all production deploys happen on a Friday, more than any other day.",
   "as": "proof"
  },
  {
   "quote": "Friday deploys are rolled back 2.4 times as often as Tuesday deploys.",
   "as": "proof"
  },
  {
   "quote": "Small teams aren't reckless. They ship on Friday because it's the only day nobody books meetings,",
   "as": "quote"

... (shortened here; the page shows it whole)

Pitch: a clinic customer story, asking for an interview

Input:

{
 "task": "pitch",
 "story": "Slatenib makes patient intake forms that work by text message for small medical and dental practices.\n\nFenwhistle Dental, a three-chair practice in Dayton, Ohio, switched from paper clipboards to Slatenib in June. In the four months before, 18% of appointments were no-shows. In the four months after, the rate was 7%.\n\nDr. Odalys Ferrandeu, owner of Fenwhistle Dental, is willing to talk on the record and can share her monthly no-show counts.\n\n\"I assumed no-shows were a patient problem. Half of them ... (776 characters in all)",
 "facts": "(a JSON string; decoded: has_pitch false, bar beat met; hook met; complete met; subject unclear; length unclear; vocabulary met; ask met, angle hint customer, journalist named true with 3 recent pieces, flags none)",
 "target": "Pirelle Ransdane, health-business reporter at Ohrvale Health Wire\nRecent pieces:\n- \"Small practices are drowning in front-desk paperwork\" (Sep 22)\n- \"The no-show problem costs clinics more than they think\" (Sep 3)\n- \"What the new digital-records rule means for dentists\" (Aug 19)",
 "ask": "interview"
}

Reply:

{
 "task": "pitch",
 "angle": "customer",
 "template": "customer",
 "source": "picked from the story",
 "subject": "Dentist cut no-shows from 18% to 7%",
 "body": "Hi Pirelle,\n\nYour Sep 3 piece, \"The no-show problem costs clinics more than they think,\" made me think you would want this one.\n\nFenwhistle Dental, a three-chair practice in Dayton, Ohio, switched from paper clipboards to text-message intake forms in June. In the four months before, 18% of appointments were no-shows. In the four months after, the rate was 7%.\n\nThe owner, Dr. Odalys Ferrandeu, puts it plainly: \"I assumed no-shows were a patient problem. Half of them were a paperwork problem.\"\n\nThe state dental board's new rule on digital patient records takes effect on November 1, and most small practices in Ohio still use paper, so your readers are weighing this switch right now.\n\nWould you like to interview Dr. Ferrandeu before the November 1 rule takes effect? She is willing to talk on the record.\n\n[your name]\nSlatenib, a team of six in Columbus",
 "ask": {
  "type": "interview",
  "text": "Would you like to interview Dr. Ferrandeu before the November 1 rule takes effect?"
 },
 "facts_used": [
  {
   "quote": "The state dental board's new rule on digital patient records takes effect on November 1",
   "as": "hook"
  },
  {
   "quote": "Fenwhistle Dental, a three-chair practice in Dayton, Ohio, switched from paper clipboards to Slatenib in June.",
   "as": "customer"
  },
  {
   "quote": "In the four months before, 18% of appointments were no-shows.",
   "as": "proof"
  },
  {
   "quote": "In the four months after, the rate was 7%.",
   "as": "proof"
  },
  {
   "quote": "I assumed no-shows were a patient problem. Half of them were a paperwork problem",
   "as": "quote"
  },
  {
   "quote": "Dr. Odalys
... (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 a story check, all seven checks graded once, a pass only with a quote, beat match unknown when no journalist is named, length and banned words matching the page's counts, no pass on a subject that is missing or too long, "pitch it" only with an angle, a hook and a complete story, every quote in the story or notes word for word, and subject ideas under 50 characters; for a pitch, a subject under 50 characters with no pattern that gets deleted, a body of 150 words or fewer, the page's rules re-run over it (banned words, pitch killers, emoji), the ask copied from the body, no quotation that is not in the story, two follow-ups on days 3 and 7 that never bump, and no invented or rounded figures. 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 story 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://pitch-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":"pitch-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": "angle", "story": "...", "facts": "...", "target": "..."}
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 pitch-desk:<lane>:<inputHash>:a<attempt>. The job's output.output is the reply text; truncated: true means the balance cut it short.

KEY="pitch-desk:angle:$(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 (pitch)

The same run as Server-Sent Events. pitch.json is a pitch input, with angle_handoff when it follows a story check.

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