Schedules API

TL;DR

The Schedules API lets you create, manage, and monitor cron-based scheduled tasks on remote machines via CMDOP. Define commands with cron expressions and timezones, enable/disable schedules, trigger immediate runs, and view execution history with exit codes and duration. Supports failure notifications and configurable timeouts.

How do I list schedules?


GET /schedules

What query parameters are supported?

Parameter	Type	Description
`machine_id`	string	Filter by machine
`enabled`	boolean	Filter by status
`limit`	number	Results per page
`offset`	number	Pagination offset

Response


{
  "data": [
    {
      "id": "sched_abc123",
      "name": "Daily Backup",
      "machine_id": "mach_xyz789",
      "command": "pg_dump mydb > /backup/db.sql",
      "cron": "0 3 * * *",
      "enabled": true,
      "timezone": "UTC",
      "next_run": "2024-01-21T03:00:00Z",
      "last_run": {
        "at": "2024-01-20T03:00:00Z",
        "exit_code": 0,
        "duration": 15000
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 10,
    "limit": 20,
    "offset": 0
  }
}

How do I get a specific schedule?


GET /schedules/:id

Response


{
  "data": {
    "id": "sched_abc123",
    "name": "Daily Backup",
    "description": "Backup production database every night",
    "machine_id": "mach_xyz789",
    "command": "pg_dump mydb > /backup/db.sql",
    "cron": "0 3 * * *",
    "enabled": true,
    "timezone": "UTC",
    "timeout": 300000,
    "notify": {
      "on_success": false,
      "on_failure": true
    },
    "next_run": "2024-01-21T03:00:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-18T14:20:00Z"
  }
}

How do I create a schedule?


POST /schedules

What fields does the request body accept?

Field	Type	Required	Description
`name`	string	Yes	Schedule name
`machine_id`	string	Yes	Target machine
`command`	string	Yes	Command to run
`cron`	string	Yes	Cron expression
`enabled`	boolean	No	Default: true
`timezone`	string	No	Default: UTC
`timeout`	number	No	Timeout in ms
`notify`	object	No	Notification settings

Example


# Create a daily backup schedule running at 3 AM Eastern
curl -X POST https://api.cmdop.com/v1/schedules \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Backup",
    "machine_id": "mach_xyz789",
    "command": "pg_dump mydb > /backup/db.sql",
    "cron": "0 3 * * *",
    "timezone": "America/New_York",
    "notify": {
      "on_failure": true
    }
  }'

How do I update a schedule?


PATCH /schedules/:id

Request Body


{
  "name": "Updated Name",
  "cron": "0 4 * * *",
  "enabled": false
}

How do I delete a schedule?


DELETE /schedules/:id

Response


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

How do I trigger a schedule immediately?

Trigger schedule immediately:


POST /schedules/:id/run

Response


{
  "data": {
    "command_id": "cmd_xyz789",
    "status": "running"
  }
}

How do I view schedule execution history?


GET /schedules/:id/history

Query Parameters

Parameter	Type	Description
`since`	string	ISO timestamp
`limit`	number	Results per page

Response


{
  "data": [
    {
      "id": "run_abc123",
      "started_at": "2024-01-20T03:00:00Z",
      "finished_at": "2024-01-20T03:00:15Z",
      "exit_code": 0,
      "duration": 15000,
      "stdout": "...",
      "stderr": ""
    }
  ],
  "meta": {
    "total": 30,
    "limit": 20,
    "offset": 0
  }
}