Developer Documentation

Integrate TeaFYI data into your applications. Access tea varieties, categories, health compounds, teaware, 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}/`	Full tea variety with category, origin, chemical profile	1h
`GET /api/category/{slug}/`	Tea category detail (oxidation, caffeine, flavor)	1h
`GET /api/search/?q=`	Search across 8 entity types (varieties, categories, countries, regions, compounds, teaware, guides, glossary)	5m
`GET /api/term/{slug}/`	Glossary term tooltip (definition, category)	1h
`GET /api/compare/?slug1=&slug2=`	Compare two tea categories (oxidation, caffeine, processing)	1h
`GET /api/compound/{slug}/`	Health compound with formula and benefits	1h
`GET /api/teaware/{slug}/`	Teaware detail with material and recommended teas	1h
`GET /api/country/{slug}/`	Tea-producing country with coordinates	1h
`GET /api/random/`	Random tea 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://teafyi.com/api/search/?q=green"

{
  "results": [
    {"name": "Green Tea", "slug": "green-tea", "type": "category", "url": "/categories/green-tea/"},
    {"name": "Longjing", "slug": "longjing", "type": "variety", "url": "/varieties/longjing/"}
  ],
  "total": 2
}

Variety Detail

GET /api/variety/{slug}/

curl "https://teafyi.com/api/variety/longjing/"

{
  "name": "Longjing",
  "slug": "longjing",
  "url": "/varieties/longjing/",
  "category": "Green Tea",
  "origin_country": "China",
  "cultivar_name": "Longjing #43",
  "oxidation_level_pct": 0,
  "caffeine_mg_per_100ml": 20.0,
  "l_theanine_mg": 30.0,
  "harvest_season": "Spring",
  "altitude_preference": "200-800m",
  "leaf_type": "One bud two leaves",
  "is_featured": true,
  "description": "..."
}

Glossary Term

GET /api/term/{slug}/

curl "https://teafyi.com/api/term/gongfu/"

{
  "term": "Gongfu",
  "slug": "gongfu",
  "definition": "A traditional Chinese tea preparation method using small teapots and short steeping times.",
  "category": "Brewing Methods",
  "content": null,
  "url": "/glossary/gongfu/"
}

AI / LLM Integration

TeaFYI 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 TeaFYI's content structure and key pages. Designed for AI models to quickly understand what the site offers and how it is organized.

/llms-full.txt text/plain

Extended version with complete URL patterns, i18n language codes, and page-level structure.

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

SEO & Standards

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

Internationalization

All content pages include hreflang alternate links for 15 languages.

OpenAPI Specification

A machine-readable OpenAPI 3.1.0 specification is available for our JSON APIs.

Download openapi.json

curl -s "https://teafyi.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:

Keep requests under 60 requests per minute per IP address
Include a descriptive User-Agent header
Cache responses locally when possible

Quick Reference

Variety Detail /api/variety/{slug}/

Category Detail /api/category/{slug}/

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

Glossary Term /api/term/{slug}/

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

Compound /api/compound/{slug}/

TeaWare /api/teaware/{slug}/

Country /api/country/{slug}/

Random Variety /api/random/

OpenAPI Spec /api/openapi.json

llms.txt /llms.txt

Markdown Suffix any-page.md