maintainx-hello-world

# 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)

```bash
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:
```json
{
  "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)

```typescript
// hello-maintainx.ts
import { MaintainXClient } from './maintainx/client';

async function helloMaintainX() {
  const client = new MaintainXClient();

  // Create a basic work order
  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);

  // Retrieve it back to confirm
  const { data: fetched } = await client.getWorkOrder(workOrder.id);
  console.log('Work order status:', fetched.status);
  console.log('Created at:', fetched.createdAt);

  // List open work orders
  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

```bash
# List recent work orders to confirm creation
curl -s "https://api.getmaintainx.com/v1/workorders?limit=3" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" | jq '.workOrders[] | {id, title, status}'

# Delete the test work order (replace ID)
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
- [MaintainX API Reference](https://developer.maintainx.com/reference)
- [Work Orders Help](https://help.getmaintainx.com/about-work-orders)

## Next Steps
Proceed to `maintainx-local-dev-loop` for development workflow setup.

## Examples

**Create a work order tied to an asset**:

```typescript
const wo = await client.createWorkOrder({
  title: 'Conveyor Belt #7 - Bearing Replacement',
  description: 'Replace worn bearings on the main drive shaft.',
  priority: 'HIGH',
  assetId: 98765,       // Link to equipment asset
  locationId: 54321,    // Link to facility location
  assignees: [{ type: 'USER', id: 111 }],
  dueDate: '2026-03-25T17:00:00Z',
});
```

**Create a work order from a preventive maintenance template**:

```bash
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
  }'
```