API Reference
Maintenance API
Plan CRUD endpoints, execute, preview, test notification, pause/resume, counters, history, compliance, and optimization.
Plan Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/maintenance/plans | List plans |
POST | /api/v1/maintenance/plans | Create plan |
GET | /api/v1/maintenance/plans/{plan_id} | Get plan |
PUT | /api/v1/maintenance/plans/{plan_id} | Update plan |
DELETE | /api/v1/maintenance/plans/{plan_id} | Delete plan |
Execution and Preview
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/maintenance/plans/{plan_id}/execute | Execute plan manually |
GET | /api/v1/maintenance/plans/{plan_id}/preview | Preview task to be generated |
POST | /api/v1/maintenance/plans/{plan_id}/test-notification | Send test notification |
Execute Plan
Forces immediate plan execution, generating the task without waiting for the scheduler:
POST /api/v1/maintenance/plans/{plan_id}/executeResponse 200:
{
"task_id": "task_abc123",
"task_code": "MAN-042",
"next_due_at": "2026-04-24T10:00:00Z"
}Task Preview
Shows what the generated task would look like without executing the plan:
GET /api/v1/maintenance/plans/{plan_id}/previewPause and Resume
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/maintenance/plans/{plan_id}/pause | Pause plan |
POST | /api/v1/maintenance/plans/{plan_id}/resume | Resume plan |
Pausing a plan preserves the
next_due_at date. On resume, it recalculates if the date has passed.Counters
For plans with counter-based triggers:
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/maintenance/plans/{plan_id}/counter | Update counter |
GET | /api/v1/maintenance/plans/{plan_id}/counter/history | Counter history |
POST /api/v1/maintenance/plans/{plan_id}/counter
{
"value": 523,
"source": "gateway_001"
}If the value reaches the threshold, the plan executes automatically.
Execution History
GET /api/v1/maintenance/plans/{plan_id}/history?skip=0&limit=20Each entry includes:
| Field | Description |
|---|---|
execution_id | Unique execution ID |
task_id | Generated task |
trigger | calendar or counter |
executed_at | Execution timestamp |
executed_by | system or user_id |
Compliance
GET /api/v1/maintenance/compliance?start_date=2026-01-01&end_date=2026-03-31Returns preventive maintenance compliance metrics:
| Metric | Description |
|---|---|
compliance_rate | % of plans executed on time |
overdue_count | Overdue plans in the period |
on_time_count | Plans executed within the deadline |
average_delay_hours | Average delay on late executions |
Optimization
POST /api/v1/maintenance/plans/{plan_id}/optimizeThe AI engine analyzes the plan's history and suggests adjustments:
- Optimal frequency based on failure patterns
- Workload redistribution among technicians
- Multi-asset route consolidation
- Counter threshold adjustments
Suggestions are presented as a draft for the user to approve before applying.