Bentori Documentation
API reference, CLI guide, card schemas, and download links.
Quick Start
- 1. Register — Visit /register and submit your email. You will receive a namespace URL and API key.
- 2. Sign in — Paste your API key in the Settings (gear icon) on your dashboard to set the session cookie. Alternatively, call
POST /api/:namespace/session. - 3. Create cards — Use the "+" menu in the dashboard header, or the CLI / API.
- 4. Share — Click "Share" to create a public read-only link for any dashboard.
REST API Reference
All mutations require an API key via X-API-Key header or bentori_api_key session cookie.
Dashboards
| Method | Endpoint | Body / Notes |
|---|---|---|
| GET | /api/:ns/dashboards | List all dashboards |
| POST | /api/:ns/dashboards | {"name":"...","bg_color":"midnight","refresh_interval":0} |
| GET | /api/:ns/dashboards/:id | Get dashboard |
| PUT | /api/:ns/dashboards/:id | {"name","bg_color","refresh_interval"} (any subset) |
| DEL | /api/:ns/dashboards/:id | Delete dashboard (cards are detached, not deleted) |
| POST | /api/:ns/dashboards/:id/duplicate | {"name":"..."} (optional) |
| POST | /api/:ns/dashboards/:id/public | Create public share token |
| DEL | /api/:ns/dashboards/:id/public | Revoke public token |
Cards
| Method | Endpoint | Body / Notes |
|---|---|---|
| GET | /api/:ns/cards | List all cards in namespace |
| POST | /api/:ns/cards | {"type":"metric","title":"...","data_json":{},"refresh_interval":60,"dashboard_id":1,"size":"1x1"} |
| GET | /api/:ns/cards/:id | Get card |
| PUT | /api/:ns/cards/:id | {"title","data_json","refresh_interval"} (type is immutable) |
| DEL | /api/:ns/cards/:id | Delete card permanently |
| GET | /api/:ns/card-types | List available types + default data_json |
Dashboard-Cards (junction)
| Method | Endpoint | Body / Notes |
|---|---|---|
| GET | /api/:ns/dashboards/:id/cards | List attached cards |
| POST | /api/:ns/dashboards/:id/cards/:card_id | {"position":0,"size":"1x1"} — attach |
| PUT | /api/:ns/dashboards/:id/cards/:card_id | {"position","size"} — move/resize |
| DEL | /api/:ns/dashboards/:id/cards/:card_id | Detach (card still exists) |
| PUT | /api/:ns/dashboards/:id/reorder | {"cards":[{"card_id","position","size"}]} — bulk |
Account & Session
| Method | Endpoint | Notes |
|---|---|---|
| POST | /api/:ns/session | {"api_key":"..."} — sets 1-year HttpOnly cookie |
| GET | /api/:ns/account | Account metadata (requires auth) |
| POST | /api/:ns/account/regenerate-api-key | New key + updates cookie |
| PUT | /api/:ns/account/role | Admin only: {"namespace":"...","role":"admin|free|membership|betatester"} |
CLI Tool (bentori-cli)
Global flags: -ns, -key, -base-url. All global flags must come before the command.
Dashboards
# Create a dashboard
bentori-cli dashboard create -name "Production" -bg-color emerald -refresh 0
# Update (any subset of fields)
bentori-cli dashboard update -id 1 -name "Prod" -bg-color emerald -refresh 300
# Duplicate
bentori-cli dashboard duplicate -id 1 -name "Production Copy"
# List / Delete
bentori-cli dashboard list
bentori-cli dashboard delete -id 2Cards
# Create a standalone card (default refresh: 60s)
bentori-cli card create -type metric -title "CPU" -data '{"value":42}' -refresh 30
# Update title, data, and/or refresh
bentori-cli card update -id 5 -title "Updated" -data '{"value":55}' -refresh 120
# Push data (auto-fetches title)
bentori-cli card push -id 5 -data '{"value":60}' -refresh 120
# Delete / List
bentori-cli card delete -id 5
bentori-cli card listAttach & Move
# Attach existing card to dashboard
bentori-cli card attach -dashboard-id 1 -card-id 5 -position 0 -size 2x2
# Detach / Move
bentori-cli card detach -dashboard-id 1 -card-id 5
bentori-cli card move -dashboard-id 1 -card-id 5 -position 1 -size 1x2
# Create + attach in one step
bentori-cli card add -type metric -title "CPU" -data '{"value":42}' \
-dashboard-id 1 -position 0 -size 2x2 -refresh 30Populate
# Create a dashboard with one card of every type
bentori-cli populate
bentori-cli populate -name "Demo Dashboard"Card Layouts
Bentori uses 16 general layout templates. The type field selects the layout; data_json provides the content. Card type is immutable after creation.
| Type | Description | Required fields |
|---|---|---|
metric | Big number + badge + sparkline | label, value |
line-chart | Chart.js line chart (1-2 datasets) | labels, datasets |
bar-list | Horizontal bars with labels | items[]: {name, pct, color} |
progress | Progress bar + fraction | label |
status | Colored status indicators | label, items[]: {name, value, color} |
event-list | Event rows with color dot + time | label, items[]: {color, text, time} |
calendar | Date-block event list | events[]: {month_short, day, title, time} |
quote | Quote + author | text, author |
weather | Gradient bg + temp/condition | temp, condition, high, low |
map | Interactive map with markers | lat, lng, markers[]: {lat, lng, label, color} |
stream | HLS live video stream | url, poster, muted, autoplay, controls |
embed | YouTube, Vimeo, video file, or generic iframe embed | url, autoplay, muted, controls |
clock | Clock with timezone + optional seconds | timezone, show_seconds, label |
admin-metric | KPI big number (inline CSS) | value, label |
admin-chart | KPI sparkline bars (inline CSS) | items, label |
admin-bar-list | KPI horizontal bars (inline CSS) | items[]: {name, value}, total |
Call GET /api/:namespace/card-types to fetch default data_json for every type. Use it to pre-fill the Data JSON field when creating cards.
Download Bentori
Pre-built server binaries.
FAQ & Troubleshooting
You are using an old content-specific type name (e.g. cpu, revenue). Bentori now uses 16 general layouts. Restart the server to trigger the automatic card migration, or manually update the card type via the API.
Open the dashboard, click the "Share" button in the header. A read-only token is created and the URL is copied to your clipboard. Anyone with the link can view the dashboard without signing in.
The API key is your write token. All mutations (create, update, delete) require it, either as an X-API-Key header or via the bentori_api_key HttpOnly session cookie. The cookie is set automatically when you register.
Cards and dashboards have a refresh_interval field (seconds). When set to a value > 0, a <meta http-equiv="refresh"> tag is injected into the HTML. Cards default to 60s; dashboards default to 0 (disabled). Minimum is 15s.
Yes. Set BENTORI_BASE_URL (or -base-url) to the public-facing URL. All internal paths use relative URLs so they work behind proxies. Use any reverse proxy (nginx, Caddy, Traefik) for TLS termination.