🔗 API - Endpoints `/hix-*`¶

Complete reference of the HIX admin panel endpoints. For conceptual details (session, signed cookie, initial configuration) see sistema/hix-admin.

Summary¶

Endpoint	Method	Auth	Function
`/hix-ping`	`GET`	-	Public health check
`/hix-slow`	`GET`	-	Slow endpoint (3s) - latency debug
`/hix-status`	`GET`	✅	Metrics in JSON
`/hix-monitor`	`GET`	✅	Live HTML dashboard
`/hix-index`	`GET`	✅	HTML listing of registered routes
`/hix-trace`	`GET POST`	✅	Trace status/toggle by module
`/hix-cache-clear`	`GET`	✅	Clears compiled view cache
`/hix-stop`	`GET`	✅	Graceful shutdown of HIX
`/hix-bench-start`	`GET`	✅	Reset metrics (bench)
`/hix-bench-stop`	`GET`	✅	JSON dump of bench
`/hix-routes/add`	`POST`	✅	Add dynamic route
`/hix-routes/delete`	`POST`	✅	Delete route by name
`/hix-routes/reload`	`GET`	✅	Reload `routes/*.json`
`/hix-routes/list`	`GET`	✅	HTML listing - app routes only
`/hix-routes/listall`	`GET`	✅	HTML listing - all routes
`/hix-login`	`GET POST`	-	Admin login
`/hix-logout`	`GET`	-	Close admin session
`/hix-setup`	`GET POST`	-	Initial credential configuration

Auth = requires HIX_AdminCheck(oReq) before executing the handler. In env=dev auth is automatically disabled - all endpoints respond without cookie. In env=prod a valid hix_admin cookie is required.

Public endpoints¶

`GET /hix-ping`¶

Lightweight health check - designed for load balancers and external monitoring.

Response 200 OK (JSON):

{ "status": "ok", "server": "HIX/2.1" }

`GET /hix-slow`¶

Same as ping but with hb_idleSleep(3). Useful for testing client timeouts, load balancers, or front proxy.

Response 200 OK after 3 seconds:

{ "status": "ok", "time": "12:34:56" }

Metrics and monitor¶

`GET /hix-status`¶

Dumps the server state (active connections, total requests, errors, pool usage, saturation alert, etc.) as JSON. Generated by HIX_MetricsJson().

Response 200 OK (excerpt):

{
  "uptime_s": 12345,
  "requests": { "total": 9876, "errors": 12 },
  "pool_http": { "workers": 64, "queue": 5, "alert": false },
  "pool_ws":   { "workers": 100, "active": 42 },
  "pool_rest": { "sse": 3, "longpoll": 1 }
}

See sistema/metricas for the complete schema details.

`GET /hix-monitor`¶

Serves html/monitor.html - HTML dashboard that consumes /hix-status every [monitor] interval_s seconds and renders graphs. Useful for visual inspection.

`GET /hix-index`¶

Self-contained HTML page with the listing of all registered routes (name, methods, pattern, "Open" button). Useful for discovering what the server has without accessing the code.

Each row shows:

Name - logical name (hix.status, users.list, ...)
Methods - colored badges by method (GET, POST, ...)
Pattern - URL pattern (/users/:id)
Action - "Open" button if the route accepts GET

Traces¶

`GET /hix-trace`¶

Without parameters: returns the current state of all traces by module in JSON.

{
  "app": true,
  "server": true,
  "worker_http": false,
  "worker_ws": false,
  ...
}

With ?mod=<module>&on=<0|1>: enables or disables the trace for that module and returns the updated state.

Query	Effect
`?mod=worker_http&on=1`	Enable trace for `worker_http` module
`?mod=worker_http&on=0`	Disable trace for module
`?mod=all&on=1`	Enable all modules
`?mod=all&on=0`	Disable all

Available modules: app, server, worker_http, worker_ws, worker_otros, pool, pool_detector, metrics, config, socket, monitor, response, logger, error.

WARN/ERROR/FATAL are always logged, regardless of trace setting.

Cache¶

`GET /hix-cache-clear`¶

Recursively deletes the compiled view cache in .cached/views/ (.hrb files and __*.prg). Useful after a deploy where .view.html files change but cache_disk = true keeps old HRBs.

Response 200 OK:

{ "status": "ok", "deleted": 42, "path": "C:/hix.pro/.cached/views" }

Does not affect RAM cache (cache_ram); that invalidates itself by mtime.

Bench¶

`GET /hix-bench-start`¶

Resets all counters of the metrics module (HIX_MetricsReset()) and leaves the server ready for a new measurement.

Response 200 OK:

{ "bench": "start" }

`GET /hix-bench-stop`¶

Closes the bench and returns a complete dump of HIX_MetricsJson().

Response 200 OK:

{
  "bench": "stop",
  "metrics": { "uptime_s": 60, "requests": { "total": 50000, ... } }
}

Graceful shutdown¶

`GET /hix-stop`¶

Marks the server to stop (HIX_ServerRequestStop()), closes the keep-alive of the current request, and lets workers finish their running tasks before exiting.

Response 200 OK:

{ "status": "stopping" }

Equivalent to a controlled Ctrl+C via HTTP. The main loop exits when each pool's queue is empty.

Dynamic route management API¶

Allows adding, deleting, and reloading routes hot without restarting HIX. Routes created by this API are volatile (lost on restart) unless you persist them in routes/*.json first.

Reserved: names with prefix hix.* are system-owned and cannot be registered via this API (responds 400).

`POST /hix-routes/add`¶

Adds a new route. Body JSON:

{
  "name":       "users.list",
  "url":        "/users",
  "action":     "/controllers/users/list.prg",
  "method":     "GET",
  "middleware": "HIX_MwJwt",
  "scope":      ""
}

Field	Type	Required	Notes
`name`	string	✅	Cannot start with `hix.`
`url`	string	✅	URL pattern (supports `:var`). Alias: `pattern`
`action`	string	✅	Path to PRG/HRB/HTML to execute
`method`	string	❌	Default `*` (all). Comma-separated: `GET,POST`
`middleware`	string	❌	MW(s) separated by comma
`scope`	string	❌	Free metadata (e.g., `admin`)

Response 200 OK if added:

{ "ok": true, "name": "users.list" }

Response 409 Conflict if the route already exists (no overwrite):

{ "ok": false, "error": "duplicate or invalid route", "name": "users.list" }

Response 400 Bad Request if the JSON is invalid or the name is reserved:

{ "ok": false, "error": "invalid JSON body" }

`POST /hix-routes/delete`¶

Deletes a route by name. Body JSON:

{ "name": "users.list" }

Response 200 OK:

{ "ok": true, "name": "users.list" }

Response 400 Bad Request if name is missing:

{ "ok": false, "error": "name required" }

`GET /hix-routes/reload`¶

Deletes all application routes (those that aren't hix.*) and reloads those defined in www/routes/*.json with HIX_LoadRoutes().

Response 200 OK:

{ "ok": true, "total_deleted": 12, "total_loaded": 14 }

Useful in deploy workflows: you copy the new routes/users.json to the server and trigger /hix-routes/reload from your pipeline.

`GET /hix-routes/list`¶

HTML page with application routes (excludes system routes hix.*). Columns: name, methods, pattern, middleware, action.

`GET /hix-routes/listall`¶

Same as /hix-routes/list but includes all routes (system + application).

Authentication¶

`GET /hix-login`¶

HTML page with the login form (username + password). Self-contained - does not use CDN or external assets.

Accepts ?next=<url> to redirect after a successful login (default: /hix-status).

`POST /hix-login`¶

Processes the login. Body form-urlencoded:

Field	Type	Notes
`user`	string	Admin username
`password`	string	Plain password (MD5-hashed on the server)
`next`	string	URL to redirect to after login

If credentials are valid:

Emits hix_admin = <ts>:<sign> cookie signed with oCfg:cAdminSecret, valid for session.lifetime minutes.
Redirects to next (or /hix-status if empty).

If they fail: responds 401 Unauthorized with the form and an error message.

`GET /hix-logout`¶

Deletes the hix_admin cookie (expires it immediately) and redirects to /hix-login.

`GET /hix-setup`¶

HTML page with the form for initial credential creation. Only shown if oCfg:cAdminUser or oCfg:cAdminPassword are empty.

If credentials already exist: redirects to /hix-login.

`POST /hix-setup`¶

Creates credentials for the first time. Body form-urlencoded:

Field	Type	Validation
`user`	string	Not empty
`password`	string	Minimum length 6
`password2`	string	Must match `password`

If they validate:

Saves oCfg:cAdminUser = user
Saves oCfg:cAdminPassword = MD5(password)
Generates and saves oCfg:cAdminSecret = MD5(timestamp + user + password)
Persists everything in hix.json with oCfg:Generate()
Redirects to /hix-login

If there are errors: responds 422 Unprocessable Entity with the form and the corresponding error message.

Admin session cookie `hix_admin`¶

Cookie value format:

<unix_timestamp>:<md5_sign>

Where:

unix_timestamp = moment in seconds when the cookie was issued
md5_sign = MD5(secret + "|" + unix_timestamp)

Verification on each request:

Tokenize by :
Recalculate MD5(secret + "|" + ts) and compare against sign
If nMinutes > 0: check that now - ts <= session.lifetime * 60

If any step fails → redirects to /hix-login?next=<current_path>.

The signature uses cAdminSecret which must be kept in hix.json. If you rotate it, all active admin sessions become invalid.

HTTP codes¶

Code	When
`200 OK`	Successful request
`302 Found`	Redirect to `/hix-login`, `/hix-setup`, or `next=`
`400 Bad Request`	Invalid JSON or reserved route name (`hix.*`)
`401 Unauthorized`	Login failed
`409 Conflict`	`/hix-routes/add` with already-existing name
`422 Unprocessable`	`/hix-setup` with validation failure (short pass, etc.)

Common recipes¶

Reload routes after deploy¶

# 1. Upload the new JSON
scp www/routes/users.json prod:/srv/hix/www/routes/

# 2. Reload
curl --cookie-jar /tmp/c.txt --cookie /tmp/c.txt \
     -d 'user=admin&password=secret' \
     https://myapp.com/hix-login

curl --cookie /tmp/c.txt https://myapp.com/hix-routes/reload

Enable WebSocket trace on-the-fly¶

curl --cookie /tmp/c.txt \
     "https://myapp.com/hix-trace?mod=worker_ws&on=1"

Stop HIX from a deploy script¶

curl --cookie /tmp/c.txt https://myapp.com/hix-stop
# The server responds {"status":"stopping"} and exits after draining queues.

Public health check (no auth)¶

curl https://myapp.com/hix-ping
# {"status":"ok","server":"HIX/2.1"}

Common errors¶

302 redirecting to /hix-setup and never reaching the panel - hix.json has admin.user and/or password empty. Visit /hix-setup from your browser to create them.
302 redirecting to /hix-login with correct cookie - the cookie expired (session.lifetime elapsed) or cAdminSecret changed.
409 duplicate in /hix-routes/add - the route already exists. Delete it first with /hix-routes/delete or change the name.
400 reserved name - you're trying to register hix.something. Rename it.
/hix-status returns HTML instead of JSON - admin.enabled = false or you're not authenticated in env = "prod" (it redirects you to the HTML login).

Best practices¶

In production, protect /hix-* also at the proxy level (apache/nginx) with an IP allowlist to minimize attack surface.
Don't register your routes with prefix hix.* - it's reserved and HIX will reject them.
Routes created by /hix-routes/add are volatile: if you want them to survive restart, persist them in www/routes/*.json.
cAdminSecret is a secret: don't commit it to git. To rotate it, regenerate with /hix-setup (after deleting user/password from hix.json).
Use /hix-cache-clear after any deploy that touches .view.html if you have cache_disk = true.
Enable traces (/hix-trace?mod=X&on=1) only as long as you need to diagnose
the logging cost can be high in hot modules (worker_http, socket).

hix.json configuration
Admin Panel (overview)
Metrics
Logger
HTTP errors
Traces

🔗 API - Endpoints /hix-*¶

Summary¶

Public endpoints¶

GET /hix-ping¶

GET /hix-slow¶

Metrics and monitor¶

GET /hix-status¶

GET /hix-monitor¶

GET /hix-index¶

Traces¶

GET /hix-trace¶

Cache¶

GET /hix-cache-clear¶

Bench¶

GET /hix-bench-start¶

GET /hix-bench-stop¶

Graceful shutdown¶

GET /hix-stop¶

Dynamic route management API¶

POST /hix-routes/add¶

POST /hix-routes/delete¶

GET /hix-routes/reload¶

GET /hix-routes/list¶

GET /hix-routes/listall¶

Authentication¶

GET /hix-login¶

POST /hix-login¶

GET /hix-logout¶

GET /hix-setup¶

POST /hix-setup¶

Admin session cookie hix_admin¶

HTTP codes¶

Common recipes¶

Reload routes after deploy¶

Enable WebSocket trace on-the-fly¶

Stop HIX from a deploy script¶

Public health check (no auth)¶

Common errors¶

Best practices¶

Related resources¶

🔗 API - Endpoints `/hix-*`¶

`GET /hix-ping`¶

`GET /hix-slow`¶

`GET /hix-status`¶

`GET /hix-monitor`¶

`GET /hix-index`¶

`GET /hix-trace`¶

`GET /hix-cache-clear`¶

`GET /hix-bench-start`¶

`GET /hix-bench-stop`¶

`GET /hix-stop`¶

`POST /hix-routes/add`¶

`POST /hix-routes/delete`¶

`GET /hix-routes/reload`¶

`GET /hix-routes/list`¶

`GET /hix-routes/listall`¶

`GET /hix-login`¶

`POST /hix-login`¶

`GET /hix-logout`¶

`GET /hix-setup`¶

`POST /hix-setup`¶

Admin session cookie `hix_admin`¶