The Openbeehive API

Openbeehive is API-first and open. There is no hidden backend: everything the app does — creating apiaries, recording inspections, syncing devices, reading statistics — goes through a single, public Connect-RPC API. The same contract that powers the app is available to you.

That openness is deliberate. Your records are yours, so you should be able to read them, script them, feed them from your own sensors, and move them elsewhere without asking anyone's permission.

One contract, two protocols

The API is defined once as a Protocol Buffers contract and served with Connect-RPC. That means every endpoint is reachable two ways, from the same URL:

Style	Best for	Page
HTTP + JSON (REST-like)	curl, scripts, webhooks, microcontrollers, quick integrations	REST / HTTP + JSON
gRPC / gRPC-Web / Connect	typed clients, streaming, high-volume sync	gRPC

You don't choose a protocol on the server — you choose it per request, by the headers you send. Pick whichever is easier for your tool.

Base URL

The API is served by the same process that serves the app:

• Hosted service: https://app.openbeehive.org
• Self-hosted: your own origin, e.g. https://bees.example.com (see Self-hosting)

Every method lives at a predictable path:

POST <base-url>/openbeehive.v1.<Service>/<Method>

For example: https://app.openbeehive.org/openbeehive.v1.ApiaryService/ListApiaries.

Services

The contract is grouped into services. Each maps to a part of the domain you already know from the app:

Service	What it covers
ApiaryService	Create, read, update, delete and list apiaries
HiveService	Hives, including relocating a hive between apiaries
QueenService	Queens and their reign history
InspectionService	Inspections / visits (incl. temperature & humidity), photo upload URLs
TreatmentService	Treatments / the Bestandsbuch (product, batch, dose, withdrawal period)
TaskService	Tasks and reminders
EventService	The append-only event / history feed
StatsService	Dashboard totals and honey statistics
SyncService	Pull, Push and a streaming Subscribe — the offline-first sync engine

:::note Implementation status (v0.1.0) ApiaryService and SyncService are fully wired server-side today. The other services are defined in the contract and follow the same shape; they are being filled in. Check the contract for the current source of truth, and the release notes for what's live. :::

Authentication

• Self-hosted, single user: when no login is configured, the API is open to the instance (you are the only user). This is the simplest setup for home servers and scripts. See Authentication.
• With login enabled / the hosted service: requests carry a session established via OIDC or a passkey. Send it as a bearer token: Authorization: Bearer <token>. Programmatic API tokens for unattended clients (scripts, sensors) are on the roadmap — until then, self-hosting in single-user mode is the friction-free path for automation.

How the app itself uses it

The app is offline-first: it writes to a local database first and the sync engine reconciles with the server through SyncService.Push / Pull. The CRUD services (ApiaryService, InspectionService, …) are the server-authoritative entry points used for direct integrations, export and automation. Both views sit on the same data — see Offline & sync and the developer architecture.

What you can build

• Pull your data into a spreadsheet, notebook or BI dashboard.
• Script bulk edits or migrations from another beekeeping tool.
• Feed readings from automated trackers — hive scales, temperature and humidity sensors — straight into inspections. See Automated trackers.
• Build your own client, bot or mobile widget against a stable, typed contract.

Ready for the details? Start with REST / HTTP + JSON.