Ben Milne developer portal — APIs and MCP server for benmilne.com

Ben Milne publishes long-form essays on value design and payment protocols at benmilne.com. This page is the human-facing companion to machine discovery files (/llms.txt, /agents.md). Core HTTP surfaces are public, read-only, and usable without API keys.

Quickstart

1. Read endpoint index at /api.
2. Fetch structured content from /api/posts.
3. Search posts with /api/search?q=....
4. Use MCP-compatible endpoints under /mcp/v1/* for agent tools.

Authentication and access

Read APIs are unauthenticated. OAuth endpoints are published for standards discovery, but token issuance is intentionally unsupported for this read-only origin. Rate-limit headers are returned on MCP endpoints and should be respected by clients.

curl -H "Accept: application/json" https://preview.benmilne.com/api/posts?per_page=3
curl -H "Accept: text/markdown" https://preview.benmilne.com/value-derivations
curl https://preview.benmilne.com/.well-known/mcp/server-card.json

Discovery endpoints

• /openapi.json - OpenAPI schema
• /.well-known/api-catalog - API catalog linkset
• /.well-known/mcp/server-card.json - MCP server card
• /.well-known/mcp/manifest.json - MCP manifest compatibility URL
• /agents.md - agent instructions
• /llms.txt - LLM index
• /docs - canonical Ben Milne API documentation URL
• /integrations - SDK integration guide

Official Ben Milne / benmilne.com CLI & SDK packages

Predictable names for programmatic discovery: shipped from the benmilne-app monorepo under integrations/. Publish to npm and PyPI to satisfy registry checks; canonical documentation remains on-site at /docs and /integrations.

CLI — benmilne-site-cli

• npm: npmjs.com/package/benmilne-site-cli
• Command: benmilne-site (npm install -g benmilne-site-cli)
• Synopsis: benmilne-site search stablecoin, benmilne-site posts 1, benmilne-site openapi
• Alternate origin example: BENMILNE_BASE=https://preview.benmilne.com benmilne-site site

JavaScript client — benmilne-site-api (npm)

• npm: npmjs.com/package/benmilne-site-api
• Install: npm install benmilne-site-api
• Import ESM class BenMilneSiteClient — see examples on /integrations.

Python package — benmilne-site-api (PyPI)

• pip install benmilne-site-api — client class benmilne_site.BenMilneSiteClient
• Project folder: repository integrations/benmilne-site-api-py

Status and error handling

Use /status for a lightweight health check. For resilient agents, retry transient failures with exponential backoff and jitter. For rate limits, pause and retry after a short delay before escalating.

Current auth model is public read-only access. OAuth discovery metadata is published for compatibility, with listed scopes (content.read, search.read, product.read) to support future hardened deployments.

Error responses are modeled in /openapi.json as a consistent ErrorResponse object with an error message string.