API Quick Reference

API Quick Reference

This page provides a practical reference for the main Nutify APIs. It is written for operators, integrators, and contributors who need fast endpoint orientation.

1) How to Discover the Full Live API List

Nutify provides a dynamic API explorer page:

• /api

It is generated from runtime route introspection. Use it as the canonical live catalog for your running instance.

Additional runtime catalog endpoint used by the frontend explorer:

• GET /api/frontend/catalog

Important:

• /api/frontend/catalog requires an authenticated session.
• /api is the UI entry for the explorer, but catalog data is served through the authenticated endpoint above.

2) Access Classification Model

API explorer classifies routes by access type:

• public
• session
• admin
• permission
• token

Use this classification before integrating automations.

Current hardening posture:

• public: minimal bootstrap endpoints only.
• token: callback endpoints that require X-Nutify-Token.
• session: authenticated user required.
• admin: authenticated admin required for sensitive/mutating APIs.

3) Bootstrap and Session Context

Frontend bootstrap

• GET /api/frontend/bootstrap

Used by frontend to resolve:

• auth status
• setup/full mode
• target context
• profile context
• tab visibility

Token callback endpoint

• POST /api/nut_event

Requires:

• X-Nutify-Token header

4) Multi-NUT Core APIs

State and overview

• GET /api/multi-nut/state
• GET /api/multi-nut/overview

Target inventory

• GET /api/multi-nut/targets
• POST /api/multi-nut/targets
• PUT /api/multi-nut/targets/<id>
• DELETE /api/multi-nut/targets/<id>
• POST /api/multi-nut/targets/<id>/toggle
• POST /api/multi-nut/targets/<id>/primary
• POST /api/multi-nut/targets/<id>/poll-now

Active target session control

• GET /api/multi-nut/active-target
• POST /api/multi-nut/active-target
• DELETE /api/multi-nut/active-target

Target data and history

• GET /api/multi-nut/targets/<id>/dashboard
• GET /api/multi-nut/targets/<id>/history

Reporting

• GET /api/multi-nut/report

Access:

• generally session
• mutating routes may require admin depending on route policy and centralized guard

5) Setup Wizard APIs

Setup flow APIs under nut_config:

• POST /nut_config/api/setup/test-target
• POST /nut_config/api/setup/test-configuration
• POST /nut_config/api/setup/generate-preview
• POST /nut_config/api/setup/save-config

Use case:

• validation and configuration persistence during wizard completion

Access behavior:

• available during first-time setup bootstrap
• once login is configured, they are protected by session/admin policy

6) Settings and Runtime Formula APIs

• GET /api/settings/variables
• POST /api/settings/variables
• GET /api/settings/operations
• POST /api/settings/operations
• GET /api/options/variable-config

Operational note:

• values may be target-scoped depending on active target and endpoint behavior

7) NUT Service Control APIs

• GET /api/nut/status
• POST /api/nut/start
• POST /api/nut/stop
• POST /api/nut/restart

Use carefully in production.

Access:

• admin

8) Notification Provider APIs (Admin)

• GET/POST/DELETE /api/ntfy/*
• GET/POST/DELETE /api/telegram/*
• GET/POST/DELETE /api/webhook/*
• Mail settings routes under /api/settings/mail*

These are admin-protected and should not be exposed without session control.

9) Remapper APIs

• GET /api/multi-nut/renamer/catalog
• POST /api/multi-nut/renamer/mappings

Use for canonical variable mapping across heterogeneous UPS payloads.

10) Active Target Resolution Rule (Important)

Many target-aware APIs resolve context in this order:

1. explicit target_id override in request
2. session active target
3. primary enabled target fallback

For deterministic integrations, pass explicit target_id when needed.

11) Multi-NUT Report Parameters (Common)

For GET /api/multi-nut/report, common query params:

• scope=selected|all
• target_id=<id> (when scope=selected)
• hours=<window>
• download=true

12) Basic cURL Examples

Read state

curl -sS -b cookie.txt "http://127.0.0.1:5050/api/multi-nut/state"

Read targets

curl -sS -b cookie.txt "http://127.0.0.1:5050/api/multi-nut/targets"

Trigger poll-now on target 2

curl -sS -b cookie.txt -X POST "http://127.0.0.1:5050/api/multi-nut/targets/2/poll-now"

Export selected target report (24h)

curl -sS -b cookie.txt "http://127.0.0.1:5050/api/multi-nut/report?scope=selected&target_id=2&hours=24"

Receive NUT callback (token endpoint)

curl -sS -X POST "http://127.0.0.1:5050/api/nut_event" \
  -H "Content-Type: application/json" \
  -H "X-Nutify-Token: <YOUR_TOKEN>" \
  -d '{"ups":"ups@localhost","event":"ONBATT"}'

13) Integration Safety Checklist

Before integrating API automation:

1. verify route access type (public/session/admin/permission/token)
2. validate target context behavior (target_id vs session)
3. test in staging profile first
4. capture error payloads in logs
5. avoid destructive actions without operator confirmation