Skip to main content

Getting started

This guide walks you through your first requests to the V60 Brew Log API: you authenticate, record a cup together with its bean and recipe, and get a list of your cups.

Before you begin​

  • You need an HTTP client. The examples in this guide use curl. You can also use Postman or send requests from the API reference in your browser.
  • Read the Introduction to learn how beans, recipes, and cups relate to each other.

Base URL​

Send all requests to the sandbox:

https://brewlog-api.bellsandthistl.es

About the sandbox​

note

The sandbox returns example responses based on the API specification. Keep in mind the following:

  • The sandbox doesn't store data. A record you create with POST isn't returned by later requests.
  • The sandbox returns the same example records for every request. The IDs in responses are example IDs.
  • The sandbox validates query parameters, such as limit and rating, but doesn't apply them. A list request always returns the full example list.

Authenticate​

Pass your API key in the X-API-Key header of every request. The sandbox accepts any non-empty value as an API key. Use only Latin letters, digits, and hyphens:

-H "X-API-Key: my-test-key"

If the header is missing, the API returns 401 Unauthorized:

{
  "error": "Header must contain API-Key"
}

Record your first cup​

A cup references a bean and a recipe, so you create them first.

Step 1. Add a bean​

Send a POST request to /beans. The origin, name, and roaster fields are required:

curl -X POST https://brewlog-api.bellsandthistl.es/beans \
  -H "X-API-Key: my-test-key" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "Colombia",
    "name": "Las Perlitas Honey",
    "method": "Honey",
    "roaster": "Koppa Coffee",
    "roastDate": "2026-08-24"
  }'

The API returns 201 Created and the new bean. Save the beanId value for step 3:

{
  "beanId": "1",
  "origin": "Colombia",
  "name": "Las Perlitas Honey",
  "method": "Honey",
  "roaster": "Koppa Coffee",
  "roastDate": "2026-08-24"
}

Step 2. Add a recipe​

Send a POST request to /recipes. The grindSize, ratio, waterTemp, and brewTime fields are required. Water temperature must be between 90 and 100 °C, and brew time is in seconds:

curl -X POST https://brewlog-api.bellsandthistl.es/recipes \
  -H "X-API-Key: my-test-key" \
  -H "Content-Type: application/json" \
  -d '{
    "grindSize": "13",
    "ratio": "1:16",
    "waterTemp": 94,
    "brewTime": 150,
    "spin": true
  }'

The API returns 201 Created and the new recipe. Save the recipeId value for step 3:

{
  "recipeId": "1",
  "grindSize": "13",
  "ratio": "1:16",
  "waterTemp": 94,
  "brewTime": 150,
  "spin": true
}

Step 3. Add a cup​

Send a POST request to /cups with the bean and recipe IDs. The date, beanId, recipeId, and rating fields are required. Use the YYYY-MM-DD format for the date. The taste object is optional:

curl -X POST https://brewlog-api.bellsandthistl.es/cups \
  -H "X-API-Key: my-test-key" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-09-01",
    "beanId": "1",
    "recipeId": "1",
    "rating": 8,
    "taste": { "body": 6, "sourness": 4, "bitterness": 3 }
  }'

The API returns 201 Created and the new cup:

{
  "cupId": "1",
  "date": "2026-09-01",
  "beanId": "1",
  "recipeId": "1",
  "rating": 8,
  "taste": { "body": 6, "sourness": 4, "bitterness": 3 }
}

List your cups​

To get a list of your cups, send a GET request to /cups:

curl https://brewlog-api.bellsandthistl.es/cups \
  -H "X-API-Key: my-test-key"

The API returns a JSON array of cups, including the cup you've just added:

[
  {
    "cupId": "1",
    "date": "2026-09-01",
    "beanId": "1",
    "recipeId": "1",
    "rating": 8,
    "taste": { "body": 6, "sourness": 4, "bitterness": 3 }
  }
]

Find your best cups​

To get only highly rated cups, pass the minimum rating in the rating query parameter:

curl "https://brewlog-api.bellsandthistl.es/cups?rating=8" \
  -H "X-API-Key: my-test-key"

You can also filter cups by origin, beanId, and recipeId. For all filters, see Get a list of cups.

Send requests from the browser​

Every endpoint page in the API reference has a request panel. To send a request from the browser:

  1. Open an endpoint page, for example, Get a list of cups.
  2. In the authentication section of the request panel, enter any value as the API key. Use only Latin letters, digits, and hyphens. If the key contains other characters, for example, Cyrillic letters, the browser doesn't send the request and no response appears.
  3. Fill in the parameters or the request body.
  4. Click Send API Request. The response appears below the request panel.

Next steps​