API specifications for the AI era

API specs that humans and machines actually understand

You might know them as OpenAPI documents, Swagger docs, API contracts, or API schemas—they're all ways to describe what your API does. MAPI is a Markdown-based format for writing these descriptions, designed for clarity. Specs that developers can read and LLMs can consume—no more wrestling with walls of YAML.

Human-First Readability

Markdown is already how developers write docs. MAPI embraces that—your API specs read like documentation, not configuration files.

AI-Native Design

TypeScript interfaces, clear intentions, and structured metadata make MAPI ideal for LLMs to parse and act upon—no hallucinated endpoints.

Full Interoperability

Convert freely between MAPI, OpenAPI, and AsyncAPI. Use MAPI for authoring, export to OpenAPI when tools demand it.

Progressive Disclosure

Not everyone needs the full 30-page spec. MAPI uses reference cards—focused guides for specific tasks. Start with the disclosure document, load only what you need. This is especially powerful for AI agents: give them just the right context without overwhelming their token window.

Start with the Disclosure document to identify your task

Load the specific reference card you need

Fall back to the full spec only for edge cases

Why not just OpenAPI?

OpenAPI was built for a different era—REST resources, URL-centric design, code generators. Modern APIs have moved on. MAPI is built for how APIs actually work today.

The OpenAPI Problem

Resource-oriented thinking — URLs as the organizing principle made sense for REST, but modern APIs are capability-oriented
No native WebSocket/SSE support — You need AsyncAPI for event-driven patterns, fragmenting your spec
Two specs to maintain — OpenAPI + AsyncAPI means duplicate schemas, drift, and confusion
Designed for machines — JSON Schema verbosity makes specs hard for humans and LLMs to parse

The MAPI Approach

Capability-oriented — Organize by what your API does, not what URLs it exposes
Native event support — WebSockets, SSE, and streaming are first-class citizens, same spec
One unified format — REST, GraphQL, WebSocket, SSE—all in one document
Human and AI readable — Markdown + TypeScript interfaces that both developers and LLMs understand

Built for the AI era

MAPI's Intentions explain when to use each capability. Logic Constraints make business rules explicit. LLMs don't hallucinate endpoints—they understand your API.