API · Awesome Reviewers

Endpoints

Resource	Path	Type	What it is
OpenAPI description	`/openapi.json`	application/vnd.oai.openapi+json;version=3.1	OpenAPI 3.1 description of every endpoint listed here.
API documentation	`/api/`	text/html	Human-readable reference for the endpoints, error format and markdown variants.
Site overview	`/raw/site.md`	text/markdown	The homepage as markdown: what this is, the endpoints, the domains.
Corpus index	`/raw/index.json`	application/json	Every instruction: slug, title, description, domain, topic, language, source, updated, raw URL.
Single instruction	`/raw/.md`	text/markdown	One instruction as plain markdown, with a commented header carrying its metadata.
Domain bundle	`/raw/bundles/.md`	text/markdown	Every instruction in one domain, concatenated into a single markdown file.
Source discussions	`/.json`	application/json	The review discussions one instruction was derived from.
Search index	`/assets/data/search.json`	application/json	Column-oriented index used by the search box: smaller, truncated descriptions.
LLM index	`/llms.txt`	text/plain	Domain-grouped listing of the whole corpus with raw URLs.
Sitemap	`/sitemap.xml`	application/xml	Every HTML page on the site.

Every path is served over HTTPS from https://awesomereviewers.com, GET only. The same list, with schemas, is in /openapi.json — OpenAPI 3.1, versioned by the corpus date it describes (2026-08-12).

OpenAPI description

/openapi.json is an OpenAPI 3.1 document covering every endpoint above: parameters, response media types, the schema of each index, and the error format. Every page on this site links it as <link rel="service-desc">, so a client that lands anywhere can find it.

# fetch the description
curl -s https://awesomereviewers.com/openapi.json | jq '.paths | keys'

# every domain slug the bundles endpoint accepts
curl -s https://awesomereviewers.com/openapi.json \
  | jq -r '.paths["/raw/bundles/{domain}.md"].get.parameters[0].schema.enum[]'

Errors

Error responses follow RFC 9457 problem details, with two extension members: code, stable for matching, and resolution, saying what to do next. Because the site is served as static files, a client that asks for HTML gets the 404 page, which carries the same problem details in a <script type="application/problem+json" id="problem"> element and a markdown recovery block.

404 — Resource not found

Nothing is published at this path. Every published path is listed in https://awesomereviewers.com/raw/index.json and https://awesomereviewers.com/llms.txt. Look the slug up there and retry.

{
  "type": "https://awesomereviewers.com/api/#error-not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "Nothing is published at this path.",
  "code": "not_found",
  "resolution": "Every published path is listed in https://awesomereviewers.com/raw/index.json and https://awesomereviewers.com/llms.txt. Look the slug up there and retry."
}

406 — No acceptable representation

The Accept header rules out every representation of this resource. Send Accept: text/markdown for markdown, text/html for the rendered page, application/json for the JSON endpoints, or */* to take whatever is served.

{
  "type": "https://awesomereviewers.com/api/#error-not-acceptable",
  "title": "No acceptable representation",
  "status": 406,
  "detail": "The Accept header rules out every representation of this resource.",
  "code": "not_acceptable",
  "resolution": "Send Accept: text/markdown for markdown, text/html for the rendered page, application/json for the JSON endpoints, or */* to take whatever is served."
}

Markdown variants

Every page that has a markdown twin links it with <link rel="alternate" type="text/markdown">, and the mapping is mechanical, so an agent can rewrite a URL instead of parsing HTML:

Page	Markdown
`/reviewers/<slug>/`	`/raw/<slug>.md`
`/domains/<domain>/`	`/raw/bundles/<domain>.md`
`/`	`/raw/site.md`
whole corpus	`/llms.txt`

Static hosting cannot vary a response on the Accept header, so Accept: text/markdown against an HTML page returns HTML. Follow the rel="alternate" link, or rewrite the path, to get markdown.

Examples

# one instruction
curl https://awesomereviewers.com/raw/bmad-method-api-contract-clarity.md

# a whole domain in one file
curl https://awesomereviewers.com/raw/bundles/llm-infra.md

# everything updated since a date, as slugs
curl -s https://awesomereviewers.com/raw/index.json \
  | jq -r '.entries[] | select(.updated >= "2026-01-01") | .slug'

# assemble a system prompt from one domain
curl -s https://awesomereviewers.com/raw/index.json \
  | jq -r '.entries[] | select(.domain == "orchestration") | .raw' \
  | xargs -n1 curl -s > orchestration.md

Freshness

Every instruction carries the date of the most recent review comment behind it, and every domain carries the newest date among its instructions. Both are exposed in /raw/index.json and in the front matter of each raw file, so a scheduled job can diff against its last run instead of refetching the corpus.

The corpus was last updated 2026-08-12 (2026-08-12).

From the repository

If you would rather not fetch over HTTP, the source of truth is _reviewers/: one markdown instruction per file, plus a sibling JSON file holding the review discussions it was derived from. Clone it and run python build_data.py to regenerate every artifact listed above locally.

Terms

Apache-2.0, same as the repository. The instructions are distilled from public review discussions; they are not official guidance from the projects they were derived from.

Awesome Reviewers API