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. posts/{slug} returns the post's metadata plus its full text in markdown.

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

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"
    }
  }
}

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