Mash Prime API

Quickstart

List the posts, then read one by slug:

curl https://mashprime.dev/api/v1/posts
curl https://mashprime.dev/api/v1/posts/one-folder-to-autonomy
curl "https://mashprime.dev/api/v1/search?q=memory"

Responses are JSON. Every endpoint, parameter and response schema is described in the OpenAPI 3.1 spec, which you can load straight into an LLM tool-calling layer: every operation has a unique operationId, a description and typed schemas.

Authentication

None. The API is public and read-only, so there are no API keys, tokens or accounts. Send requests from anywhere; CORS is open (Access-Control-Allow-Origin: *).

Endpoints

Base URL: https://mashprime.dev/api/v1

posts pages with optional limit (1–100) and offset, and reports total. search takes a required q (1–200 characters) and an optional limit, and ranks posts by BM25 over the site's passage index (best match first). posts/{slug} returns the post's metadata plus its full text in markdown.

The passage index behind search is a static file too: /search/index.json holds every post split into heading-level passages (with the anchor of each section) plus one 384-dimension int8 embedding per post, which powers related posts. The site's own search box ranks it in your browser; no query is sent anywhere.

Errors

Every 4xx and 5xx response is an RFC 9457 application/problem+json object. Branch on the stable code; show detail to humans; follow hint to recover.

{
  "type": "https://mashprime.dev/developers/#error-post_not_found",
  "title": "Post not found",
  "status": 404,
  "detail": "No published post has the slug 'no-such-post'.",
  "instance": "/api/v1/posts/no-such-post",
  "code": "post_not_found",
  "hint": "Get valid slugs from GET /api/v1/posts.",
  "documentation": "https://mashprime.dev/developers/#errors"
}

Rate limits

60 requests per 60 seconds per client IP. Every response, including errors, tells you where you stand:

RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=57;t=42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790467242

RateLimit and RateLimit-Policy follow the IETF RateLimit header fields draft: r is requests remaining, t is seconds until the window resets. The X-RateLimit-* headers carry the same numbers, with X-RateLimit-Reset as Unix epoch seconds. Over the limit you get a 429 with code: "rate_limited" and a Retry-After header in seconds. Throttle when r gets low rather than waiting for the 429.

Versioning and deprecation

• The major version is in the path (/api/v1/) and echoed in the API-Version response header.
• Within a version, changes are additive only: new endpoints, new optional fields, new error codes. Ignore fields you don't recognise.
• Breaking changes ship as a new path version. The old version keeps working alongside it.
• A version being retired first sends Deprecation (RFC 9745) and Link: rel="successor-version" headers, then a Sunset (RFC 8594) date at least 90 days before it stops responding.
• Unknown versions return 404 with code: "unsupported_version".

Currently deprecated: the unversioned /api/posts.json build index. It still works and has no sunset date yet; it sends Deprecation and a successor link to /api/v1/posts.

MCP server

A remote Model Context Protocol server gives Claude, ChatGPT and other agents the site as native tools. Transport: streamable HTTP (stateless). No auth.

• Endpoint: https://mashprime.dev/mcp
• Server card: /.well-known/mcp.json
• Tools: site_info, list_posts, read_post, search_posts, related_posts

Claude Code:

claude mcp add --transport http mashprime https://mashprime.dev/mcp

Clients that take a JSON config:

{
  "mcpServers": {
    "mashprime": {
      "type": "http",
      "url": "https://mashprime.dev/mcp"
    }
  }
}

WebMCP

The pages are tool servers too. WebMCP is a W3C Web Machine Learning Community Group draft, started by Microsoft and Google, that lets a web page hand JavaScript tools to an AI agent running in the browser. When the browser exposes document.modelContext, every page here registers the tools below. Without it, the tool code isn't even downloaded. The site-wide read tools have the same names and schemas as the MCP server. The rest act on the open tab.

Read-only tools carry the readOnlyHint annotation. Results are MCP-style text content ({ content: [{ type: "text", text }] }). Bad input gets isError: true and a message that says what to fix. Every argument is checked against its schema. Tools only fetch this site's public files from the same origin, and only change local UI state: the page, the scroll position, the theme.

Try it

• Chrome 149 or later: turn on chrome://flags/#enable-webmcp-testing, then list and call the tools with a WebMCP client such as the Model Context Tool Inspector extension. Chrome and Edge also run WebMCP origin trials. This site is not enrolled, so use the flag.
• Other browsers: a polyfill such as MCP-B's @mcp-b/webmcp-polyfill installs document.modelContext. This site does not ship a polyfill. The tools only appear when your browser or extension provides WebMCP.
• From DevTools on any page: await document.modelContext.getTools(), then document.modelContext.executeTool(tool, { slug: "one-folder-to-autonomy" }).

When tools are live, the footer shows how many the page registered.

Implemented against WebMCP, Draft Community Group Report, 8 October 2026 (spec commit 4999377). It uses the imperative registerTool() API only: that revision dropped the declarative form API, and the spec defines no discovery file.

CLI

mashprime is a zero-dependency Node CLI that reads the site from a terminal: mashprime posts, mashprime read <slug>, mashprime search <query>, mashprime mcp. It is built on this API and published on npm as mashprime (Node 18+). No install needed:

npx mashprime
npx mashprime read one-folder-to-autonomy

Or install it: npm install -g mashprime. The in-browser terminal runs the same commands.

Machine-readable files

Every HTML page also has a markdown variant: send Accept: text/markdown. This page's is /developers/index.md.

Sandbox

The API is read-only, so production is the sandbox: nothing you send can change anything. Try a request (it counts toward your rate limit).

// response will appear here