MaintainX Hello World
Overview
Create your first work order using the MaintainX REST API -- the core building block of CMMS operations.
Prerequisites
- Completed
maintainx-install-auth setup
- Valid
MAINTAINX_API_KEY environment variable
- Node.js 18+ or curl
Instructions
Step 1: Create a Work Order (curl)
curl -X POST https://api.getmaintainx.com/v1/workorders \
-H "Authorization: Bearer $MAINTAINX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Hello World - Test Work Order",
"description": "First API-created work order. Safe to delete.",
"priority": "LOW",
"status": "OPEN"
}' | jq .
Expected response:
{
"id": 12345,
"title": "Hello World - Test Work Order",
"status": "OPEN",
"priority": "LOW",
"createdAt": "2026-03-19T12:00:00Z"
}
Step 2: Create a Work Order (TypeScript)
import { MaintainXClient } from './maintainx/client';
async function helloMaintainX() {
const client = new MaintainXClient();
const { data: workOrder } = await client.createWorkOrder({
title: 'HVAC Filter Replacement - Building A',
description: 'Replace air filters in units 1-4 on the 3rd floor.',
priority: 'MEDIUM',
});
console.log('Created work order:', workOrder.id);
const { data: fetched } = await client.getWorkOrder(workOrder.id);
console.log('Work order status:', fetched.status);
console.log('Created at:', fetched.createdAt);
const { data: list } = await client.getWorkOrders({
status: 'OPEN',
limit: 5,
});
console.log(`Found ${list.workOrders.length} open work orders`);
}
helloMaintainX();
Step 3: Verify and Clean Up
curl -s "https://api.getmaintainx.com/v1/workorders?limit=3" \
-H "Authorization: Bearer $MAINTAINX_API_KEY" | jq '.workOrders[] | {id, title, status}'
curl -X DELETE "https://api.getmaintainx.com/v1/workorders/12345" \
-H "Authorization: Bearer $MAINTAINX_API_KEY"
Output
- Working code file that creates a MaintainX work order via REST API
- Console output showing the created work order ID, status, and timestamp
- Verified retrieval of the created work order
Error Handling
| Error | Cause | Solution |
|---|
| 400 Bad Request | Missing required title field | Include at least title in the POST body |
| 401 Unauthorized | Invalid API key | Check MAINTAINX_API_KEY environment variable |
| 403 Forbidden | Plan limitations | Verify API access on your subscription |
| 422 Unprocessable | Invalid enum value | Use valid priority (NONE, LOW, MEDIUM, HIGH) |
Resources
Next Steps
Proceed to maintainx-local-dev-loop for development workflow setup.
Examples
Create a work order tied to an asset:
const wo = await client.createWorkOrder({
title: 'Conveyor Belt #7 - Bearing Replacement',
description: 'Replace worn bearings on the main drive shaft.',
priority: 'HIGH',
assetId: 98765,
locationId: 54321,
assignees: [{ type: 'USER', id: 111 }],
dueDate: '2026-03-25T17:00:00Z',
});
Create a work order from a preventive maintenance template:
curl -X POST https://api.getmaintainx.com/v1/workorders \
-H "Authorization: Bearer $MAINTAINX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Monthly Fire Extinguisher Inspection",
"priority": "MEDIUM",
"categories": ["PREVENTIVE"],
"procedureId": 7890
}'
