API documentation

The Meaning of Numbers API documentation

HTTP and agent interfaces this origin actually runs. There is no public API key and no OAuth login for agents. Example requests are below.

Authentication

Public machine surfaces need no token. RFC 9728 metadata at /.well-known/oauth-protected-resource lists this origin in authorization_servers so a walkthrough can fetch AS metadata, and keeps bearer_methods_supported empty. Public reads need no token. Humans sign in with a magic link. Paid readings use Stripe Checkout. See auth.md.

Endpoints

  • GET /api/v1 - versioned JSON index
  • GET /api/v1/pages - paginated published paths
  • GET /api - compatibility alias of /api/v1
  • POST /api/checkout - start Stripe Checkout for a reading
  • POST /api/reading - stream a paid reading (sessionId)
  • POST /mcp - Streamable HTTP MCP (site guide, markdown, free numbers)
  • GET /mcp - SSE stream when Accept includes text/event-stream; otherwise the server card
  • GET /ask - NLWeb-style published-path list
  • openapi.json - OpenAPI 3.1

Unknown /api/... paths return RFC 9457 application/problem+json with code, message, and resolution. GET on a POST-only route returns 405.

Example requests

GET /api HTTP/1.1
Host: themmeaningofnumbers.com
Accept: application/json
GET /api/checkout HTTP/1.1
Host: themmeaningofnumbers.com
Accept: application/json

That GET returns 405 problem+json (code: method_not_allowed). The live call is:

POST /api/checkout HTTP/1.1
Host: themmeaningofnumbers.com
Content-Type: application/json

{"slug":"life-path","tier":"full","name":"Ada Example","m":12,"d":10,"y":1990}
POST /mcp HTTP/1.1
Host: themmeaningofnumbers.com
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example","version":"1"}}}

Dual-Accept POST returns 200 text/event-stream (event: message) plus Mcp-Session-Id.notifications/initialized is 202 empty. GET /mcp with Accept: text/event-stream is the SSE stream (not 405). The card is at /mcp/server-card and /server.json.

Versioning and deprecation

Public read operations are version 1 at /api/v1. Breaking changes will use /api/v2. The optional API-Version: 1 header is echoed on responses. Deprecated operations will send Deprecation and Sunset headers. None are deprecated today.

Pagination

GET /api/v1/pages?page=1&per_page=20 lists published HTML paths plus their markdown twins. Link headers carry first, prev, next, and last. Maximum per_page is 50.

Rate limits

Responses send IETF RateLimit / RateLimit-Policy plus RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (120 requests / 60 seconds, courtesy). 429 includes Retry-After.

More

Developer portal · Developer resources · pricing.md · llms.txt