API Blueprint is a Markdown-based specification language for designing and documenting web APIs. It uses a human-readable syntax to describe resources, actions, requests, and responses for tooling, mocking, and documentation.
API Blueprint
API Blueprint is a Markdown-based specification language for designing and documenting web APIs, built by Apiary and released in 2013. Instead of the JSON or YAML structure that OpenAPI uses, it leans on human-readable Markdown to describe resources, actions, requests, and responses, so a definition reads almost like documentation while still being machine-parseable. It was one of the early machine-readable API definition formats, and it powered a real ecosystem of mocking, testing, and documentation tooling.
- Markdown-native syntax - API contracts are written in structured Markdown, so they are legible to humans before any tooling touches them.
- Design-first workflow - The format was built to describe an API before it exists, enabling mock servers and shared review early.
- MSON for data structures - The Markdown Syntax for Object Notation lets authors model request and response bodies in the same readable style.
- Tooling ecosystem - Parsers like Drafter and generators like Aglio turned blueprints into mocks, tests, and static documentation.
API Blueprint mattered as one of the formats that proved design-first, machine-readable contracts were worth adopting, competing directly with Swagger in the years before OpenAPI consolidated the space. In practice today it is largely legacy — the market coalesced around OpenAPI — but blueprints still turn up in older repositories and Apiary-era toolchains I encounter while profiling providers. It remains a useful reference point for understanding how the API definition landscape evolved and why a single dominant contract format ultimately won.
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
