Documentation

API Reference

The Tea API is a free, static JSON API for teas, ingredients, health benefits, and brewing data. No authentication required — every endpoint is a plain GET request.

All responses are fully resolved — foreign key IDs are expanded inline so you never need to make multiple requests.

Prefer tooling? An OpenAPI 3.0 spec is available at /api/v1/openapi.yaml — import it into Postman, Insomnia, or any OpenAPI-compatible client for instant autocompletion.

Base URL

https://theteaapi.com/api/v1

Response format

All endpoints return JSON with Content-Type: application/json. Array endpoints return a JSON array; single-resource endpoints return a JSON object.

The caffeine_level field is an enum with four values: none, low, medium, high.

GET

List all teas

Returns an array of all teas in the catalogue. Each tea object is fully expanded — category, characteristics, health benefits, and ingredient composition are all resolved inline.

GET https://theteaapi.com/api/v1/teas.json

Example response

200 OK Try it ↗

{
  "id": 1,
  "name": "Sencha",
  "slug": "sencha",
  "origin": "Shizuoka & Uji, Japan",
  "caffeine_level": "medium",
  "temperature_celsius": 75,
  "steeping_time_minutes": 2,
  "category": {
    "id": 1,
    "slug": "true-tea",
    "name": "True Tea"
  },
  "tea_type": {
    "id": 1,
    "slug": "green",
    "name": "Green Tea"
  },
  "base_type": null,
  "characteristics": [
    {
      "id": 1,
      "name": "Earthy"
    },
    {
      "id": 6,
      "name": "Grassy"
    }
  ],
  "...": "..."
}

GET

Get tea by slug

Returns a single tea by its URL-safe slug identifier. The response shape is identical to a single item in the teas list.

GET https://theteaapi.com/api/v1/teas/{slug}.json

Parameters

Name	Type	Description
slug (required)	string	URL-safe tea identifier, e.g. sencha, earl-grey

GET

List all categories

Returns all tea categories with an additional tea_count field showing how many teas belong to each category.

GET https://theteaapi.com/api/v1/categories.json

Example response

200 OK Try it ↗

[
  {
    "id": 1,
    "slug": "true-tea",
    "name": "True Tea",
    "description": "...",
    "tea_count": 14
  },
  {
    "id": 2,
    "slug": "blend",
    "name": "Blend",
    "description": "...",
    "tea_count": 5
  },
  {
    "id": 3,
    "slug": "tisane",
    "name": "Tisane (Herbal Tea)",
    "description": "...",
    "tea_count": 6
  }
]

GET

List all tea types

Returns the six true-tea processing types (green, white, yellow, black, oolong, pu-erh) with a tea_count field. Use this to understand the type of each true tea — blends and tisanes reference this via the base_type field.

GET https://theteaapi.com/api/v1/tea-types.json

Example response

200 OK Try it ↗

[
  {
    "id": 1,
    "slug": "green",
    "name": "Green Tea",
    "description": "...",
    "tea_count": 5
  },
  {
    "id": 2,
    "slug": "white",
    "name": "White Tea",
    "description": "...",
    "tea_count": 2
  },
  {
    "id": 3,
    "slug": "black",
    "name": "Black Tea",
    "description": "...",
    "tea_count": 4
  },
  {
    "id": 4,
    "slug": "oolong",
    "name": "Oolong Tea",
    "description": "...",
    "tea_count": 2
  },
  {
    "id": 5,
    "slug": "puerh",
    "name": "Pu-erh Tea",
    "description": "...",
    "tea_count": 1
  },
  {
    "id": 6,
    "slug": "yellow",
    "name": "Yellow Tea",
    "description": "...",
    "tea_count": 1
  }
]

GET

List all ingredients

Returns all ingredients used across the tea catalogue, including descriptions and image URLs where available.

GET https://theteaapi.com/api/v1/ingredients.json

GET

List all health benefits

Returns all catalogued health benefit entries referenced by teas.

GET https://theteaapi.com/api/v1/health-benefits.json

GET

List all characteristics

Returns all flavour and aroma characteristic tags used to describe teas.

GET https://theteaapi.com/api/v1/characteristics.json

GET

API metadata

Returns the API version, generation timestamp, total counts, and a full list of available endpoints.

GET https://theteaapi.com/api/v1/meta.json

Example response

200 OK Try it ↗

{
  "version": "1.0.0",
  "tea_count": 26,
  "category_count": 3,
  "tea_type_count": 6,
  "base_url": "https://theteaapi.com/api/v1",
  "endpoints": [
    "..."
  ]
}