benmilne.com Developer API — OpenAPI, MCP, REST

This site publishes a read-only JSON API so agents, integrations, and curious developers can work with the content programmatically without scraping HTML. No authentication, no versioning, CORS open.

benmilne developer resources: benmilne API docs, benmilne OpenAPI spec, benmilne GraphQL API, benmilne MCP server (Streamable HTTP JSON-RPC), benmilne auth docs, benmilne agent instructions, benmilne machine catalog, and benmilne MCP server card.

Quick links

/api/posts — Public Data API (read-only JSON, no auth)
/api/site — Site metadata
/api/search?q=stablecoin — Full-text search
/llms.txt — Machine-readable site index for LLMs
/feed.xml — RSS feed
/api/products/the-value-layer — Book product JSON (*The Value Layer*, PDF)
/graphql — GraphQL API (Relay cursor pagination, typed errors, introspection)

Authentication

There is no API key product. All endpoints are public and read-only. Make GET requests from any origin — no tokens, no headers, no sign-up.

Endpoints

Method	Path	Description
`GET`	`/api`	This page (HTML) or endpoint index (JSON)
`GET`	`/api/site`	Site metadata and post count
`GET`	`/api/posts`	Paginated post list
`GET`	`/api/posts/:slug`	Single post with full content and agent metadata
`GET`	`/api/search?q=`	Full-text search across posts
`GET`	`/api/categories`	All categories with post counts
`GET`	`/api/tags`	All tags with post counts
`GET`	`/api/categories/:slug`	Posts filtered by category
`GET`	`/api/tags/:slug`	Posts filtered by tag

Posts

GET /api/posts returns a paginated list of posts. Each item is a slim summary — no content body. Use ?page= and ?per_page= (max 100) to paginate.

curl https://benmilne.com/api/posts?per_page=3

Single post

GET /api/posts/:slug returns the full post with rendered HTML, Markdown body (stored source when present, otherwise HTML converted to Markdown), and agent-rich metadata: extracted links, media references, section outline, and estimated reading time.

curl https://benmilne.com/api/posts/value-derivations

Search

GET /api/search?q= performs full-text search across all posts. Returns slim post summaries. Try: stablecoin, brale, bitcoin, value.

curl "https://benmilne.com/api/search?q=stablecoin"

Categories and tags

GET /api/categories and GET /api/tags list all taxonomies with post counts. Append a slug to filter posts: /api/categories/stablecoin-infrastructure.

Response envelope

Every response wraps data in a consistent shape with an attribution notice:

Collection

{
  "attribution": "Content provided by BenMilne.com. ...",
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 9,
    "total_pages": 1
  }
}

Single resource

{
  "attribution": "Content provided by BenMilne.com. ...",
  "data": { ... }
}

Post shapes

List item (slim)

Returned by /api/posts, /api/search, and taxonomy filters. No content body.

{
  "slug": "value-derivations",
  "title": "Value Derivations",
  "date": "2025-09-28T17:20:38+00:00",
  "modified": "2026-02-23T06:17:15+00:00",
  "author": "Ben Milne",
  "summary": "I use a simple model when...",
  "url": "https://benmilne.com/value-derivations",
  "featured_image": null,
  "categories": ["Payment Systems"],
  "tags": []
}

Detail (agent-rich)

Returned by /api/posts/:slug. Everything above, plus content and structured metadata designed for AI consumption:

{
  "slug": "value-derivations",
  "title": "Value Derivations",
  "content_html": "<p>...</p>",
  "content_markdown": "...",
  "reading_time": 4,
  "links": ["https://brale.xyz/blog/new-capital"],
  "media": [
    { "type": "image", "src": "https://..." },
    { "type": "video", "src": "https://youtube.com/..." }
  ],
  "structure": {
    "sections": [
      { "level": 3, "text": "Major Value Derivations" },
      { "level": 4, "text": "1. Stablecoins as Liquidity Derivations" }
    ]
  }
}

For AI agents

The post detail endpoint is designed for agent consumption. Each response includes structured metadata that helps LLMs understand content without parsing HTML:

links[] — Every external URL referenced in the post. Agents can follow these for deeper research.
media[] — Images and videos with type and source URL. Useful for multimodal agents or content summaries.
structure.sections[] — Heading-based outline (h2/h3/h4 hierarchy). Use for navigation, summarization, or table-of-contents generation.
reading_time — Estimated minutes. Helps agents gauge content depth.
content_markdown — Markdown body: original source when the post was authored in Markdown; otherwise derived from HTML so agents always receive a text-first representation.

Streaming (Server-Sent Events)

Real-time search results via SSE. Connect with Accept: text/event-stream or use the dedicated streaming endpoint:

curl -N "https://benmilne.com/api/stream/search?q=payments"

Events: status (search phase), result (individual post match), done (completion summary), error (failure).

NLWeb streaming is also available via POST /ask with "streaming": true:

curl -N -X POST https://benmilne.com/ask \
  -H "Content-Type: application/json" \
  -d '{"query":"payments","streaming":true}'

SSE events follow the NLWeb spec: start, result, complete.

Rate limits

Every JSON response includes rate-limit headers:

Header	Description
`X-RateLimit-Limit`	Requests per window (1000)
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Cloudflare edge caching serves most reads. Use exponential backoff on 429 responses.

Developer resources

Resource	URL	Purpose
API docs	`/api`	This page (human-readable)
OpenAPI spec	`/openapi.json`	OpenAPI 3.0.3 schema for all endpoints
MCP server card	`/.well-known/mcp/server-card.json`	MCP tool discovery and transport info
MCP endpoint	`POST /mcp`	Streamable HTTP JSON-RPC (initialize, tools/list, tools/call)
MCP SSE	`/mcp/sse`	MCP Server-Sent Events transport
Agent instructions	`/agents.md`	Discovery pointers for coding agents
NLWeb endpoint	`POST /ask`	Natural-language query (JSON or SSE)
Sandbox	`/sandbox`	Canned test data for integration testing
LLMs.txt	`/llms.txt`	Site catalog for LLMs (posts + search)
Node.js	`npm install -g benmilne-api`	CLI and Node.js client (npm)
Python	`pip install benmilne-api`	CLI and Python client (PyPI)
GitHub	benmilne-com/agents	Public agent discovery repo
RSS	`/feed.xml`	Feed of all published posts

Content negotiation

This page serves HTML to browsers and JSON to programmatic clients. Any post URL on the site also supports content negotiation:

# JSON
curl -H "Accept: application/json" https://benmilne.com/value-derivations

# Markdown
curl -H "Accept: text/markdown" https://benmilne.com/value-derivations

# HTML (default)
curl https://benmilne.com/value-derivations

CORS

All API responses include Access-Control-Allow-Origin: *. Call from any origin — browser, server, agent.

Errors

Unknown paths return 404 with a JSON body. Missing required parameters return 400. All errors follow the same shape:

{ "error": "Not found" }           // 404
{ "error": "Query parameter ?q= is required" }  // 400

Multilingual API

All content endpoints support translated responses via the ?lang= query parameter. English is the default.

Supported languages

en, es, zh, ar, pt-br, fr, ja, de, ru, id, hi, ko, tr, vi

Language metadata

curl https://benmilne.com/api/languages

Translated posts

curl "https://benmilne.com/api/posts?lang=es"

Translated post detail

curl "https://benmilne.com/api/posts/better-funds-flows?lang=es"

Translated search

curl "https://benmilne.com/api/search?q=stablecoin&lang=zh"

Fallback

If a translated post is unavailable, the API returns 404 by default. Add ?fallback=en to receive the English version instead, clearly marked as a fallback:

curl "https://benmilne.com/api/posts/better-funds-flows?lang=es&fallback=en"

Unsupported language

Requesting an unsupported language returns 400 with the list of supported codes:

GET /api/posts?lang=xx  →  400 { "error": "Unsupported language", ... }

Translations are automated (DeepL) and may contain errors. English is always the source of truth.

RSS feeds

Language	Feed URL
English (canonical)	`/feed.xml`
Español	`/es/feed.xml`
简体中文	`/zh/feed.xml`
العربية	`/ar/feed.xml`
Português	`/pt-br/feed.xml`
Français	`/fr/feed.xml`
日本語	`/ja/feed.xml`
Deutsch	`/de/feed.xml`
Русский	`/ru/feed.xml`
Bahasa Indonesia	`/id/feed.xml`
हिन्दी	`/hi/feed.xml`
한국어	`/ko/feed.xml`
Türkçe	`/tr/feed.xml`
Tiếng Việt	`/vi/feed.xml`

Webhooks

Not provided. This site offers request/response HTTP APIs and RSS. There is no outbound webhook product. Pull the RSS feed on your schedule.