Log an espresso or alternative shot/brew attempt. Uses the active context (bean/grinder/machine/program) unless overridden via bean_id/grinder_id/machine_id/program_id. ALWAYS pass bean_id explicitly when the user names a specific coffee, so the shot cannot land on the wrong bag. Backdate with pulled_at when the shot happened earlier. When the user reports taste (bitter, sour, harsh, hollow…), include matching sensory_tags: the diagnosis engine reads tags and metrics, not free-text flavor_notes. When the user tasted the shot and reports it as GOOD/clean (no defects), pass tasted=1 with no sensory_tags. Otherwise a tag-less, rating-less shot is filed taste-pending as if never tasted.
View input schema
{
"type": "object",
"properties": {
"dose_g": {
"type": "number"
},
"yield_g": {
"type": "number"
},
"time_s": {
"type": "number"
},
"bean_id": {
"type": [
"integer",
"null"
],
"description": "Override: log against this bean instead of the active one (null = active)"
},
"bag_id": {
"type": [
"integer",
"null"
],
"description": "Which bag of the coffee the shot came from; defaults to its current (open) bag. Bag numbers are on list_beans' bags[]"
},
"grinder_id": {
"type": [
"integer",
"null"
],
"description": "Override: grinder used, if not the active one (null = active)"
},
"machine_id": {
"type": [
"integer",
"null"
],
"description": "Override: machine used, if not the active one (null = active)"
},
"program_id": {
"type": [
"integer",
"null"
],
"description": "Override: machine program used, if not the active one (null = active)"
},
"pulled_at": {
"type": [
"string",
"null"
],
"description": "When the shot was actually pulled (ISO 8601 or \"YYYY-MM-DD HH:MM:SS\"), for backdated entries. Defaults to now (null = now). When backdating, pass the returned shot_id to diagnose_shot explicitly, because the default diagnosis target is the chronologically latest shot."
},
"finish_action": {
"type": "string",
"enum": [
"hard_stop",
"passive_drip"
]
},
"drink_intent": {
"type": "string",
"enum": [
"straight",
"milk"
]
},
"flavor_notes": {
"type": "string",
"maxLength": 4096
},
"sensory_tags": {
"type": "array",
"maxItems": 64,
"items": {
"type": "string",
"maxLength": 128
}
},
"observations": {
"type": "object",
"maxProperties": 64
},
"temp_taste": {
"type": "string",
"enum": [
"hot",
"warm",
"cold"
]
},
"rating": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"verdict": {
"type": "string"
},
"data_confidence": {
"type": "string",
"enum": [
"measured",
"recalled",
"estimated"
],
"description": "measured = weighed/timed live; recalled = from memory; estimated = a best guess (e.g. \"~25s\" after missing the timer)"
},
"temperature_c": {
"type": "number",
"description": "Brew temperature in Celsius"
},
"bloom_time_s": {
"type": "number",
"description": "Pre-wetting or bloom duration in seconds"
},
"first_drip_time_s": {
"type": "number",
"description": "Time to first drip in seconds"
},
"pressure_profile": {
"type": "string",
"maxLength": 16384,
"description": "Pressure profile description or values"
},
"beverage_g": {
"type": "number",
"description": "Yield mass excluding cup/vessel weight in grams"
},
"tds": {
"type": "number",
"description": "Total Dissolved Solids percentage (e.g. 9.1 or 1.35)"
},
"water_id": {
"type": "integer",
"description": "Optional references to waters formulation"
},
"vessel_name": {
"type": "string",
"description": "Cup/vessel name"
},
"vessel_weight_g": {
"type": "number",
"description": "Cup/vessel weight in grams"
},
"favourite": {
"type": "integer",
"enum": [
0,
1
],
"description": "1 if favourite, 0 otherwise"
},
"best_brew": {
"type": "integer",
"enum": [
0,
1
],
"description": "1 if marked as best brew, 0 otherwise"
},
"tasted": {
"type": "integer",
"enum": [
0,
1
],
"description": "1 = the shot was tasted at log time. The explicit way to record a CLEAN tasting: sensory tags all describe defects, so a good shot has none. Without this flag (or a rating) it would be filed taste-pending. Tags or a rating also mark a shot as tasted; 0 (default) = taste later."
},
"flow_profile": {
"type": "string",
"maxLength": 16384,
"description": "Opaque flow profile data (JSON/TEXT)"
},
"method_tools": {
"type": "string",
"maxLength": 4096,
"description": "JSON representation of method tools used (e.g., paper filters, screen)"
},
"machine_settings": {
"type": "object",
"maxProperties": 16,
"description": "Only when this one shot was pulled with a selector somewhere other than the machine's recorded settings: {key: position}. The shot is otherwise stamped with those automatically; a lasting change goes through update_machine."
}
},
"required": [
"dose_g",
"yield_g",
"time_s",
"finish_action"
]
}