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.
Scheduling is part of the relay’s live surface, but the exact paths and field shapes documented here describe the planned hosted API (/v1/... on the managed cloud) and may differ from a given self-hosted relay version. Treat the shapes below as the target reference; the SDKs and CLI track what ships.
How do I list schedules?
GET /schedulesWhat 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/:idResponse
{
"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 /schedulesWhat 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/:idRequest Body
{
"name": "Updated Name",
"cron": "0 4 * * *",
"enabled": false
}How do I delete a schedule?
DELETE /schedules/:idResponse
{
"data": {
"deleted": true
}
}How do I trigger a schedule immediately?
Trigger schedule immediately:
POST /schedules/:id/runResponse
{
"data": {
"command_id": "cmd_xyz789",
"status": "running"
}
}How do I view schedule execution history?
GET /schedules/:id/historyQuery 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
}
}
Cmdop