Machines API

TL;DR

The Machines API lets you list, view, update, and delete machines registered with CMDOP. Filter machines by status (online/offline) or tags, retrieve detailed machine info including OS, architecture, and agent version, check real-time status with CPU/memory/disk metrics, and update machine names or tags via PATCH requests.

How do I list machines?


GET /machines

What query parameters are supported?

Parameter	Type	Description
`status`	string	Filter by status: `online`, `offline`
`tags`	string	Comma-separated tags
`search`	string	Search by name
`limit`	number	Results per page (default: 20)
`offset`	number	Offset for pagination

Example


# List online machines, returning up to 10 results
curl "https://api.cmdop.com/v1/machines?status=online&limit=10" \
  -H "Authorization: Bearer TOKEN"

Response


{
  "data": [
    {
      "id": "mach_abc123",
      "name": "production-server",
      "status": "online",
      "os": "linux",
      "arch": "amd64",
      "hostname": "prod-1.example.com",
      "tags": ["production", "web"],
      "created_at": "2024-01-15T10:30:00Z",
      "last_seen": "2024-01-20T15:45:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "limit": 10,
    "offset": 0
  }
}

How do I get a specific machine?


GET /machines/:id

Example


# Fetch detailed info for a single machine by ID
curl https://api.cmdop.com/v1/machines/mach_abc123 \
  -H "Authorization: Bearer TOKEN"

Response


{
  "data": {
    "id": "mach_abc123",
    "name": "production-server",
    "status": "online",
    "os": "linux",
    "arch": "amd64",
    "hostname": "prod-1.example.com",
    "ip": "192.168.1.100",
    "tags": ["production", "web"],
    "agent_version": "1.2.3",
    "created_at": "2024-01-15T10:30:00Z",
    "last_seen": "2024-01-20T15:45:00Z"
  }
}

How do I check machine status and metrics?


GET /machines/:id/status

Response


{
  "data": {
    "connected": true,
    "uptime": 86400,
    "last_ping": "2024-01-20T15:45:00Z",
    "cpu": {
      "usage": 45.2,
      "cores": 4
    },
    "memory": {
      "total": 8589934592,
      "used": 4294967296,
      "free": 4294967296
    },
    "disk": {
      "total": 107374182400,
      "used": 53687091200,
      "free": 53687091200
    }
  }
}

How do I update a machine?


PATCH /machines/:id

Request Body


{
  "name": "new-name",
  "tags": ["production", "api"]
}

Example


# Update machine name using PATCH with JSON body
curl -X PATCH https://api.cmdop.com/v1/machines/mach_abc123 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-name"}'

How do I delete a machine?


DELETE /machines/:id

Example


# Remove a machine from your workspace permanently
curl -X DELETE https://api.cmdop.com/v1/machines/mach_abc123 \
  -H "Authorization: Bearer TOKEN"

Response


{
  "data": {
    "deleted": true
  }
}