← Co-Marketing Fit / API
Tokens

Drive Co-Marketing Fit from your own code

The page does its free work in the browser: it reads what your company does and a shortlist of possible co-marketing partners (CSV, TSV or a Markdown table), maps the columns, and scores what it can measure on its own 1-5 scale - each partner's audience size, engagement, the reciprocity between the two audiences and the ease of execution - with flags CM-01..CM-10 (a competitor, audiences more than 10 times apart, missing sizes and engagement, no relationship signal, duplicates). Its two paid lanes are available over HTTP. You send one JSON object with task set to "score" or "plan", and the model replies with one JSON object. The easiest way to build the facts string is the page itself: PartnerKit.buildInput(lane, PartnerKit.analyze(you, partners, {company, goal, question}), {partner, scoreHandoff}) in partnerkit.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
"score"The partner scorecard: for each partner the page sent, the co-marketing skill's six criteria 1-5 (audience_fit and brand_alignment judged with quotes; audience_size, engagement, reciprocity and ease exactly as the page computed them, or null), a partnership type, a verdict of pursue, maybe or pass, 1-2 campaign formats, risks and what to find out; then a ranking, a top_pick and a next_step.
"plan"A joint campaign with one partner: the campaign (a format from the skill's list, its category, a working title, a pitch, what customers get from both, the shared moment), alternatives, the assets each side brings, the eight-item agreement, a timeline, metrics, the outreach email and the call_prep.

Input fields (all strings)

fieldwhencontent
taskrequiredscore or plan
companyrequiredYour company's name (may be empty; the page then reads it from the description's first words).
yourequiredWhat your company does: the product, the buyer, audience numbers, integrations, past partnerships, the goal and the timeline. Past 5,000 characters the page cuts the middle on line boundaries and leaves a [comarketing-fit: ...] marker.
partnersrequiredThe shortlist's header row and the rows of the partners in this run: up to 8 for score, the chosen one for plan, within 6,000 characters, cut on whole rows.
factsrequiredA JSON string: company, you_size, you_size_basis, icp_stated, icp_quote, you_history, columns, mapped, partners[] (name, row, does, audience, size, engagement, relation, competes, team, history, notes, ratio, computed{audience_size, engagement, reciprocity, ease}, flags[]), flags[], goal, notes.
goaloptionalThe campaign category you prefer: any, content, events, product or community.
partnerplan onlyThe partner to plan with, spelled as the shortlist spells it.
questionoptionalWhat you want to know.
score_handoffplan onlyA JSON string of that partner's scorecard entry: partner, verdict, type, scores{}, campaigns[], risks.
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: "score"

partners[{name, type: co-marketing|integrations|reseller|affiliate|marketplace, scores{audience_fit, audience_size, brand_alignment, engagement, reciprocity, ease: {score: 1-5|null, why, evidence[]}}, verdict: pursue|maybe|pass, reason, campaigns[], risks, find_out}] (one per partner sent, in order), ranking[], top_pick, next_step.

task: "plan"

source (score handoff|from the input), partner, campaign{format, category: content|events|product|community, title, pitch, combined_value, moment}, alternatives[{format, pitch}] (1 or 2), assets{yours[], theirs[]}, agreement[{item, terms}] (exactly eight, in order: campaign description, responsibilities, timeline, lead handling, promotion, branding, costs, metrics sharing), timeline[{phase, when, owner: you|partner|both, what}] (3 to 6), metrics[] (3 to 6), outreach{subject, body}, call_prep[{item, status: ready|missing, note}] (exactly five).

Worked examples

These are the page's own bundled examples (invented companies, people and numbers), with the input as app.js builds it and the saved model reply the page replays for free. One worked example per lane, the score-to-plan handoff, and a second scorecard.

Score: an invoicing app for freelancers and six possible partners

Input (description, shortlist and facts shortened here):

{
 "task": "score",
 "company": "Tallyho",
 "you": "Tallyho - invoicing and payment reminders for freelancers and small creative agencies (1-10 people).\nOur buyer is a freelance designer, developer or writer who sends 5 to 30 invoices a month and hates chasing late payments.\nAudience: our newsletter \"Paid on Time\" has 14,200 subscribers with a 41% open rate; about 3,000 paying customers.\nIntegrations today: Stripe, PayPal and a Zapier app. Customers keep asking for a ... (641 characters in all)",
 "partners": "partner,what_they_do,audience,audience_size,open_rate,relationship,competes,partnerships_team,past_co_marketing,notes\nTimesmith,time tracking with billable hours,freelancers and small agencies,22k newsletter,38%,native integration in beta; customers ask for it,no,yes (Dana runs partnerships),yes - podcast swaps with two design tools,Their users export hours to spreadsheets to invoice\nLedgerloop,invoicing app,freelanc... (1140 characters in all)",
 "facts": "(a JSON string; decoded: company Tallyho, your audience 14200, buyer stated, past co-marketing yes, 6 partners: Timesmith (size 4, engagement 4, reciprocity 5, ease 5); Ledgerloop (size 3, engagement 3, reciprocity 5, ease 1); BigBooks (size 5, engagement -, reciprocity 1, ease 5); Freelance Friday (size 3, engagement 5, reciprocity 5, ease 3); Clauseful (size 2, engagement 3, reciprocity 3, ease 1); Pixelpost (size 4, engagement 2, reciprocity 3, ease 1); flags CM-01@Ledgerloop, CM-04@Ledgerloop, CM-07@Ledgerloop, CM-03@BigBooks, CM-09@BigBooks, CM-04@Clauseful, CM-07@Clauseful, CM-04@Pixelpost, CM-07@Pixelpost)",
 "goal": "any",
 "question": "Who should we approach first?"
}

Reply:

{
 "task": "score",
 "partners": [
  {
   "name": "Timesmith",
   "type": "integrations",
   "scores": {
    "audience_fit": {
     "score": 5,
     "why": "Timesmith serves the same freelancers and small agencies, and sits right before invoicing in their workflow.",
     "evidence": [
      "freelancers and small agencies",
      "Their users export hours to spreadsheets to invoice"
     ]
    },
    "audience_size": {
     "score": 4,
     "why": "Their 22k newsletter falls in the page's 20,000 to 99,999 band.",
     "evidence": [
      "22k newsletter"
     ]
    },
    "brand_alignment": {
     "score": 4,
     "why": "A billable-hours tool your customers already ask for is a partner you would be glad to be seen with.",
     "evidence": [
      "Customers keep asking for a time-tracking integration"
     ]
    },
    "engagement": {
     "score": 4,
     "why": "Their 38% open rate scores 4 on the page's scale.",
     "evidence": [
      "38%"
     ]
    },
    "reciprocity": {
     "score": 5,
     "why": "Their 22k newsletter against your 14,200 subscribers is a ratio of 1.5, well matched.",
     "evidence": [
      "22k newsletter"
     ]
    },
    "ease": {
     "score": 5,
     "why": "They have a named partnerships lead and past co-marketing.",
     "evidence": [
      "yes (Dana runs partnerships)",
      "yes - podcast swaps with two design tools"
     ]
    }
   },
   "verdict": "pursue",
   "reason": "Same buyer, the next step in their workflow, an integration already in beta and a partnerships lead to talk to.",
   "campaigns": [
    "integration launch",
    "podcast guest exchange"
   ],
   "risks": "",
   "find_out": "When the beta integration can launch publicly and whether Dana will co-own the launch."
  },
  {
   "name": "Ledgerloop",
   "type": "c
... (shortened here; the page shows it whole)

Plan: the top pick, carrying its scorecard entry

Input (with the scorecard entry handed over):

{
 "task": "plan",
 "company": "Tallyho",
 "you": "Tallyho - invoicing and payment reminders for freelancers and small creative agencies (1-10 people).\nOur buyer is a freelance designer, developer or writer who sends 5 to 30 invoices a month and hates chasing late payments.\nAudience: our newsletter \"Paid on Time\" has 14,200 subscribers with a 41% open rate; about 3,000 paying customers.\nIntegrations today: Stripe, PayPal and a Zapier app. Customers keep asking for a ... (641 characters in all)",
 "partners": "partner,what_they_do,audience,audience_size,open_rate,relationship,competes,partnerships_team,past_co_marketing,notes\nTimesmith,time tracking with billable hours,freelancers and small agencies,22k newsletter,38%,native integration in beta; customers ask for it,no,yes (Dana runs partnerships),yes - podcast swaps with two design tools,Their users export hours to spreadsheets to invoice",
 "facts": "(a JSON string; decoded: company Tallyho, your audience 14200, buyer stated, past co-marketing yes, 1 partner: Timesmith (size 4, engagement 4, reciprocity 5, ease 5); flags none)",
 "goal": "any",
 "partner": "Timesmith",
 "question": "Who should we approach first?",
 "score_handoff": "{\"partner\":\"Timesmith\",\"verdict\":\"pursue\",\"type\":\"integrations\",\"scores\":{\"audience_fit\":5,\"audience_size\":4,\"brand_alignment\":4,\"engagement\":4,\"reciprocity\":5,\"ease\":5},\"campaigns\":[\"integration launch\",\"podcast guest exchange\"],\"risks\":\"\"}"
}

Reply:

{
 "task": "plan",
 "source": "score handoff",
 "partner": "Timesmith",
 "campaign": {
  "format": "integration launch",
  "category": "product",
  "title": "Track it, bill it: Timesmith hours straight into Tallyho invoices",
  "pitch": "Launch the Timesmith and Tallyho integration together so freelancers turn tracked billable hours into invoices without a spreadsheet.",
  "combined_value": "Freelancers get tracked hours and a sent, chased invoice in one flow, where today Timesmith users export hours to spreadsheets to invoice.",
  "moment": "Tallyho customers keep asking for a time-tracking integration, and Timesmith users export hours to spreadsheets to invoice."
 },
 "alternatives": [
  {
   "format": "podcast guest exchange",
   "pitch": "Swap podcast guest spots on getting paid for billable hours, building on Timesmith's podcast swaps with design tools."
  },
  {
   "format": "joint webinar",
   "pitch": "A joint webinar showing freelancers the hours-to-invoice workflow, following Tallyho's earlier joint webinar with a tax app."
  }
 ],
 "assets": {
  "yours": [
   "The \"Paid on Time\" newsletter with 14,200 subscribers and a 41% open rate",
   "About 3,000 paying customers who ask for a time-tracking integration",
   "Experience running a joint webinar with a tax app for freelancers"
  ],
  "theirs": [
   "A 22k newsletter of freelancers and small agencies with a 38% open rate",
   "A native integration with Tallyho in beta",
   "Dana, who runs partnerships",
   "Experience with podcast swaps with two design tools"
  ]
 },
 "agreement": [
  {
   "item": "campaign description",
   "terms": "Tallyho and Timesmith jointly announce the native integration to freelancers and small agencies, with a shared \"better together\" message."
  },
  {
   "item": "responsibiliti
... (shortened here; the page shows it whole)

Plan: a newsletter tool and a landing-page partner, before a launch date

Input:

{
 "task": "plan",
 "company": "Quillsend",
 "you": "Quillsend - email newsletter software for independent creators (writers, illustrators, podcasters) who sell digital products.\nOur newsletter for creators has 31,000 subscribers (35% open rate) and we post weekly on YouTube.\nWe have never run a co-marketing campaign before.\nWe want to run something with a landing page partner before 14 November, when our paid-products feature launches.\nBudget: we can pay for a webinar... (457 characters in all)",
 "partners": "partner,what_they_do,who_they_serve,audience_size,open_rate,shared_customers,competes,partnerships_team,past_co_marketing\nPageform,landing pages and link-in-bio pages,independent creators,45k newsletter,33%,\"about 600 customers use both (from our onboarding survey)\",no,yes - Mara Quintebrook leads partnerships,yes - co-hosted a workshop with a design tool",
 "facts": "(a JSON string; decoded: company Quillsend, your audience 31000, buyer stated, past co-marketing no, 1 partner: Pageform (size 4, engagement 4, reciprocity 5, ease 5); flags CM-10)",
 "goal": "events",
 "partner": "Pageform"
}

Reply:

{
 "task": "plan",
 "source": "from the input",
 "partner": "Pageform",
 "campaign": {
  "format": "joint webinar",
  "category": "events",
  "title": "From page to paid: selling digital products with your newsletter and landing page",
  "pitch": "A joint webinar showing independent creators how to pair a Pageform landing page with a Quillsend newsletter to sell digital products, timed to the paid-products launch.",
  "combined_value": "Creators see the full path from a link-in-bio page to an email list to a paid product, which neither tool shows alone.",
  "moment": "Quillsend's paid-products feature launches on 14 November."
 },
 "alternatives": [
  {
   "format": "co-hosted workshop",
   "pitch": "A hands-on workshop where creators build a product landing page and a launch email together, a format Pageform has run before."
  },
  {
   "format": "joint AMA or Twitter Space",
   "pitch": "A live AMA with both teams on selling digital products to a newsletter audience."
  }
 ],
 "assets": {
  "yours": [
   "A creator newsletter with 31,000 subscribers and a 35% open rate",
   "A weekly YouTube channel",
   "The paid-products feature launching 14 November",
   "Budget for a webinar tool and design time"
  ],
  "theirs": [
   "A 45k newsletter of independent creators with a 33% open rate",
   "Landing page and link-in-bio product",
   "A partnerships lead, Mara Quintebrook",
   "Experience co-hosting a workshop with a design tool"
  ]
 },
 "agreement": [
  {
   "item": "campaign description",
   "terms": "Quillsend and Pageform co-host one live webinar for independent creators on selling digital products with a landing page and a newsletter."
  },
  {
   "item": "responsibilities",
   "terms": "Quillsend runs the webinar tool, design and the newsletter demo; Pageform pres
... (shortened here; the page shows it whole)

Score: a bare shortlist, three names and a note each

Input:

{
 "task": "score",
 "company": "Classquay",
 "you": "Classquay - class booking and memberships software for independent yoga and pilates studios.\nStudio owners use us to run their schedule, sell class packs and send reminders.\nWe have never done co-marketing. We want to try one partnership this spring.\n",
 "partners": "partner,notes\nMatwell,\"sells yoga mats and props wholesale to studios; their rep visits studios in person\"\nStudiolens,\"photo and video packages for fitness studios; small team\"\nStretchreel,\"on-demand yoga video platform for consumers; studios sometimes list classes there\"",
 "facts": "(a JSON string; decoded: company Classquay, your audience not stated, buyer stated, past co-marketing no, 3 partners: Matwell (size -, engagement -, reciprocity -, ease -); Studiolens (size -, engagement -, reciprocity -, ease -); Stretchreel (size -, engagement -, reciprocity -, ease -); flags CM-02@Matwell, CM-07@Matwell, CM-09@Matwell, CM-02@Studiolens, CM-07@Studiolens, CM-09@Studiolens, CM-02@Stretchreel, CM-07@Stretchreel, CM-09@Stretchreel, CM-05)",
 "goal": "any",
 "question": "Is any of these worth a first partnership?"
}

Reply:

{
 "task": "score",
 "partners": [
  {
   "name": "Matwell",
   "type": "co-marketing",
   "scores": {
    "audience_fit": {
     "score": 5,
     "why": "Matwell sells to the same studio owners you serve, solving a different problem: equipment, not scheduling.",
     "evidence": [
      "sells yoga mats and props wholesale to studios",
      "independent yoga and pilates studios"
     ]
    },
    "audience_size": {
     "score": null,
     "why": "The shortlist gives no audience size for Matwell.",
     "evidence": []
    },
    "brand_alignment": {
     "score": 4,
     "why": "A props supplier whose rep already visits studios in person is a natural, trusted name beside a studio software tool.",
     "evidence": [
      "their rep visits studios in person"
     ]
    },
    "engagement": {
     "score": null,
     "why": "No open or engagement rate is given for Matwell.",
     "evidence": []
    },
    "reciprocity": {
     "score": null,
     "why": "Neither your audience size nor Matwell's is stated, so the two cannot be compared.",
     "evidence": []
    },
    "ease": {
     "score": null,
     "why": "The shortlist does not say whether Matwell has a partnerships team or past co-marketing.",
     "evidence": []
    }
   },
   "verdict": "pursue",
   "reason": "Same buyer, a different problem, and a sales rep who already meets your buyers face to face.",
   "campaigns": [
    "co-hosted workshop",
    "bundle or discount"
   ],
   "risks": "No audience size, engagement figure or relationship with you is stated, so reach and ease are unknown.",
   "find_out": "How many studios Matwell supplies and who there would own a partnership."
  },
  {
   "name": "Studiolens",
   "type": "co-marketing",
   "scores": {
    "audience_fit": {
     "score": 4,
     "why": "Studi
... (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 scorecard, one entry per partner it sent, in order, names spelled the same; all six criteria; audience size, engagement, reciprocity and ease equal to the page's own scores and null where it had nothing; audience fit and brand alignment quoted when scored; pass for a competitor (CM-01) or a fit of 1 or 2, pursue only for a fit of 4 or 5 with no 1 on reciprocity or ease; a real partnership type; campaign formats from the skill's list; a ranking of every partner with pursue before maybe before pass and the top pick first. For a plan, the partner asked for; a campaign format from the list in its own category and the preferred one; the eight agreement items in order with lead handling stated; 3 to 6 timeline phases; metrics from the skill's list; an outreach email naming both companies, under 120 words, asking for a call; call preparation marked ready only when the input has it. In both, quotes are checked word for word and no size, rate, price, date or duration 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://comarketing-fit.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":"comarketing-fit"}' | 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": "score", "company": "...", "you": "...", "partners": "...", "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 comarketing-fit:<lane>:<inputHash>:a<attempt>. The job's output.output is the reply text; truncated: true means the balance cut it short.

KEY="comarketing-fit:score:$(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 (plan)

The same run as Server-Sent Events. plan.json is a plan-lane input, with score_handoff when it follows a scorecard.

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