PrintMaster DOCS
GitHub ↗
Documentation

API Reference

REST API documentation for PrintMaster Agent and Server.

Agent API

Base URL: http://localhost:8080 (default agent port)

Device Management

List Discovered Devices

GET /devices/discovered

Returns devices found but not yet saved.

Response:

[{
  "IP": "10.0.0.100",
  "Manufacturer": "HP",
  "Model": "LaserJet Pro M404n",
  "Serial": "JPBCD12345",
  "PageCount": 12453,
  "TonerLevels": {"Black": 45}
}]

List Saved Devices

GET /devices/list

Returns all saved devices with full metadata.

Get Device Profile

GET /api/devices/profile?serial={serial}

Get canonical device profile by serial number.

Response:

{
  "device": { /* Device object */ },
  "latest_metrics": { /* MetricsSnapshot or null */ }
}

Save Device

POST /devices/save
Content-Type: application/json

{"serial": "JPBCD12345"}

Save All Discovered

POST /devices/save/all

Delete Device

POST /devices/delete
Content-Type: application/json

{"serial": "JPBCD12345"}

Permanently removes device and all history.

Update Device Metadata

POST /devices/update
Content-Type: application/json

{
  "serial": "JPBCD12345",
  "asset_number": "IT-2024-001",
  "location": "3rd Floor Copy Room",
  "description": "Main office printer"
}

Discovery

Start Discovery Scan

POST /discover

Scans configured IP ranges and local subnet.

Metrics

Collect Device Metrics

POST /devices/metrics/collect
Content-Type: application/json

{"serial": "JPBCD12345"}

Get Latest Metrics

GET /api/devices/metrics/latest?serial={serial}

Get Metrics History

GET /api/devices/metrics/history?serial={serial}&since={iso}&until={iso}

Query params use RFC3339 timestamps.

Settings

Get Settings

GET /settings

Response:

{
  "discovery": {
    "subnet_scan": true,
    "manual_ranges": true,
    "ranges_text": "10.0.0.1-10.0.0.254",
    "enable_snmp": true,
    "snmp_timeout_ms": 2000,
    "discover_concurrency": 20
  }
}

Update Settings

POST /settings
Content-Type: application/json

{
  "discovery": {
    "subnet_scan": true,
    "snmp_timeout_ms": 3000
  }
}

Partial updates supported.

Real-Time Updates

Server-Sent Events

GET /events

SSE stream for real-time UI updates.

Events:

  • connected - Connection established
  • discovery_update - Discovery progress
  • device_change - Device updated
const eventSource = new EventSource('/events');
eventSource.addEventListener('discovery_update', (e) => {
  console.log('Progress:', JSON.parse(e.data));
});

Logging

Get Recent Logs

GET /logs?level=INFO&tail=100

Download Log File

GET /logfile

Server API

Base URL: http://localhost:9090 (default server port)

Health Check

GET /api/v1/health

Agent Registration

Register Agent

POST /api/v1/agents/register
Content-Type: application/json

{
  "agent_id": "uuid",
  "name": "Office Agent",
  "version": "0.23.6"
}

Agent Heartbeat

POST /api/v1/agents/heartbeat
Content-Type: application/json

{
  "agent_id": "uuid",
  "device_count": 15
}

WebSocket Connection

Agent WebSocket

WS /api/v1/agents/ws

Real-time communication channel for agent-server communication.

Fleet Management

List Agents

GET /api/v1/agents

Get Agent Details

GET /api/v1/agents/{agent_id}

List All Devices

GET /api/v1/devices

Aggregated view across all agents.

Authentication

Agent API

The agent UI supports multiple authentication modes:

ModeBehavior
localNo login required; admin tasks require loopback access
serverDelegates authentication to central server
disabledNo authentication (development only)

Configure in config.toml:

[web.auth]
mode = "local"
allow_local_admin = true

Server API

The server requires authentication for most endpoints.

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}

Response:

{
  "token": "session-token",
  "expires_at": "2025-12-29T12:00:00Z"
}

Include the token in subsequent requests:

Authorization: Bearer {token}

Error Handling

HTTP Status Codes:

  • 200 OK - Success
  • 400 Bad Request - Invalid parameters
  • 401 Unauthorized - Authentication required
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

Error Response:

{
  "error": "Device not found",
  "details": "No device with serial JPBCD12345"
}

Examples

JavaScript: Discover and Save

// Start discovery
await fetch('/discover', {method: 'POST'});

// Get discovered devices
const resp = await fetch('/devices/discovered');
const devices = await resp.json();

// Save first device
await fetch('/devices/save', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({serial: devices[0].Serial})
});

curl: Update Settings

curl -X POST http://localhost:8080/settings \
  -H "Content-Type: application/json" \
  -d '{
    "discovery": {
      "subnet_scan": true,
      "snmp_timeout_ms": 3000
    }
  }'

PowerShell: Get Device List

$devices = Invoke-RestMethod -Uri "http://localhost:8080/devices/list"
$devices | ForEach-Object { "$($_.Model) - $($_.Serial)" }

See Also