JesebelGPT/docs/ADMIN.md

Admin

There are two admin surfaces:

1. Browser admin UI: /admin
2. Admin APIs: /api/logs and /api/stats/*

Admin is intended for local-network use.

Browser admin UI

1. Start the server (serves both chat UI and admin UI):

export FIRMWARE_API_KEY=...
./run.sh build
./run.sh server

2. Open the admin UI:

• http://<HOST>:<PORT>/admin (example: http://192.168.88.2:8787/admin)

3. Login:

• Enter ADMIN_TOKEN once.
• The server sets an admin_token httpOnly cookie.
• The UI then calls admin APIs without needing custom headers.

Logout clears the cookie.

Admin APIs

Admin APIs are read-only and require authentication.

Auth methods:

• Header: x-admin-token: $ADMIN_TOKEN
• Cookie session: admin_token (set by POST /api/admin/session)

List/search logs

GET /api/logs

Query params:

• q: full-text search across prompt+answer (SQLite FTS5)
• status: ok|error|aborted|started
• model: model id
• from, to: timestamps (ms epoch)
• limit (1..200), offset

Example:

curl -H "x-admin-token: $ADMIN_TOKEN" \
  "http://192.168.88.2:8787/api/logs?q=xin%20chao&limit=50"

Log detail

GET /api/logs/:request_id

Returns full record including:

• messages_json (full conversation context)
• assistant_text (final/partial answer)
• timestamps and status

Stats

• GET /api/stats/summary
• GET /api/stats/models
• GET /api/stats/timeseries?bucket=hour|day

Example:

curl -H "x-admin-token: $ADMIN_TOKEN" \
  "http://192.168.88.2:8787/api/stats/summary"

Data logging

SQLite file (default): ./data/chatlog.sqlite

Each /api/chat request inserts a log row at start and updates it when finished.

Stored fields include:

• timestamps: ts_request, ts_first_token, ts_done
• full context: messages_json
• quick fields: user_text, assistant_text
• model, status, optional usage tokens