API Evangelist Paper Types

There is one type in this repo. That is the point of the file: to say so plainly, and to say what a paper is not, because for two years this repo held six types and the ambiguity is what caused the split.

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

A paper is not a report

Split on 2026-08-16. Everything that ships a machine-readable data bundle moved out.

The test is still the bundle. If the evidence is the blog corpus, the books and field work, it is a paper and it belongs here. Nothing that ships a scored cohort and a bundle/ gets added back: that shape was retired with the reports line on 2026-08-21, and the data it was rendered from is sold as metered API access instead. Do not describe report types here.

The paper

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. 21 live. New papers are written when there is a specific reason to rather than on a cadence — the research is pointed at the reports — but this is the storefront’s whole catalogue now rather than a band at the foot of somebody else’s page.

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 is a Trend Report. Anything about one named company — that is a Profile Report, or a Provider Checklist if it is written for them.

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.

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, and 0.11.0 halved this series’ Exemplar counts. When the rubric bumps, live reports need a revision pass — scripts/rescore_reports.py finds the drift and scripts/audit_report_claims.py separates what can be auto-corrected from what has to be re-argued.

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.