Build on Your Own Wine Cellar: Cellarion's Public API

Your cellar, on your terms

A wine cellar is a surprisingly personal dataset. It's years of purchases, the bottle you're saving for a birthday, the shelf in the fridge where the Riesling lives, the notes you wrote after a good dinner. In Cellarion that data has always been yours. You can export it, take it with you, or run the whole thing on your own server. Today it also becomes something you can build on, properly.

Meet cellarion.app/developers: a public guide to the Cellarion API, with a getting-started section, a full reference, and copy-paste examples in curl and Python for every call.

Why now

People were already building on Cellarion: a dashboard on a kitchen tablet, a script that totals what's ready to drink this year, a home-automation card that lights up when a bottle hits its peak. We love that. But there was a catch. Without a guide, the only way to build was to watch what the app itself called and copy it. Those calls were never meant as a public promise, so any update could quietly break someone's integration.

So we drew a clear line. What's documented on /developers is stable, and we tell you before it changes. Everything else is internal, and you shouldn't need it.

What you can build

• The whole cellar in one call. GET /api/inventory returns every bottle you own, plus the cellars shared with you. Each comes with its wine, its drink window, your personal fields and exactly where it is: wine fridge, shelf 2, row 1, slot 3. It's built to be polled. When nothing has changed, the answer is a tiny "not modified", so checking every few minutes costs almost nothing.
• Live updates. An event stream tells your integration the moment something changes, so it can refresh instead of guessing.
• Taking a bottle out. One call marks a bottle as drunk, gifted or sold, straight from your dashboard or a button by the cellar door.
• Statistics and notifications. Totals, drink-window counts and the bottles that need drinking soon, ready for a dashboard.
• Climate sensors. Post temperature and humidity from a sensor in your cellar, and Cellarion keeps the history and warns you when it drifts.

Rather not write code? Two ready-made clients use exactly this API. pycellarion is a small Python library (pip install pycellarion). And the Cellarion integration for Home Assistant installs from HACS. Its newest version adds an inventory card: search your cellar, see which shelf a bottle is on, and take it out, all without leaving your home dashboard.

A promise, in writing

An API is only worth building on if it stays put. So here's ours:

• A documented endpoint, parameter or field keeps its name, type and meaning.
• New things may appear: new fields, new endpoints, new options. Well-behaved clients just ignore what they don't know.
• If something documented ever has to go, we announce it in the release notes and on /developers, the answers carry Deprecation and Sunset headers, and it keeps working for at least six months.

We're holding ourselves to the same rule from day one. A few undocumented routes that personal tokens could reach until now keep working until 1 May 2027, clearly marked. In the meantime, the inventory call covers what they were used for.

Safe by default

• Scoped tokens. You create a token under Settings → API tokens and give it only what it needs: read for a dashboard, consume if it should take bottles out. A token can only do what its scopes allow, and no token can change your password or delete your account.
• Revoke any time. One click in Settings, and the token stops working on the spot. Integrations can also revoke their own token when you remove them.
• Your data, not our AI. The API gives you your own cellar data. Nothing in it calls an AI model, so nothing you build on it ever spends anyone's AI budget.
• Nothing from third parties. The reference page loads everything from Cellarion itself. We even removed the one image the documentation viewer would have fetched from elsewhere.

Free, open, and yours

If you're new here: Cellarion is a wine cellar manager for people who love wine more than spreadsheets. Track every bottle and know when to drink it, thanks to drink windows reviewed by a sommelier. Lay out your racks and wine fridges shelf by shelf, then walk through them in 3D. Share a cellar with your household, and keep using it offline in a cellar with no signal. You can ask your AI assistant what to open tonight, and now you can build your own tools on top.

Every feature is free, for everyone. Cellarion is open source (AGPL-3.0), and you can run it on your own server if you like. The API guide there describes that server's own version. If Cellarion earns a place in your cellar, supporting the running costs is very welcome. Either way, every feature stays free for everyone.

For the technically curious

You can stop here and go pour a glass. What follows is the part where we nerd out.

The single source of truth is an OpenAPI 3.1 document, kept in the repository right next to the code. The guide on /developers is part of the same document, so the page, the downloadable spec and the version search engines see can't drift apart. Each server publishes it for its own version, which matters when a self-hosted server runs a few releases behind cellarion.app.

Documentation that isn't tested is just a wish. So the document is held to the real code in three ways:

• A contract test boots the real application against a real MongoDB with seeded data. It calls every documented endpoint and checks each answer against the document: status, headers and body, field by field. If a status is documented but never exercised, the test fails unless it says why.
• A parity test keeps the document and the token allowlist equal. Every documented call is reachable with exactly the scope it names, and the allowlist holds nothing undocumented. The few routes on their way out are kept on a separate list, with their end date.
• A cost trap wraps every function that could call an AI provider or pay for an embedding. The suite fails if any documented call touches one.

The reference is rendered with Redoc, vendored as a single versioned file instead of a hundred-package dependency. It's patched so it makes no third-party requests, and it runs under the app's strict content security policy without loosening it. And before release, the whole change went through a line-by-line audit, and its findings were fixed before it shipped.

Start at cellarion.app/developers, create a token with the fewest scopes you need, and build something lovely. If you need something that isn't there yet, tell us on GitHub.