GET /api/inventory — The whole inventory in one read
Token scope: read
Every bottle still in your cellars and in the cellars shared with you, each with its wine, its drink window, where it is (rack, shelf, row, slot) and its personal fields. Start here: one call replaces paging the bottle list, and an unchanged poll costs almost nothing.
Send the ETag of the copy you hold as If-None-Match. When nothing changed you get 304 with no body. The tag moves when any of the data changes, and at least every 30 minutes.
Limited to 60 requests per user per 10 minutes, 304s included. Poll every few minutes, or refetch when the event stream says something changed.
Add include=consumed to get the drunk, gifted and sold bottles too, in the same shape: their status says how they left and consumed holds when, the rating and the note. They come newest finished first, up to a limit (10,000 today); consumedTotal says how many there are and consumedTruncated whether some were left out. Without it the answer is unchanged. Each include has its own ETag.
If-None-Match(header): The `ETag` of the copy you hold, exactly as you received it.include(query): `consumed` = also the bottles that left the cellar (drunk, gifted, sold, other), newest finished first, up to a limit; see `consumedTruncated`. Any other value answers `400`.
{
"schema": 1,
"generatedAt": "2026-10-22T08:00:00.000Z",
"cellars": [
{
"id": "66f0a1b2c3d4e5f6a7b8c902",
"name": "Home",
"role": "owner"
},
{
"id": "66f0a1b2c3d4e5f6a7b8c903",
"name": "Summer house",
"role": "editor"
}
],
"racks": [
{
"id": "66f0a1b2c3d4e5f6a7b8c904",
"cellar": "66f0a1b2c3d4e5f6a7b8c902",
"name": "Wine fridge"
}
],
"wines": {
"66f0a1b2c3d4e5f6a7b8c905": {
"name": "Château Exemple",
"displayName": "Château Exemple",
"producer": "Château Exemple",
"type": "red",
"colour": null,
"country": "France",
"region": "Pauillac",
"appellation": "Pauillac",
"classification": null,
"labelSweetness": null,
"grapes": [
"Cabernet Sauvignon",
"Merlot"
],
"image": "/api/uploads/thumbs/processed/3f2b8c1e-4a5d-4e6f-9a7b-1c2d3e4f5a6b.webp.webp",
"profile": {
"body": "full",
"acidity": "medium",
"sweetness": "dry",
"tannin": "high",
"flavors": [
"blackcurrant",
"cedar"
],
"foodPairings": [
"lamb"
]
}
}
},
"bottles": [
{
"id": "66f0a1b2c3d4e5f6a7b8c906",
"wine": "66f0a1b2c3d4e5f6a7b8c905",
"pending": null,
"cellar": "66f0a1b2c3d4e5f6a7b8c902",
"status": "active",
"vintage": "2015",
"size": "750ml",
"price": 350,
"currency": "SEK",
"rating": 92,
"ratingScale": "100",
"notes": "For a birthday",
"purchaseDate": "2024-05-01",
"purchaseLocation": "Wine shop",
"addedAt": "2025-01-02T10:00:00.000Z",
"opened": false,
"consumed": null,
"maturity": "peak",
"window": {
"drinkFrom": 2022,
"peakFrom": 2025,
"peakUntil": 2032,
"drinkTo": 2038
},
"location": {
"rack": "66f0a1b2c3d4e5f6a7b8c904",
"rackName": "Wine fridge",
"position": 5,
"shelf": 2,
"row": 1,
"col": 2
},
"place": null,
"image": "/api/uploads/thumbs/processed/3f2b8c1e-4a5d-4e6f-9a7b-1c2d3e4f5a6b.webp.webp",
"personal": [
{
"key": "Closure",
"type": "text",
"unit": null,
"value": "cork",
"level": "bottle",
"by": "alice"
}
]
}
]
}