Authentication and scope
export BE=https://hub.[yourdomain]; export K="Authorization: Bearer bek_…"
curl -H "$K" $BE/me # who am I, role, companies
curl -H "$K" "$BE/agents?tenant=t_…" # every list accepts ?tenant=
Mutating actions that reach a machine need ?approved=yes on the request; that is the API form of the approval click, and the caller's name is recorded.
Machines
| method and path | what |
|---|
| GET /agents | every visible machine with its latest heartbeat |
| GET /agents/sparks | 24 h disk and CPU points per machine, disk growth per day and days to full |
| GET /agents/:id/trend?range=24h|7d|30d | one machine's series (raw for 24 h, hourly beyond) |
| GET /agents/:id/samples|events|checks/history | history from the hub's tables |
| POST /agents/:id/call {tool, args} | call a tool; read tools run, mutating tools need ?approved=yes |
| GET and PUT /agents/:id/checks; POST /agents/:id/checks/run | the check document (PUT needs approval); evaluate now |
| PUT /agents/:id/profile {display_name, notes}; PUT /agents/:id/tags; PUT /agents/:id/ai | name and notes, tags, BE AI scope |
| PUT /agents/:id/target {version}; PUT /agents/:id/tenant {tenant_id} | roll-out target; move to another company (superadmin) |
| DELETE /agents/:id | forget an offline machine (superadmin) |
BE AI
| method and path | what |
|---|
| POST /agents/:id/ask {question} or {thread_id, question} or {proposal_id, thread: true, question} | start a run; add ?wait=yes to block for the result |
| GET /runs, GET /runs/:id | runs with conclusions; one run with its transcript |
| GET /threads, GET /threads/:id | conversations |
| GET /proposals; POST /proposals/:id/approve|reject|retry | the approvals queue and decisions |
| GET /schedule; POST /tenants/:id/schedule/run | the nightly pass evaluation; run it now |
Alerts
| method and path | what |
|---|
| GET /alerts?status=active|open|acked|resolved|all | alerts |
| POST /alerts/:id/ack|resolve | decisions |
| GET, POST, PUT, DELETE /alert-rules; POST /alert-rules/:id/test | notification rules per company |
| GET /notifications | deliveries |
Companies and users
| method and path | what |
|---|
| GET, POST /tenants; PUT /tenants/:id {name, notes, disabled, settings} | companies (create, rename, disable and settings are superadmin) |
| POST /tenants/:id/install-key; POST /tenants/:id/token | rotate the install link; rotate the enrollment token (superadmin) |
| GET, POST /operators; PUT /operators/:id; POST /operators/:id/password|key | users, disable, temporary password, new key |
| GET /usage?month=YYYY-MM | machines, runs, tokens and estimated cost per company |
Releases and the hub
| method and path | what |
|---|
| GET /updates; POST /updates/rollout {version, agents|tenant|tag|all} | versions against targets; roll out |
| GET /dl/; GET /dl/:version/:file; PUT /dl/:version/:file; PUT /dl/latest | releases index and files; publish (admin) |
| GET /events; GET /audit; GET /trend?range=; GET /stats | hub-wide history, audit trail, fleet series, counts (admin) |
| POST /login; POST /logout; POST /me/password | sessions |