V60 Brew Log API overview

V60 Brew Log API is a tool for keeping and organizing personal day-to-day records of brewed coffee cups. Use the collected data to build your own dashboard or an app, tracking beans and recipes combinations to find out what works for you and what doesn't.

The API is built around the Hario V60 pour-over method; other brewing methods, such as espresso or French press, are out of scope.

What you can do with it

• Keep a brew journal. Record every cup you brew along with the beans, the recipe, and your rating.
• Find your best cups. Filter cups by minimum rating to see which brews worked.
• Compare cups. Filter cups by bean and recipe to see how a change in one variable affects the result.
• Build on top of your data. Use the API as a backend for your own dashboard, mobile app, or script.

The API stores and returns your records. It doesn't calculate statistics such as average ratings per bean. Your client application aggregates the data.

How it works

The API works with the following entities:

Entity	Description	Key fields
Bean	A coffee bean you brew with	Origin country, name, processing method, roaster, roast date
Recipe	A set of V60 brewing parameters	Grind size, coffee-to-water ratio, water temperature (90–100 °C), brew time, spin
Cup	A single brewed cup	Brew date, bean, recipe, rating (1–10), taste evaluation

A cup links a bean and a recipe together:

Bean ────┐
         ├──▶ Cup (rating, taste)
Recipe ──┘

Each cup references one bean by beanId and one recipe by recipeId. To record a cup, create the bean and the recipe first, then create the cup with their IDs.

A cup's taste evaluation is optional and consists of three scores, each from 1 to 10: body, sourness, and bitterness.

Operations

All three resources support the same set of operations:

Operation	Method and path
List records	GET /cups, GET /beans, GET /recipes
Create a record	POST /cups, POST /beans, POST /recipes
Get a record by ID	GET /{resource}/{id}
Replace a record	PUT /{resource}/{id}
Delete a record	DELETE /{resource}/{id}

List operations accept the limit query parameter and the following filters:

Resource	Filters
Cups	rating (minimum rating), origin, beanId, recipeId
Beans	origin, roaster
Recipes	grindSize, ratio

For request and response details, see the API reference for cups, beans, and recipes.

API basics

• Format. The API follows REST conventions. Requests and responses use JSON.
• Authentication. Every request requires an API key in the X-API-Key header. See Getting started.
• Errors. The API returns 400 for invalid parameters, 401 for a missing or invalid API key, and 404 for a record that doesn't exist. See Errors and restrictions.
• Version. The current API version is 0.1.0. The API is distributed under the MIT license.

Next steps

• Getting started: authenticate and record your first cup.
• Errors and restrictions: handle error responses.
• API reference: explore every endpoint.