{"openapi":"3.1.0","info":{"title":"Awesome Reviewers API","version":"2026-08-12","summary":"Read-only endpoints for the Awesome Reviewers instruction corpus.","description":"Awesome Reviewers publishes expert engineering instructions for AI and infrastructure domains, distilled from code review discussions in production open-source repositories.\n\nEvery endpoint is a static file served over HTTPS. There is no key, no rate limit and no method other than GET. Responses are immutable for a given build; the `updated` field on each entry carries the date of the most recent review comment behind it, so a scheduled job can diff against its last run instead of refetching the corpus.\n\nErrors follow RFC 9457 problem details.","termsOfService":"https://awesomereviewers.com/api/#terms","contact":{"name":"Awesome Reviewers","url":"https://github.com/baz-scm/awesome-reviewers"},"license":{"name":"Apache-2.0","identifier":"Apache-2.0"}},"externalDocs":{"description":"Awesome Reviewers API documentation","url":"https://awesomereviewers.com/api/"},"servers":[{"url":"https://awesomereviewers.com","description":"Production"}],"tags":[{"name":"instructions","description":"Single instructions and domain bundles."},{"name":"indexes","description":"Machine-readable indexes of the whole corpus."},{"name":"discovery","description":"Descriptions of the site itself."}],"paths":{"/raw/index.json":{"get":{"operationId":"getIndex","summary":"Machine-readable index of the whole corpus","description":"One row per instruction plus one row per domain. The `raw` field on each entry is the URL of that instruction as markdown.","tags":["indexes"],"responses":{"200":{"description":"The corpus index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Index"}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}}}}},"/raw/site.md":{"get":{"operationId":"getSiteOverview","summary":"The homepage as markdown","description":"What the corpus is, the endpoints, and one row per domain with its instruction count and bundle URL. The short alternative to /llms.txt.","tags":["discovery"],"responses":{"200":{"description":"The site overview","content":{"text/markdown":{"schema":{"type":"string"}}}},"406":{"description":"No acceptable representation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}}}}},"/raw/{slug}.md":{"get":{"operationId":"getInstruction","summary":"One instruction as markdown","description":"The instruction body, preceded by an HTML comment carrying its title, domain, topic, language, source repository, last-updated date and the URL of its page. Slugs come from `/raw/index.json`.","tags":["instructions"],"parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"The instruction","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}},"406":{"description":"No acceptable representation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}}}}},"/raw/bundles/{domain}.md":{"get":{"operationId":"getDomainBundle","summary":"Every instruction in one domain, concatenated","description":"One markdown file per domain: a heading, the domain blurb, its counts and then every instruction in it, each with a source comment.","tags":["instructions"],"parameters":[{"name":"domain","in":"path","required":true,"description":"Domain slug.","schema":{"type":"string","enum":["ai-agents","llm-infra","ml-systems","orchestration","cloud-infra","data-systems","observability","security","runtimes","devtools","app-frameworks","docs"]},"example":"ai-agents"}],"responses":{"200":{"description":"The domain bundle","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}},"406":{"description":"No acceptable representation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}}}}},"/{slug}.json":{"get":{"operationId":"getDiscussions","summary":"The review discussions one instruction was derived from","description":"Provenance for a single instruction: the review threads it was distilled from, each with its comments, authors and timestamps.","tags":["instructions"],"parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"The source discussions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Discussion"}}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}}}}},"/assets/data/search.json":{"get":{"operationId":"getSearchIndex","summary":"Compact column-oriented search index","description":"The index the search box fetches. Repeated values (domain, topic, language, repository) are interned: each entry holds their positions in the sibling arrays. Descriptions are truncated. Prefer `/raw/index.json` unless size matters.","tags":["indexes"],"responses":{"200":{"description":"The search index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchIndex"}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","summary":"Domain-grouped index of the corpus for LLM consumers","tags":["indexes"],"responses":{"200":{"description":"The llms.txt index","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"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."}},"text/html":{"schema":{"type":"string","description":"Served to clients that accept HTML. The page carries the same problem details in a script element with id \"problem\", plus a markdown recovery block."}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenapi","summary":"This description","tags":["discovery"],"responses":{"200":{"description":"The OpenAPI description","content":{"application/vnd.oai.openapi+json;version=3.1":{"schema":{"type":"object"}}}}}}},"/sitemap.xml":{"get":{"operationId":"getSitemap","summary":"Every HTML page on the site","tags":["discovery"],"responses":{"200":{"description":"The sitemap","content":{"application/xml":{"schema":{"type":"string"}}}}}}}},"components":{"parameters":{"Slug":{"name":"slug","in":"path","required":true,"description":"Instruction slug, as published in /raw/index.json.","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"example":"bmad-method-api-contract-clarity"}},"schemas":{"Entry":{"type":"object","description":"One instruction.","required":["slug","title","domain","raw"],"properties":{"slug":{"type":"string","example":"bmad-method-api-contract-clarity"},"title":{"type":"string"},"description":{"type":"string"},"repository":{"type":"string","description":"Source repository, as owner/name."},"domain":{"type":"string","enum":["ai-agents","llm-infra","ml-systems","orchestration","cloud-infra","data-systems","observability","security","runtimes","devtools","app-frameworks","docs"]},"topic":{"type":"string"},"language":{"type":"string"},"updated":{"type":"string","format":"date","description":"Date of the most recent review comment behind it."},"comments":{"type":"integer","minimum":0},"stars":{"type":"integer","minimum":0,"description":"Stars on the source repository when it was imported."},"raw":{"type":"string","format":"uri","description":"URL of this instruction as markdown."}}},"Domain":{"type":"object","description":"One domain, with its bundle URL.","required":["slug","title","count","bundle"],"properties":{"slug":{"type":"string","enum":["ai-agents","llm-infra","ml-systems","orchestration","cloud-infra","data-systems","observability","security","runtimes","devtools","app-frameworks","docs"]},"title":{"type":"string"},"count":{"type":"integer","minimum":0},"updated":{"type":"string","format":"date"},"bundle":{"type":"string","format":"uri"}}},"Index":{"type":"object","required":["generated","count","site","domains","entries"],"properties":{"generated":{"type":"string","format":"date-time","description":"When this index was built."},"count":{"type":"integer","minimum":0},"site":{"type":"string","format":"uri"},"domains":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}},"entries":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}},"SearchIndex":{"type":"object","required":["fields","entries"],"properties":{"fields":{"type":"array","items":{"type":"string"},"description":"Column names, in the order each entry row holds them."},"domains":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"repositories":{"type":"array","items":{"type":"string"}},"entries":{"type":"array","description":"One row per instruction. Domain, topic, language and repository are indexes into the arrays above.","items":{"type":"array"}}}},"Discussion":{"type":"object","description":"One review thread an instruction was derived from.","properties":{"created_at":{"type":"string","format":"date-time"},"discussion_comments":{"type":"array","items":{"type":"object","properties":{"comment_author":{"type":"string"},"comment_created_at":{"type":"string","format":"date-time"}}}}}},"Problem":{"type":"object","description":"RFC 9457 problem details, with `code` and `resolution` extensions.","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri","description":"URI identifying the problem type; resolves to its documentation.","enum":["https://awesomereviewers.com/api/#error-not-found","https://awesomereviewers.com/api/#error-not-acceptable"]},"title":{"type":"string"},"status":{"type":"integer","enum":[404,406]},"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference","description":"The path that produced the error."},"code":{"type":"string","description":"Stable machine-readable code for this problem type.","enum":["not_found","not_acceptable"]},"resolution":{"type":"string","description":"What to do next."}}}}}}