Public API

Small, stateless JSON endpoints on this same Next.js deployment. There is no authentication, no database, and no retention: each request is computed and forgotten. Same markdown emitters as the generator (formatNygardMarkdown, formatMadrMarkdown, etc.). Open API index. Per-IP rate limits apply (rough in-process windows; response 429 with Retry-After). POST /api/generate-adrbodies are capped at 32 KiB (413 if larger).

Endpoints

• GET https://adr.zone/api — service name, version, endpoint list
• GET https://adr.zone/api/formats — supported formats, required/optional fields
• POST https://adr.zone/api/generate-adr — JSON in, markdown plus slug out

Example

curl -s -X POST "https://adr.zone/api/generate-adr" \
  -H "Content-Type: application/json" \
  -d '{"title":"Use PostgreSQL for new services","context":"We need one default DB for new work.","decision":"Default to PostgreSQL 15+ for new stateful services."}' | jq

Supported formats

Default format is nygard. iso-42010 is an ISO/IEC/IEEE 42010–inspired record, not a formal “ISO 42010 ADR standard.”

• nygard — Nygard ADR

  Classic markdown ADR: status, context, decision, and consequences. Matches the shape popularized in engineering blogs and adr-tools-style workflows.

  Required: title, context, decision

  Optional: format, status, consequences, moreInformation, notes

• madr — MADR (Markdown ADR)

  Structured sections for drivers, options, and confirmation—handy for automation and indexed ADR sets.

  Required: title, context, decision

  Optional: format, status, consequences, decisionDrivers, consideredOptions, confirmation, moreInformation, notes

• y-statement — Y-Statement

  Single reviewable Y-style sentence plus a field list. Optional fields map to the sentence content.

  Required: title, context, decision

  Optional: format, status, consequences, concern, decisionAgainst, outcome, tradeoff, notes, moreInformation

• iso-42010 — ISO 42010–inspired

  ISO/IEC/IEEE 42010–inspired decision record: stakeholders, concerns, and views—not an official “ADR under ISO 42010,” but compatible vocabulary for architecture description.

  Required: title, context, decision

  Optional: format, status, consequences, system, stakeholders, concerns, viewpoint, rationale, architecturalImpact, traceability, moreInformation, notes

On this site

Generator · Templates · Examples · Raw /api/formats JSON