Developer Documentation

Integrate BrewFYI data into your applications. Access coffee varieties, brew methods, origins, glossary terms, and guides through our JSON APIs and machine-readable endpoints.

API Demo

API Endpoints

All API endpoints return JSON responses with Content-Type: application/json. No authentication is required. Free to use.

Endpoint	Description	Cache
`GET /api/variety/{slug}/`	Coffee variety detail with species, origin, quality attributes	1h
`GET /api/method/{slug}/`	Brew method detail with time, temperature, grind, ratio	1h
`GET /api/search/?q=`	Search across 8 entity types (varieties, countries, regions, methods, processing, roasts, guides, glossary)	5m
`GET /api/term/{slug}/`	Glossary term definition with category and related terms	1h
`GET /api/compare/?slug1=&slug2=`	Compare two coffee varieties (species, origin, genetic group)	1h
`GET /api/processing/{slug}/`	Processing method detail with drying time and flavor impact	1h
`GET /api/roast/{slug}/`	Roast level detail with Agtron number and temperature range	1h
`GET /api/country/{slug}/`	Coffee-producing country detail with coordinates	1h
`GET /api/random/`	Random coffee variety with full detail	none
`GET /api/openapi.json`	OpenAPI 3.1.0 spec (CORS enabled)	none

Search API

GET /api/search/?q={query}

curl "https://brewfyi.com/api/search/?q=bourbon"

{
  "results": [
    {"name": "Bourbon", "slug": "bourbon", "type": "variety", "url": "/variety/bourbon/"},
    {"name": "Yellow Bourbon", "slug": "yellow-bourbon", "type": "variety", "url": "/variety/yellow-bourbon/"}
  ],
  "total": 2
}

Variety Detail

GET /api/variety/{slug}/

curl "https://brewfyi.com/api/variety/bourbon/"

{
  "name": "Bourbon",
  "slug": "bourbon",
  "url": "/variety/bourbon/",
  "species": "Arabica",
  "origin_country": "Yemen",
  "genetic_group": "Bourbon",
  "is_featured": true,
  "description": "One of the most important Arabica varieties...",
  "yield_potential": "Medium",
  "quality_potential": "Excellent",
  "altitude_range": "1000-2000m"
}

Glossary Term

GET /api/term/{slug}/

curl "https://brewfyi.com/api/term/cupping/"

{
  "term": "Cupping",
  "slug": "cupping",
  "definition": "A standardized method of evaluating coffee quality by tasting brewed samples.",
  "extended_description": "Professional coffee tasting protocol...",
  "category": "Quality & Grading",
  "related_terms": [{"term": "Q Grader", "slug": "q-grader"}],
  "url": "/glossary/cupping/"
}

AI / LLM Integration

BrewFYI provides machine-readable content summaries following the llms.txt standard. These endpoints help AI models understand and reference our content.

/llms.txt text/plain

A concise summary of BrewFYI's content structure and key pages. Designed for AI models to quickly understand what the site offers and how it is organized.

# BrewFYI.com

> Coffee encyclopedia — varieties, origins, brewing methods,
  and guides in 15 languages.

## Browse
- [Varieties](https://brewfyi.com/varieties/) — 72 coffee varieties
- [Origins](https://brewfyi.com/countries/) — 80+ producing countries
  ...

.md Endpoints text/markdown

Append .md to any page URL for a Markdown version optimized for LLMs. Example: https://brewfyi.com/variety/bourbon.md

AI Crawler Policy: Our robots.txt explicitly allows GPTBot, ClaudeBot, and Google-Extended crawlers.

SEO & Standards

Standard endpoints for search engines, crawlers, and security researchers.

Endpoint	Standard	Description
/sitemap.xml	Sitemaps 0.9	Sitemap index with per-section sitemaps covering all content types
/robots.txt	REP	Crawler directives with explicit AI bot permissions
/.well-known/security.txt	RFC 9116	Security vulnerability reporting contact information

Structured Data

Every page includes JSON-LD structured data for rich search results:

CollectionPage — variety, country, and method index pages
Article — guide pages with author, dates, and reading time
DefinedTerm — glossary terms with definitions
WebApplication — interactive tools (brew calculators, flavor wheel)
BreadcrumbList — navigation breadcrumbs on all pages
WebSite — with SearchAction for sitelinks search box

Internationalization

All content pages include hreflang alternate links for 15 languages: English (default), Korean, Japanese, Chinese (Simplified), Spanish, French, German, Portuguese, Russian, Arabic, Hindi, Thai, Vietnamese, Indonesian, and Turkish.

OpenAPI Specification

A machine-readable OpenAPI 3.1.0 specification is available for our JSON APIs. Use it with tools like Swagger UI, Postman, or code generators.

Download openapi.json

Fetch via command line

# Download the OpenAPI spec
curl "https://brewfyi.com/api/openapi.json" -o openapi.json

# Pretty-print
curl -s "https://brewfyi.com/api/openapi.json" | python -m json.tool

Rate Limits & Usage

Our APIs are free to use with no authentication required. To ensure fair access for everyone, please follow these guidelines:

Keep requests under 60 requests per minute per IP address
Include a descriptive User-Agent header identifying your application
Cache responses locally when possible — our API responses include Cache-Control headers
For bulk data access, use the sitemap to discover all URLs, then scrape individual pages

If you need higher-volume access or have integration questions, reach out via the contact in our security.txt.

Quick Reference

Variety Detail /api/variety/{slug}/

Brew Method /api/method/{slug}/

Search /api/search/?q=...

Glossary Term /api/term/{slug}/

Compare /api/compare/?slug1=&slug2=

Processing /api/processing/{slug}/

Roast Level /api/roast/{slug}/

Country /api/country/{slug}/

Random Variety /api/random/

OpenAPI Spec /api/openapi.json

llms.txt /llms.txt