This page provides a customer-facing reference structure for CMMS integration surfaces. Use it for integration planning and handoff. Exact endpoint availability, payload shape, and provider mappings depend on the deployed product scope and customer-approved integration mode.
API Surface Map
Prerequisites
| Requirement | Why it matters |
|---|
| Deployment scope | Endpoint availability depends on enabled modules and customer integration scope |
| Service identity | API calls need scoped credentials and audit records |
| Data contract | Work-order, asset, status, priority, SLA, and attachment fields must be mapped |
| Ownership rule | Read, draft, handoff, and write-back modes need separate approval |
| Error handling | Retries, partial failures, duplicate prevention, and sync exceptions need a defined policy |
| Test environment | Integration tests should run outside production before go-live |
| Input | Use |
|---|
| Work-order payload | Create, update, search, assign, or close work-order records |
| Asset reference | Links work orders to MDM asset and location identity |
| Provider reference | Preserves downstream source system, native ID, and sync state |
| Attachment payload | Links files and evidence to ECM |
| Status transition payload | Supports lifecycle updates and review records |
| Webhook event | Notifies FactVerse or provider systems about changes |
| Error payload | Records rejected fields, provider response, retry state, and owner action |
Common Resource Groups
| Resource group | Use |
|---|
| Work orders | Read, create, update, assign, comment, attach, complete, close, reopen, or cancel records |
| Worker execution | Support field task views, progress updates, issue reports, evidence upload, and closeout |
| Operations read model | Read normalized work-order, asset, provider, status, audit, and sync state |
| Attachments and evidence | Link ECM documents, photos, service reports, and closeout packages |
| Provider connectors | Configure and monitor imports, exports, webhooks, and synchronization jobs |
| Status mapping | Maintain provider status, priority, and lifecycle mappings |
| Audit and sync logs | Review imports, handoffs, write-back attempts, retries, and failures |
Current API Anchors
Use runtime OpenAPI output and the customer deployment scope as the final contract. The current platform surface uses these resource groups as anchors for implementation planning:
Adapter Type Reference
| Adapter type | Use |
|---|
webhook | Push work-order events to a downstream endpoint and receive status callbacks through an inbound webhook path |
rest | Configure a vendor-neutral REST profile with customer-approved paths, auth, field mapping, and result parsing |
maximo | Connect IBM Maximo work orders through the approved Maximo REST profile |
sap-pm | Connect SAP Plant Maintenance maintenance orders through the approved SAP OData profile |
| Forge or customer overlay profile | Connect Honeywell Forge or another customer-specific provider through approved overlay wiring and payload contracts |
BACnet, Modbus, and SNMP are field protocol adapters for equipment context. They should not be configured as downstream CMMS work-order adapters.
CMMS Configuration and Monitoring
| API | Use |
|---|
GET /api/v1/cmms/adapters | List CMMS adapter configurations for the current tenant |
POST /api/v1/cmms/adapters | Create an adapter configuration |
POST /api/v1/cmms/adapters/{id}/test | Run a connector health check |
DELETE /api/v1/cmms/adapters/{id} | Remove an adapter configuration |
GET /api/v1/cmms/asset-mappings | Review provider-to-FactVerse asset mappings |
POST /api/v1/cmms/asset-mappings | Create a single asset mapping |
POST /api/v1/cmms/asset-mappings/batch | Create asset mappings in batch |
DELETE /api/v1/cmms/asset-mappings/{id} | Remove an asset mapping |
GET /api/v1/cmms/sync/logs | Review synchronization results for an adapter |
POST /api/v1/cmms/webhook/outbound/test | Test outbound webhook reachability |
GET /api/v1/cmms/dashboard-summary | Read the live CMMS operations summary |
Work Orders
| API | Use |
|---|
GET /api/v1/workorders | List work orders by the available filters |
GET /api/v1/workorders/{id} | Read work-order detail |
POST /api/v1/workorders | Create a native work order |
PUT /api/v1/workorders/{id}/status | Update lifecycle status |
PUT /api/v1/workorders/{id}/start | Mark execution as started |
PUT /api/v1/workorders/{id}/complete | Mark execution as completed |
PUT /api/v1/workorders/{id}/assign | Assign to a user |
PUT /api/v1/workorders/{id}/assign-resource | Assign to a technician or crew resource |
POST /api/v1/workorders/{id}/reassign | Reassign while preserving reassignment history |
POST /api/v1/workorders/{id}/feedback | Record closeout feedback used by maintenance analytics |
GET /api/v1/workorders/{id}/attachments | List work-order evidence files |
POST /api/v1/workorders/{id}/attachments | Upload work-order evidence |
GET /api/v1/workorders/{id}/closed-loop | Review the linked alert, diagnosis, work order, and feedback trail |
Work Requests
| API | Use |
|---|
POST /api/v1/platform/worker-issues | Create a field, mobile, natural-language, or provider-originated work request |
GET /api/v1/platform/worker-issues | List work requests, optionally filtered by channel and status |
POST /api/v1/platform/worker-issues/{id}/triage | Mark a work request as triaged |
POST /api/v1/platform/worker-issues/{id}/reject | Reject a work request with an optional reason |
POST /api/v1/platform/worker-issues/{id}/convert | Convert a work request into a work order |
Technicians and Crews
| API | Use |
|---|
GET /api/v1/technicians | List technician records |
POST /api/v1/technicians | Create a technician record |
PUT /api/v1/technicians/{id}/crew/{crewId} | Add a technician to a crew |
PUT /api/v1/technicians/{id}/deactivate | Deactivate a technician |
GET /api/v1/crews | List crew records |
POST /api/v1/crews | Create a crew |
DELETE /api/v1/crews/{id} | Remove a crew where allowed by the deployment policy |
Preventive Maintenance
| API | Use |
|---|
GET /api/v1/pm/dashboard | Review preventive-maintenance indicators |
GET /api/v1/pm/templates | List preventive-maintenance templates |
POST /api/v1/pm/templates | Create a preventive-maintenance template |
GET /api/v1/pm/schedules | List preventive-maintenance schedules |
GET /api/v1/pm/calendar | Review scheduled maintenance on a calendar |
POST /api/v1/pm/complete | Complete a scheduled maintenance item |
POST /api/v1/pm/skip | Skip a scheduled item with a reason |
Spare Parts and Inventory
| API | Use |
|---|
GET /api/v1/spare-parts | List spare parts |
GET /api/v1/spare-parts/equipment/{equipmentId} | List spare parts associated with equipment |
GET /api/v1/spare-parts/low-stock | Review low-stock items |
GET /api/v1/spare-parts/stats | Review spare-parts summary statistics |
POST /api/v1/spare-parts/{id}/consume | Consume parts during maintenance |
POST /api/v1/spare-parts/{id}/restock | Restock a spare part |
GET /api/v1/inventory/dashboard | Review inventory indicators |
POST /api/v1/inventory/issue | Issue stock |
POST /api/v1/inventory/receive | Receive stock |
GET /api/v1/inventory/transactions | Review inventory transaction history |
GET /api/v1/inventory/valuation | Review inventory valuation where enabled |
The CMMS Agent tool surface is scoped by the tenant Agent configuration. tools/list should show only the CMMS tools bound to the current Agent. tools/call should apply tenant scope, permission checks, risk limits, idempotency, and audit before any tool is executed.
| Tool | Permission | Contract |
|---|
cmms_query_backlog | cmms.read | Read backlog totals, priority distribution, and SLA breach counts. |
cmms_query_equipment | cmms.read | Read equipment or asset records, optionally filtered by site. |
cmms_query_work_orders | cmms.read | Read work orders by status, equipment, and page window. |
cmms_suggest_technician | cmms.read | Return available technician candidates; does not assign work. |
cmms_create_work_request | workorders.create | Create an intake request or field issue report with an audit record. |
cmms_create_work_order | workorders.create | Create a work order after the required review or confirmation step. |
cmms_assign_work_order | workorders.assign | Assign a work order to a technician or crew after confirmation. |
cmms_close_work_order | workorders.complete | Complete a work order after confirmation; completion is a terminal operational action. |
Read tools execute after scope and permission checks. Work-request intake is an audited low-risk write. Work-order creation, assignment, and completion should return a confirmation-required state until an accountable reviewer approves the action. Callers should pass a stable idempotency key when retrying the same logical action.
Predictive-Maintenance Linkage
| API | Use |
|---|
GET /api/v1/pdm/cmms | Read the Predictive Maintenance CMMS connector configuration |
POST /api/v1/pdm/cmms | Configure or update the connector used by Predictive Maintenance workflows |
POST /api/v1/pdm/cmms/test | Test connector reachability |
POST /api/v1/pdm/cmms/webhook | Receive CMMS work-order updates for the predictive-maintenance loop |
GET /api/v1/pdm/advisory | List predictive-maintenance advisories |
GET /api/v1/pdm/advisory/by-workorder/{workOrderId} | Find the advisory linked to a work order |
POST /api/v1/pdm/advisory/{id}/work-order | Link an advisory to a reviewed work order |
POST /api/v1/pdm/advisory/{id}/outcome | Record the field outcome after work-order closeout |
GET /api/v1/pdm/advisory/outcome-stats | Review outcome distribution |
GET /api/v1/pdm/advisory/precision | Review daily precision trend for the advisory loop |
Example Contract Fields
| Field | Purpose |
|---|
common_work_order_id | FactVerse work-order reference |
provider_id | Source CMMS, EAM, contractor system, or integration profile |
source_work_order_id | Native provider work-order ID |
asset_ref | MDM asset, equipment, location, or system reference |
source_status | Provider status value |
common_status | FactVerse lifecycle state |
priority | Normalized priority |
source_priority | Provider priority value |
sla_due_at | Due time used for operations review |
sync_state | Imported, pending, synchronized, retrying, rejected, or stale |
last_synced_at | Latest successful synchronization time |
Webhook and Sync Events
| Event type | Use |
|---|
work_order.created | New provider or FactVerse record enters the integration scope |
work_order.updated | Status, assignment, priority, or description changed |
work_order.completed | Field execution is complete and closeout review can begin |
work_order.closed | Closeout state is finalized |
attachment.added | New file or evidence record is available |
sync.failed | Import, handoff, or write-back needs review |
mapping.exception | Field, status, or asset mapping needs steward action |
Event names are planning references. Use runtime discovery and deployed integration documentation to confirm the names available in a customer environment.
Error Handling
| Error class | Review action |
|---|
| Authentication | Check service identity, credential, environment, and provider allowlist |
| Authorization | Check scope, provider role, tenant boundary, and action level |
| Validation | Check required fields, enum values, timestamp format, and payload schema |
| Identity | Check asset reference, alias mapping, MDM state, and retired assets |
| Conflict | Check source revision, transition rule, duplicate prevention, and ownership |
| Provider unavailable | Check retry policy, queue state, and customer escalation path |
Expected Output
An API handoff should include:
- endpoint or connector list in scope;
- credential and scope matrix;
- payload fields and examples approved by the customer;
- status, priority, and SLA mapping;
- webhook or synchronization behavior;
- error and retry policy;
- test cases and acceptance criteria.
Validation Checklist
- Read endpoints return expected tenant and provider scope.
- Create or draft behavior produces an audit record.
- Status updates follow approved transition rules.
- Attachments link to ECM and the target work order.
- Failed writes are visible in sync history.
- API tests include authentication, authorization, validation, conflict, and retry cases.