API Evangelist Paper Types

The canonical definition of every type of paper this repo produces. One rubric — the Kin Score — runs underneath all of them; what separates a type from its siblings is the unit of analysis, the buyer, and the spine.

Machine-readable registry: _data/paper_types.yml. This file is the prose behind it. When the two disagree, the YAML wins for tooling and this file wins for intent.

Four products, and a back catalogue. Market, Standard, Portfolio and Insights are what API Evangelist sells — they carry featured: true and they are the four problems /products/ leads with. Fundamentals still sells but is deliberately backgrounded; Provider Checklists are not sold from a catalogue at all.

¹ Priced by scope: one cohort is $500; a study synthesizing across many cohorts prices at $1,500. ² Back catalogue. Still for sale, off the four-up grid, one quiet band at the foot of /products/. ³ Never listed on the storefront. Not in _papers/; excluded in _config.yml. Offered from a provider’s own profile on providers.apievangelist.com, beside the free score it responds to.

The one distinction that matters

Five of the six types are written about somebody, for a third party to read. One — Providers — is written for the subject itself. That inversion changes the voice completely: the others are assessments and can be blunt about a named company, while a Provider Checklist is a work plan handed to the team that has to do the work. Never mix the two voices, and never let a Provider Checklist reach a public URL.

The second distinction: Insights inverts the buyer. Every other type is bought by people who publish APIs. Insights is bought by people selling into a company that publishes them.

Choosing a type

Start with the subject, not the price:

What is the subject of this paper?

 A named industry .................................... Markets ($500)
   └─ scoped to one country? still Markets — country is a facet, not a type
 A cohort that isn't an industry
   (an architecture, a tool corpus, a ranking
    across entities of the same kind) ................. Markets ($500)
 A standards body and its specifications ............. Standards ($500)
 A venture or growth fund's portfolio ................ Portfolios ($750)
 One company, read for a vendor selling into it ...... Insights ($1,500)
 One provider, written for that provider ............. Providers ($1,500)
 A topic, a practice, an argument .................... Fundamentals ($25)
                                                       — back catalogue; see below

Two rules that resolve almost every ambiguity:

1. If it scores a cohort, it is not Fundamentals — even at $25, even if the argument matters more than the data. Fundamentals is distilled practice; the moment a paper’s spine is “here is every provider in X, scored,” it belongs to a report type.
2. If the subject is a single named entity, the type follows what kind of entity it is — company (Insights), fund (Portfolios), standards body (Standards), provider you are advising (Providers).

1. Markets

What it is. One market, with every provider in it scored on the same public rubric and read straight from machine-readable evidence. The workhorse, and the merger of what were previously two types — Industries and Landscapes — into one product on 2026-07-31, because the machinery, the spine, the price and the buyer were identical and only the shape of the cohort differed. A cohort shape is a facet, not a product.

Unit of analysis. A market, in any of three shapes:

• an industry — state-of-telecom-apis, state-of-market-data-apis
• an industry within a country — state-of-us-banking-apis. Country is a facet, not a type; the four-country banking quartet is four Market Reports, not a separate family
• a cohort assembled by something other than sector — an architecture or category (state-of-headless-apis, 108 CMS, commerce and browser providers, where the single word covers three unrelated markets), a tool or practice corpus (the-state-of-spectral-in-api-pipelines, 1,005 real public pipelines), or a cross-entity ranking on one axis (agentic-readiness-of-venture, 25 funds, one question)

Qualifies. A recognizable market with enough providers to have a distribution — practically, 40+ scored providers, and never fewer than 25. A country cut qualifies when the regulatory regime differs enough to change the finding (the AU/UK/US/CA banking split exists because CDR, OBIE, and a no-mandate US produce three different markets). A non-sector cohort qualifies when it is real, comparable, and complete enough to have a distribution. Does not qualify. A cohort you assembled by tag match to fill a gap. The headless report is explicit that building the cohort by tag match produces the wrong set — the cohort has to be constructed deliberately, and the construction disclosed. This is the single hardest thing to get right in this type, and it is where a confident wrong answer comes from.

Required spine.

1. Executive summary — the finding that frames everything
2. The state of the market
3. The resource taxonomy — what this market’s APIs actually expose. For a non-sector cohort, this becomes whatever the cohort’s comparable surface is
4. The composite Kin Score, facet by facet
5. Agent-readiness across the twelve dimensions
6. Provenance — what the providers published vs. what API Evangelist derived
7. The blueprint — what the leaders satisfied and the field hasn’t
8. Standards — which standards this market claims and who ships a conformant contract
9. Regulation — the regimes in force, and the mandate × standard 2×2
10. Security, auth, scopes, and consent
11. Provider-by-provider intelligence — leaders, absent incumbents, the tail
12. The investable thesis
13. Where this is going

Sections 8 and 9 are required in every sector-shaped Market Report, including markets with no mandate — “no mandate” is itself the finding in US banking. For a cohort no regime touches, section 9 is included only where a regime actually applies. Provenance and the investable thesis are always required.

Evidence. all/* artifacts for every provider in the cohort — OpenAPIs, scopes, security, plans, agent surfaces — scored with score.rb. Never a hand-assembled list of impressions.

Naming. state-of-<country>-<industry>-apis, state-of-<industry>-apis, state-of-<cohort>-apis, the-state-of-<thing>, or the-<axis>-of-<population>.

Deliverables. PDF + Word + AI data bundle (bundle/, regenerable, shipped as a zip from S3).

Skill. api-evangelist-sector-report. Cadence. Revise on a rubric bump or a material market event; scripts/check_report_drift.py diffs published scores against the live catalog.

Pricing, settled. The old “two odd Landscapes” question is closed — verified 2026-07-31 against both the front matter and the live Stripe prices, which agree on all 35. the-state-of-spectral-in-api-pipelines is $500 (the inherited $25 was corrected 2026-07-30), and agentic-readiness-of-venture at $1,500 is exactly what the by-scope rule prescribes: it synthesizes 25 funds and 1,900 companies, which is Insights-tier depth. One cohort is $500; many cohorts is $1,500.

2. Fundamentals

What it is. One practice, topic, or body of knowledge, distilled from sixteen years of apievangelist.com and the books into a reusable playbook. Argument from experience, not from a cohort. No scoring, no data bundle.

Status: back catalogue. As of 2026-07-31 this is no longer a product API Evangelist leads with — distilling practice is not where the research is pointed. The 18 live papers stay for sale and keep their page, but the type is off the four-up grid on /products/ and appears there as a single quiet band. New Fundamentals are written only when there is a specific reason to, not on cadence.

Unit of analysis. A topic area — governance, discovery, evangelism, the lifecycle, pricing, MCP, Arazzo, context engineering, agent boundaries.

Qualifies. A practice the reader has to do; a category whose economics are worth explaining; an argument sixteen years of watching the industry earns. Does not qualify. Anything whose evidence is a scored cohort — that’s Markets. Anything about one named company — that’s Insights or Providers.

Required spine. Free-form body sections, then the three house closers, in this order:

• Anti-patterns I watch for
• Self-assessment — something the reader can run against their own operation
• Where this is going

Evidence. The blog corpus, the books, field work. Everything is first-person and attributable to practice; nothing is invented (see Cross-cutting rules).

Front matter. Requires topic: — the subject area the paper sits in (Governance, Discovery, Pricing, Developer Experience, Agentic APIs, Evangelism, API Lifecycle, Small Business). This is the only type where topic: is required, because it’s the only type whose subject isn’t already named by the title.

Naming. fundamentals-of-<topic>, the-pricing-of-<category>, publishing-<a-thing>, or a titled argument (explicit-agent-boundaries, conversational-api-governance).

Deliverables. PDF + Word. No AI bundle unless the paper ships a working artifact (running-a-local-food-business-on-apis ships an APIs.json; it sets bundle: true).

Skill. api-evangelist-paper.

3. Standards

What it is. One standards body: what it publishes, how much of it has graduated, who is in the coalition and who steers it, and the gap between organizations that claim the standard and organizations that ship a callable, conformant contract.

Unit of analysis. A standards body and its specification set — CAMARA, FHIR, FDX, TM Forum, OpenAPI, AsyncAPI, PSD2/OBIE.

Qualifies. The body publishes machine-readable specifications, has a public governance record, and has enough claimed implementers that the claim-vs-ship gap is measurable.

Required spine.

1. Executive summary — the ratio that frames everything
2. What the standard is, and what it is not
3. The origin
4. What the body publishes — repositories, categories, APIs
5. The maturity ladder — what has actually graduated
6. The coalition — who staffs it, who steers it, who does the work
7. The adoption gap — category by category
8. Conformance — including a document-level diff where the programme allows one
9. The regulatory layer — which regimes touch this subject matter, and whether any compels it
10. The scoring caveat — why a composite score is or isn’t the right instrument here
11. What would have to be true — the checkable signals that would change the call
12. The investable thesis
13. Where this is going

Section 10 is a hard requirement. A standards body scored on a provider rubric will score badly for structural reasons; say so explicitly rather than letting the number stand as a verdict.

Evidence. The standards pipeline artifacts under all/<body>/ — specifications, maturity ladder, participants, member organizations — matched against the catalog. Conformance diffs live in planning/<body>/conformance/ and are private evidence; only conclusions ship.

Naming. the-<standard>-standard.

Deliverables. PDF + Word + AI data bundle (scripts/build_standard_bundle.py).

Skill. api-evangelist-standard-report. Upstream: the pipeline-standards skill has to have profiled the body first. Downstream: run standards-from-paper to wire the paper into standards.apievangelist.com both ways.

4. Portfolios

What it is. One venture or growth fund’s book, read through the APIs its companies ship — scored, decomposed by practice area, and benchmarked head-to-head against rival funds.

Unit of analysis. One fund. A ranking across funds is a Market Report, not a Portfolio.

Qualifies. The fund’s public investment list resolves to enough API-bearing companies to score a distribution — practically 50+, and the marquee funds run into the hundreds.

Required spine.

1. Executive summary — the tell in the fund’s own book
2. The firm, and the book — how many portfolio companies ship an API
3. Portfolio decomposition — does the book look like the deck?
4. The composite Kin Score of the book, facet by facet
5. Agent-readiness of the portfolio
6. The peer-fund benchmark — apples to apples against rival funds
7. The crown jewels — provider-by-provider on the exemplars
8. Standards and the agentic turn
9. Security, auth, scopes, and compliance posture
10. The whitespace — for the fund and for its rivals
11. The investable thesis, written for both readers

Two readers, always. The fund and its LPs (portfolio diligence), and the competing fund or founder (who they backed, how it really scores, where the door is open). Write section 11 for both.

Evidence. portfolio/<slug>-portfolio.yml matched to the network by domain, every matched company scored. Portfolio companies that aren’t in the network become harvest leads, not omissions.

Naming. <firm>-api-portfolio.

Deliverables. PDF + Word + AI data bundle.

Skill. api-evangelist-portfolio-report. Upstream: pipeline-vc.

5. Insights

What it is. Account intelligence on one company, read from two directions — the demand side from its own hiring, press, and blogs, and the supply side from the API surface it publishes — sold to the vendor sales team that has to get into that account. The most expensive type, and the one with an inverted buyer.

Unit of analysis. One company. Primarily Fortune 100, in practice any account large enough to have a public job corpus and a public API surface.

Qualifies. Enough public job postings to extract a real demand profile, plus a public API surface worth scoring. An account with neither is not an Insights subject.

Required spine.

1. Executive summary — what kind of account this is
2. What the account is buying — all 41 investment dimensions, ranked against the Fortune 1000
3. The incumbents, the distinctive choices, and the stack broken out by kind
4. Where the gaps are — whitespace targets verified absent across the full corpus
5. The org map — function, location, posting recency, platform affinity
6. The peer cohort — peers re-extracted identically, so the comparison is honest
7. The supply side — published specs, provenance, and graded agent-readiness
8. What the account publishes about itself — press, blog, docs
9. The openings — entry points, displacement targets, discovery questions

Evidence. Jobs corpus (signals-jobs), press, blogs, docs, and the company’s own artifacts, re-profiled and re-scored at report time. Whitespace claims must be verified absent across the whole corpus, never inferred from a sample — a false “they don’t use X” is the one error that destroys the deliverable’s credibility with a sales team.

Naming. insights-<company>.

Deliverables. PDF + Word + the complete machine-readable data bundle (scripts/build_insights_bundle.py).

Skill. enterprise-insights-bundle.

6. Providers

What it is. One provider’s Kin Score and Agent Readiness read against their peers, then an itemized, sequenced checklist of every rubric check they are failing: what each one is worth on their score, what to do about it, and how API Evangelist can do it with them or for them.

Unit of analysis. One API provider — and the only type written for its subject.

Storefront: never. These name a real customer. Every checklist-<slug>/ folder goes in the _config.yml exclude list, and no document is created in _papers/.

Price: $1,500, fixed. Not listed publicly and not case-by-case. The checklist is the rung between the free score on apis.io and any engagement — the thing you hand across the table when a scoring conversation lands, with a Stripe link, so the answer to “what do we do about this?” is a product and not a proposal. It is never given away: the free tier is the score itself, and the checklist is what the score is worth once it is itemized. Same price as an Insights Bundle, because it is the same depth of work pointed at the buyer instead of at their account.

Required spine.

1. Where they stand — Kin Score and Agent Readiness against their peer cohort
2. The itemized checklist — every failing check, each traced to one numbered check in the public rubric, each carrying the exact score movement closing it would produce
3. Sequence — what to do first, and why
4. How API Evangelist can help — with them, or for them

Why every item traces to a numbered check. So nothing in the document is an opinion about their API. The rubric is public; the checklist is arithmetic against it. That is what makes it safe to hand to a team that didn’t ask for a critique.

Deliverables. The checklist (PDF + Word) and DECK.md — the two artifacts do different jobs; the deck is for the room, the checklist is for the team afterward.

Skill. api-evangelist-personalized-checklist (scripts/build_checklist.py, scripts/build_deck.py).

Cross-cutting rules

Front matter. Every document in _papers/ carries: order, slug, title, paper_type, area, tagline, version, updated, pages, cover, summary, outline. Everything except Fundamentals also carries price. Fundamentals also carries topic.

paper_type is the canonical key from _data/paper-types.yml. area is the human label rendered on the card and the paper page, and must match that type’s label. The field is paper_type rather than type because type is a reserved attribute on Jekyll collection documents.

Never fabricate. No invented specs, no unevidenced links, no plausible-sounding numbers. Every figure in a scored type traces to an artifact in all/* or to a script in scripts/.

Provenance is disclosed. Where a score rests on an artifact API Evangelist generated rather than one the provider published, the report says so — that’s the section 6 requirement in Markets, and it’s what Kin Score 0.6 grades.

Rubric versions are not comparable. Every scored paper carries a rubric version and an “as of” date. The Kin Score moves; 0.6 alone rebanded 8.8% of the catalog. When the rubric bumps, live reports need a revision pass — scripts/check_report_drift.py finds the drift.

Every scored type ships an AI data bundle. Layered per-entity data, an APIs.json 0.21 manifest, a conversation primer, and a data dictionary, so the buyer can interrogate the research they bought. Bundles are gitignored and regenerable, and ship as a zip from S3.

The bundle section on a paper page is driven by the type’s bundle: flag in _data/paper_types.yml, not by a hand-maintained list of labels. A paper of a bundling type whose bundle/ has not been generated yet must set data_bundle: false in its front matter — never advertise a bundle the buyer will not receive at checkout. Generate the bundle, then remove the override.

Full text stays private. The public site renders a teaser only — summary, outline, cover, and a Stripe checkout. Every paper folder is in the _config.yml exclude list.

Buy once, get every revision. These are living documents, which is why version and updated are required and why repricing is a deliberate act.

Open items

Carried forward from the July 2026 formalization, none of them blocking:

1. Price the two odd Market Reports deliberately. Closed 2026-07-31. Front matter and live Stripe agree on all 35; Spectral is $500 and the venture flagship’s $1,500 is the by-scope rule working as intended.
2. Generate the two missing bundles. Those same two papers are Market Reports with no bundle/ folder, and currently carry data_bundle: false to keep the page honest.
3. Facets are documented but not implemented. Market Reports could carry industry: and country: as first-class fields instead of encoding both in the slug, which would let the storefront filter the banking quartet as one family. Deferred — the slug convention works.
4. Fundamentals is thinning — resolved by decision, not by refill. 18 of 85 papers against 67 scored reports. Rather than refill it, the type was moved to back-catalogue status on 2026-07-31: the $25 tier is no longer positioned as the front door to the $500+ tiers, because the front door is now the problem the buyer arrives with.
5. Stripe product descriptions still say “Industry Report.” Closed 2026-07-31. Re-running the script would not have fixed this: ensurePaper returned early on a matching price and never touched the Product, so every rename since the first run had been a no-op and 31 products still said “Sector Report”. syncProductCopy now PATCHes drifted copy, DRY_RUN=1 previews it, and all 34 stale descriptions were corrected. Price IDs were untouched, so worker/src/prices.js is unchanged and the commerce Worker did not need redeploying.

Adding a new type

A new type is justified when a paper’s unit of analysis doesn’t match any existing type — not when it has a different price or a different length — and the bar is high. Landscapes once earned a slot on the argument that “every provider in an architecture” is a different unit than “every provider in an industry”; that argument did not survive contact with the storefront, and the two merged back into Markets in July 2026. A $99 Fundamentals paper would not qualify either.

The lesson from that merger: a type has to be a different thing to buy, not just a different thing to build. If two types share a spine, a price, and a buyer, they are one product with two cohort shapes, and splitting them only makes the reader do the sorting.

To add one:

1. Append it to _data/paper_types.yml — including the customer-facing fields (icon, price_label, plural, headline, pitch, buyer_line, unit_label, evidence_label). Keep angle brackets and repo paths out of the *_label and pitch fields; they render as HTML on the sales pages, where a stray <slug> silently eats the rest of the sentence.
2. Write its section here.
3. Add products/<key>.html (layout: product, paper_type: <key>), and decide featured:. A featured type generates its own problem card on /products/ and joins the chooser from the registry; an unfeatured one is reachable but not sold from the grid. The listing page is a real file either way. A featured type must also carry problem:, why:, chooser_label:, chooser_hint: and chooser_question: or the storefront renders blanks.
4. Build the producing skill, and point its front-matter guidance at this spec.
5. Add the first instance’s folder to the _config.yml exclude list.

The AI-bundle section on paper pages is driven by the registry’s bundle: flag, so _layouts/paper.html needs no edit.

Where the copy lives

_data/paper_types.yml is the single source for both the structural facts and the selling copy. The problem cards and the chooser on /products/, every /products/<type>/ sales page, and the badge on every paper page all read from it, so they cannot drift apart. Edit the registry, not the templates.

Three field families, deliberately separate. The structural fields (unit, evidence, price, slug_pattern) describe the type for tooling and for this spec, and may contain repo paths and placeholders. The customer-facing fields (headline, pitch, buyer_line, unit_label, evidence_label) render on the sales pages and must read as plain English to a buyer who has never seen the repo. The problem-first fields (problem, why, chooser_*) drive /products/: problem is written in the buyer’s voice, not Kin’s, and why has to answer “why does this research exist and why can nobody else publish it” without naming a price.

Keep angle brackets and repo paths out of every customer-facing and problem-first field; they render as HTML on the sales pages, where a stray <slug> silently eats the rest of the sentence.