Machine-Gated Catalog Reads (Post-Launch)
GET /catalog and GET /advertisers are free for all clients
at launch. Once the catalog reaches a traction threshold, machine reads via
Accept: application/json will be MPP-gated. Human reads remain
free permanently.
Context
The catalog's public read endpoints are the viral surface of madcatalog. Charging at launch would kill the flywheel before it starts. However, autonomous agents running competitive intelligence pipelines are a distinct second audience with operational budgets — not the viral audience, but data consumers.
The traction threshold (~20+ active advertisers for 30 consecutive days) is the natural inflection point between "prove the catalog" and "monetize the catalog."
Decision
Machine reads will be MPP-gated post-launch using Accept-header detection:
Accept: text/html is always free; Accept: application/json
without a credential returns a 402 MPP challenge; with a valid
credential it is charged $0.02–$0.05 per read.
The 402 response and x-payment-info extension are
already in api/openapi.yml. Lambda implementation is gated on
reaching the traction threshold, not on a calendar date.
Consequences
Positive
- Recurring revenue with zero marginal cost once implemented
- Human viral loop is never compromised
- Consistent with the machine-economy thesis
- Contract already in OpenAPI spec; implementation is a Lambda config change
Negative
- Traction threshold is a judgment call; enabling too early chills adoption
- Agents with embedded free reads need reconfiguration when gating activates
- Per-read pricing may be too low if read volume is less than expected
Alternatives Considered
| Option | Why not chosen |
|---|---|
| Gate at launch | Cold-start problem; kills viral adoption |
| Keep free permanently | Leaves natural monetization surface unused; inconsistent with newsletter pricing model |
| API key subscription | Requires separate subscription flow; per-read MPP is simpler and consistent with the rest of the API |