The client targets the Dataplane API v3 REST surface.
Endpoints
Operation | Method & path | Notes |
|---|---|---|
Read configuration |
| Current version included in the response |
Read version |
| Used for conflict detection |
Write configuration |
| Body is the config JSON. Version-scoped — rejects if the live config moved. |
Open transaction |
| Returns a transaction id |
Per-resource op |
| Transaction-scoped, not version-scoped. See the note below. |
Commit transaction |
| Bumps the config version by exactly one |
Reload |
| Runs |
Where $BASE_URL is the instance’s baseUrl — an absolute URL in direct or Tauri mode, or the relative path /dataplane when using the Vite proxy.
Transaction scoping is not interchangeable with version scoping. Opening a transaction advances the API’s tracked version immediately, so a per-resource call carrying a version captured before the transaction opened is stale on arrival — 409 on every operation, aborting the whole transaction. Use
?transaction_id=.
Authentication
The bearer token is sent as Authorization: Bearer $PUBLIC_DATAPLANE_API_TOKEN when set. HTTP Basic is supported for instances configured with a username and password.
In the desktop build the token is resolved from the OS keychain inside Rust per request. PUBLIC_DATAPLANE_API_TOKEN is not required for desktop requests.
PUT replaces
Dataplane v3 PUT replaces the target resource wholesale. Fields absent from the request body are deleted. Any client that sends a delta rather than the full representation will silently destroy configuration it did not intend to touch. This is the single most dangerous behaviour in the API, and it is why the write path sends complete resource bodies.
Environment variables
Variable | Scope | Purpose |
|---|---|---|
| Build-time (bundled) | Default Dataplane URL for new browser-mode instances |
| Build-time (bundled) | Browser mode only. Bundled into the client — do not set this to a production token in a browser build. |
| Server-side only | Overrides the Vite dev proxy upstream. Never bundled into the client. |
Error classification
All failures surface as HaproxyApiError, which carries a kind so the UI can offer the right remediation rather than a generic failure. See Architecture Overview for the full table.