Awesome Reviewers API

Endpoints

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 ().

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.

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:

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/.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 ().

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.