# API Reference
[Back to Docs Index](index.md) | [Index (HTML)](index.html)

## Purpose
Provide a consolidated, human-readable list of Borealis Engine API endpoints grouped by domain.

## API Endpoints

### Core
- `GET /health` (No Authentication) - liveness probe.

### Authentication and Access Management
- `POST /api/auth/login` (No Authentication) - operator login.
- `POST /api/auth/logout` (Token Authenticated) - operator logout.
- `POST /api/auth/mfa/verify` (Token Authenticated, MFA pending) - verify MFA.
- `GET /api/auth/me` (Token Authenticated) - current operator profile.
- `GET /api/users` (Admin) - list operator accounts.
- `POST /api/users` (Admin) - create operator account.
- `DELETE /api/users/<username>` (Admin) - delete operator account.
- `POST /api/users/<username>/reset_password` (Admin) - reset operator password.
- `POST /api/users/<username>/role` (Admin) - update operator role.
- `POST /api/users/<username>/mfa` (Admin) - toggle MFA/reset secrets.
- `GET /api/github/token` (Admin) - GitHub API token status.
- `POST /api/github/token` (Admin) - update GitHub API token.

### Enrollment and Tokens
- `POST /api/agent/enroll/request` (No Authentication) - submit enrollment request.
- `POST /api/agent/enroll/poll` (No Authentication) - finalize approved enrollment.
- `POST /api/agent/token/refresh` (Refresh Token) - mint new access token.

### Devices and Inventory
- `POST /api/agent/heartbeat` (Device Authenticated) - heartbeat + metrics.
- `POST /api/agent/details` (Device Authenticated) - full hardware/inventory payload.
- `POST /api/agent/script/request` (Device Authenticated) - request work or idle signal.
- `GET /api/agents` (Token Authenticated) - list online collectors by hostname/context.
- `GET /api/devices` (Token Authenticated) - device summary list.
- `GET /api/devices/<guid>` (Token Authenticated) - device summary by GUID.
- `GET /api/device/details/<hostname>` (Token Authenticated) - full device details.
- `POST /api/device/description/<hostname>` (Token Authenticated) - update description.
- `GET /api/device/vpn_config/<agent_id>` (Token Authenticated) - VPN allowed ports.
- `PUT /api/device/vpn_config/<agent_id>` (Token Authenticated) - update VPN allowed ports.
- `GET /api/device_list_views` (Token Authenticated) - list saved device views.
- `GET /api/device_list_views/<int:view_id>` (Token Authenticated) - get saved view.
- `POST /api/device_list_views` (Token Authenticated) - create saved view.
- `PUT /api/device_list_views/<int:view_id>` (Token Authenticated) - update saved view.
- `DELETE /api/device_list_views/<int:view_id>` (Token Authenticated) - delete saved view.
- `GET /api/sites` (Token Authenticated) - list sites.
- `POST /api/sites` (Admin) - create site.
- `POST /api/sites/delete` (Admin) - delete sites.
- `GET /api/sites/device_map` (Token Authenticated) - hostname to site map.
- `POST /api/sites/assign` (Admin) - assign devices to site.
- `POST /api/sites/rename` (Admin) - rename site.
- `POST /api/sites/rotate_code` (Admin) - rotate site enrollment code.
- `GET /api/repo/current_hash` (Device or Token Authenticated) - current agent repo hash.
- `GET /api/agent/hash` (Device Authenticated) - get agent hash.
- `POST /api/agent/hash` (Device Authenticated) - update agent hash.
- `GET /api/agent/hash_list` (Admin + Loopback) - list agent hashes (local diagnostics).

### Admin Approvals and Install Codes
- `GET /api/admin/enrollment-codes` (Admin) - list install codes.
- `POST /api/admin/enrollment-codes` (Admin) - create install code.
- `DELETE /api/admin/enrollment-codes/<code_id>` (Admin) - delete install code.
- `GET /api/admin/device-approvals` (Admin) - approval queue.
- `POST /api/admin/device-approvals/<approval_id>/approve` (Admin) - approve device.
- `POST /api/admin/device-approvals/<approval_id>/deny` (Admin) - deny device.

### Device Filters
- `GET /api/device_filters` (Token Authenticated) - list filters.
- `GET /api/device_filters/<filter_id>` (Token Authenticated) - get filter.
- `POST /api/device_filters` (Token Authenticated) - create filter.
- `PUT /api/device_filters/<filter_id>` (Token Authenticated) - update filter.

### Assemblies and Execution
- `GET /api/assemblies` (Token Authenticated) - list assemblies.
- `GET /api/assemblies/<assembly_guid>` (Token Authenticated) - assembly details.
- `POST /api/assemblies` (Token Authenticated) - create assembly.
- `PUT /api/assemblies/<assembly_guid>` (Token Authenticated) - update assembly.
- `DELETE /api/assemblies/<assembly_guid>` (Token Authenticated) - delete assembly.
- `POST /api/assemblies/<assembly_guid>/clone` (Admin + Dev Mode for protected domains) - clone assembly.
- `POST /api/assemblies/dev-mode/switch` (Admin) - toggle dev mode.
- `POST /api/assemblies/dev-mode/write` (Admin + Dev Mode) - flush queued writes.
- `POST /api/assemblies/import` (Domain write permission) - import legacy JSON assembly.
- `GET /api/assemblies/<assembly_guid>/export` (Token Authenticated) - export legacy JSON.
- `POST /api/scripts/quick_run` (Token Authenticated) - quick job (PowerShell).
- `POST /api/ansible/quick_run` (Token Authenticated) - placeholder (not implemented).
- `GET /api/device/activity/<hostname>` (Token Authenticated) - device activity history.
- `DELETE /api/device/activity/<hostname>` (Token Authenticated) - clear activity history.
- `GET /api/device/activity/job/<int:job_id>` (Token Authenticated) - activity record details.

### Scheduled Jobs
- `GET /api/scheduled_jobs` (Token Authenticated) - list scheduled jobs.
- `POST /api/scheduled_jobs` (Token Authenticated) - create scheduled job.
- `GET /api/scheduled_jobs/<int:job_id>` (Token Authenticated) - get scheduled job.
- `PUT /api/scheduled_jobs/<int:job_id>` (Token Authenticated) - update scheduled job.
- `POST /api/scheduled_jobs/<int:job_id>/toggle` (Token Authenticated) - enable/disable.
- `DELETE /api/scheduled_jobs/<int:job_id>` (Token Authenticated) - delete scheduled job.
- `GET /api/scheduled_jobs/<int:job_id>/runs` (Token Authenticated) - run history.
- `GET /api/scheduled_jobs/<int:job_id>/devices` (Token Authenticated) - device results.
- `DELETE /api/scheduled_jobs/<int:job_id>/runs` (Token Authenticated) - clear run history.

### Notifications
- `POST /api/notifications/notify` (Token Authenticated) - broadcast toast notification.

### VPN and Remote Access
- `POST /api/tunnel/connect` (Token Authenticated) - start WireGuard tunnel.
- `GET /api/tunnel/status` (Token Authenticated) - tunnel status by agent.
- `GET /api/tunnel/connect/status` (Token Authenticated) - alias for status.
- `GET /api/tunnel/active` (Token Authenticated) - list active tunnels.
- `DELETE /api/tunnel/disconnect` (Token Authenticated) - stop tunnel.

### RDP
- `POST /api/rdp/session` (Token Authenticated) - issue Guacamole RDP session token.

### Server Info and Logs
- `GET /api/server/time` (Operator Session) - server clock.
- `GET /api/server/logs` (Admin) - list logs and retention.
- `GET /api/server/logs/<log_name>/entries` (Admin) - tail log lines.
- `PUT /api/server/logs/retention` (Admin) - update retention policies.
- `DELETE /api/server/logs/<log_name>` (Admin) - delete log file(s).

## Related Documentation
- [Engine Runtime](engine-runtime.md)
- [Device Management](device-management.md)
- [Assemblies and Quick Jobs](assemblies.md)
- [Scheduled Jobs](scheduled-jobs.md)
- [VPN and Remote Access](vpn-and-remote-access.md)

## Codex Agent (Detailed)
### Where endpoints are defined
- Each API module begins with a header listing endpoints.
- Search under `Data/Engine/services/API/` to find the authoritative source.
- The registry lives in `Data/Engine/services/API/__init__.py`.

### How to keep this doc accurate
- When you add or remove a route, update:
  1) The module header comment in the source file.
  2) This `api-reference.md` page.
  3) The domain page (example: `device-management.md`).

### Quick discovery workflow
- Use `rg "# - (GET|POST|PUT|DELETE)" Data/Engine/services/API` to list endpoints.
- Cross-check auth requirements in each module (RequestAuthContext, session checks, or device auth decorators).
- If a route is Socket.IO only, document it in the relevant domain page instead of this REST list.

### Auth labels used in this doc
- No Authentication: open endpoints (rare).
- Token Authenticated: operator session or bearer token.
- Device Authenticated: agent JWT access token.
- Admin: operator must have Admin role.

### Example update scenario
- You add `POST /api/devices/retire`:
  - Update `Data/Engine/services/API/devices/management.py` header.
  - Add the endpoint under the Devices and Inventory section here.
  - Update `device-management.md` with behavior and UI impact.