# API Blueprint

> API Blueprint is a high-level API description language for web APIs, written in a
> Markdown-based syntax. It was created by Apiary and released under the MIT License.
> Alongside the format, the project operates a live, open parsing service at
> https://api.apiblueprint.org that parses API Blueprint and Swagger 2.0 into API
> Elements (Refract) and composes API Blueprint back out of API Elements.

Generated by API Evangelist on 2026-09-02 from all/api-blueprint/apis.yml and the
artifacts in this repository. API Blueprint does not publish an llms.txt of its own;
https://apiblueprint.org/llms.txt returned 404 when probed on 2026-09-02.

## Status

- The specification and all tooling repositories under the `apiaryio` GitHub
  organization were **archived on 2024-11-08** and are read-only.
- The last API Blueprint format release is **Format 1A9** (2015-06-08).
- The parsing service at `https://api.apiblueprint.org` was **probed live and
  answering on 2026-09-02**. It requires no authentication, no API key and no
  sign-up. It is not covered by any published SLA, status page or deprecation policy.

## API

- [Service root](https://api.apiblueprint.org/): `GET /` returns `application/hal+json` listing the affordances `parse` and `compose`.
- [Parse](https://api.apiblueprint.org/parser): `POST /parser` with `Content-Type: text/vnd.apiblueprint` (or `text/vnd.legacyblueprint`, `application/swagger+json`, `application/swagger+yaml`) and `Accept: application/vnd.refract.parse-result+json`. Returns 200 with an API Elements parse result; 415 on an unsupported input media type; 406 on an unsupported output media type; 422 with annotations when the document does not parse.
- [Compose](https://api.apiblueprint.org/composer): `POST /composer` with `Content-Type: application/vnd.refract+json` or `application/vnd.refract.parse-result+json`. Returns 200 `text/vnd.apiblueprint`; 415 on an unsupported content type or Refract version.

## Contracts

- [API Blueprint contract (provider-published)](https://github.com/apiaryio/api.apiblueprint.org/tree/master/source): the parsing service is described in API Blueprint itself. Saved verbatim in this repository under `apib/`.
- [OpenAPI 3.1 (derived by API Evangelist)](openapi/api-blueprint-parsing-service-openapi.yml): an operation-for-operation translation of the provider's API Blueprint contract, reconciled against live probes. The provider does not publish OpenAPI.
- [API Elements element schema (provider-published JSON Schema)](json-schema/api-blueprint-api-elements-element-schema.json)

## Specification

- [API Blueprint Specification](https://apiblueprint.org/documentation/specification.html)
- [MSON Specification](https://apiblueprint.org/documentation/mson/specification.html)
- [Tutorial](https://apiblueprint.org/documentation/tutorial.html)
- [RFC process](https://github.com/apiaryio/api-blueprint-rfcs)
- Media type: `text/vnd.apiblueprint`; file extension `.apib`

## Tooling

- [Drafter](https://github.com/apiaryio/drafter) — the reference C++ parser
- [Dredd](https://github.com/apiaryio/dredd) — contract testing against a running API
- [Gavel](https://github.com/apiaryio/gavel.js) — HTTP transaction validator
- [API Elements](https://github.com/apiaryio/api-elements) — the Refract structure the parser emits
- [apiaryio CLI (Ruby gem)](https://rubygems.org/gems/apiaryio)
- Full inventory with versions and release dates: `packages/api-blueprint-packages.yml`

## Commercial

- No plans, no pricing page, no paid tier, no billing surface. The specification is MIT
  licensed and the parsing service is free and unauthenticated. See `plans/api-blueprint-plans-pricing.yml`.
- No published rate limits and no rate-limit response headers observed on the wire.
  See `rate-limits/api-blueprint-rate-limits.yml`.

## Optional

- [Developer portal](https://apiblueprint.org/developers.html)
- [Tools directory](https://apiblueprint.org/tools.html)
- [Support](https://apiblueprint.org/support.html)
- [Issue tracker](https://github.com/apiaryio/api-blueprint/issues)
- [GitHub organization](https://github.com/apiaryio)