API reference

Everything the web UI does goes through this API, so anything the UI can do, you can script. Authentication is the session cookie — sign in with POST /api/login and keep the cookie:

curl -c jar -X POST http://localhost:8080/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"andre","password":"..."}'

curl -b jar http://localhost:8080/api/board

Requests and responses are JSON. Unknown fields in a request body are an error rather than being ignored, so a misspelled field tells you immediately instead of silently doing nothing.

Errors are {"error": "..."} with a meaningful status.

0.2.0 removed /api/bookmarks entirely. There is no alias, deliberately: a bookmark had exactly one group_id and a board item has zero or many, so an alias would have to answer with a field that no longer has an honest value. A 0.1.0 script gets a 404 and finds out immediately. See Apps, resources & groups for the new model.

Auth in the tables below

• public — no session needed
• session — any signed-in account
• owner — you own the group / resource / board item in question
• app-edit — the app's creator, one of its responsible users, or an admin
• app-owner — the app's creator, or an admin
• admin — the admin role

404 vs 403. Anything private (a group, a resource, a board item) answers 404 when it is not yours, so no id can be probed by watching which ones answer differently. The shared catalog is the only place that produces a 403: you can already see every app, so a refusal to edit one has nothing left to hide.

Setup and session

The catalog

POST /api/apps body:

{
  "url": "grafana.lan:3000",
  "title": "Grafana",           // optional — omit and the server reads the page
  "description": "…",
  "plate": "plain",             // plain | light | dark
  "link_target": "reuse",       // reuse | new | self
  "icon_data_url": "data:…",    // optional; revalidated server-side regardless
  "group_ids": ["…"],           // your own groups only
  "add_to_board": true,         // default true
  "allow_duplicate": false      // see below
}

It answers 201 {"app": {...}, "item": {...}} — the catalog entry, and the board row it created (null when add_to_board is false).

The duplicate check

Adding an app on a host the catalog already knows answers 409:

{
  "error":  "an app on grafana.lan already exists — resend with allow_duplicate: true to add another",
  "reason": "duplicate_host",
  "host":   "grafana.lan",
  "existing": [ { …app… } ]
}

Resend with "allow_duplicate": true to create it anyway. This is the same kind of guard as {"confirm": true} on the destructive endpoints: a stray script cannot make a duplicate by accident, and a person who means it says so once.

GET /api/apps/lookup answers the same question without writing anything, and takes the raw pasted URL rather than a host — so a client never reimplements the normalisation rules and cannot drift from them.

Changing an app's url when board_count > 1 needs {"confirm": true} too.

App fields

can_edit and on_board are computed per request and per caller; the client never infers them. board_item_id is set when on_board is true.

window_target is the exact string to hand window.open and <a target>. It is server-computed so that every surface showing one app agrees on it — see Security.

icon_url is present only when the app has an icon; its absence is the signal to draw a letter tile. It carries ?v=<content hash>, so the URL changes exactly when the bytes do and can be cached indefinitely.

Resources

Private deep links. Owner-only throughout, so every failure here is a 404.

Your board

DELETE /api/board/{id} on a resource item answers 400 pointing at DELETE /api/resources/{id}. A resource is reachable only through its board item, so "remove from board" would silently mean "destroy forever".

Groups

Private per-user tags. Every route here is owner-only, and "not yours" is 404.

Ordering

There are two independent orderings: your board's, and one per group. A drag inside a group does not reshuffle your board.

Both board and group reorder endpoints accept a subset. The listed ids are reassigned to the positions they already occupied, sorted ascending; unlisted ids never move. That is what makes the kind-filtered views and the search filter draggable at all. An id that is not in that scope, or a duplicate, is a 400.

PUT /api/groups/order is the exception and still demands exactly your own groups: the sidebar always renders every one, so a partial list means the client is confused rather than filtered.

Metadata

Returns {url, final_url, title, icon_url, icon_data_url, unreachable} and persists nothing. A failed lookup is still 200, with unreachable set to private_address_blocked, timeout or unreachable — the add form has to stay usable when a host is simply switched off.

Kept separate from /api/apps/lookup on purpose: this one reaches out across the network and is rate-limited, and the duplicate hint has to keep working when the far end is down or the limiter has already fired.

Users

/api/users/search is not admin-only because a member has to be able to pick who is responsible for an app they added. It excludes the caller and disabled accounts, and never lists everybody.

Activity

Actions worth filtering on: app.create, app.create_duplicate (somebody deliberately made a second app on a known host), app.update (records url: old -> new when the address changes), app.responsible_add, board.add, board.remove.

Databases upgraded from 0.1.0 still hold bookmark.* and group.share rows. Nothing rewrites history.

Health

Example: add an app from a script

curl -s -b jar -X POST localhost:8080/api/apps \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://grafana.lan:3000"}'

The title and icon are filled in server-side, and it lands on your board. If the catalog already has that host you get a 409 — add "allow_duplicate": true if you meant it, or take the existing[0].id and put that on your board instead:

curl -s -b jar -X POST localhost:8080/api/board \
  -H 'Content-Type: application/json' -d '{"app_id":"…"}'