Tasks API

API endpoints for scheduled task management.

Create and manage scheduled tasks via the REST API.

Endpoints Overview

Method	Endpoint	Description
GET	/tasks	List tasks
POST	/tasks	Create task
GET	/tasks/:id	Get task
PUT	/tasks/:id	Update task
DELETE	/tasks/:id	Delete task
POST	/tasks/:id/run	Run immediately

List Tasks

GET /api/v1/tasks

Permission: tasks:read

Query Parameters:

Parameter	Description	Example
`projectId`	Filter by project	`my-project`
`type`	Filter by type	`backup`, `health-check`
`enabled`	Filter by enabled	`true`, `false`

Response:

{
  "tasks": [
    {
      "id": "task-123",
      "name": "Daily Backup",
      "type": "backup",
      "enabled": true,
      "projectId": "my-project",
      "projectName": "My Project",
      "cronExpression": "0 2 * * *",
      "timezone": "America/New_York",
      "nextRun": "2026-01-20T07:00:00Z",
      "lastRun": "2026-01-19T07:00:00Z",
      "lastStatus": "success",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Create Task

POST /api/v1/tasks

Permission: tasks:write

Health Check Task

{
  "name": "Production Health Check",
  "enabled": true,
  "type": "health-check",
  "projectId": "production",
  "cronExpression": "*/5 * * * *",
  "timezone": "UTC",
  "healthCheckConfig": {
    "checkContainers": true,
    "checkConnectivity": true,
    "alertOnFailure": true
  }
}

Backup Task

{
  "name": "Daily Full Backup",
  "enabled": true,
  "type": "backup",
  "projectId": "production",
  "cronExpression": "0 2 * * *",
  "timezone": "America/New_York",
  "backupConfig": {
    "type": "full",
    "destination": "s3",
    "encrypt": true
  }
}

Container Update Task

{
  "name": "Weekly Updates",
  "enabled": true,
  "type": "container-update",
  "projectId": "production",
  "cronExpression": "0 4 * * 0",
  "timezone": "UTC",
  "containerUpdateConfig": {
    "pullImages": true,
    "restartAfterUpdate": true
  }
}

Custom Task

{
  "name": "Database Vacuum",
  "enabled": true,
  "type": "custom",
  "projectId": "production",
  "cronExpression": "0 5 * * 0",
  "timezone": "UTC",
  "customConfig": {
    "command": "docker exec production-db psql -U postgres -c 'VACUUM ANALYZE;'"
  }
}

Response:

{
  "success": true,
  "task": {
    "id": "task-456",
    "name": "Daily Full Backup",
    "type": "backup",
    "enabled": true,
    "nextRun": "2026-01-20T07:00:00Z",
    "createdAt": "2026-01-19T12:00:00Z"
  }
}

Get Task

GET /api/v1/tasks/:id

Permission: tasks:read

Response:

{
  "id": "task-123",
  "name": "Daily Backup",
  "type": "backup",
  "enabled": true,
  "projectId": "my-project",
  "projectName": "My Project",
  "cronExpression": "0 2 * * *",
  "timezone": "America/New_York",
  "backupConfig": {
    "type": "full",
    "destination": "s3",
    "encrypt": true
  },
  "nextRun": "2026-01-20T07:00:00Z",
  "lastRun": "2026-01-19T07:00:00Z",
  "lastStatus": "success",
  "history": [
    {
      "executedAt": "2026-01-19T07:00:00Z",
      "status": "success",
      "duration": 120000,
      "result": {
        "backupId": "backup-789",
        "size": 52428800
      }
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z"
}

Update Task

PUT /api/v1/tasks/:id

Permission: tasks:write

Request:

{
  "name": "Updated Task Name",
  "enabled": false,
  "cronExpression": "0 3 * * *"
}

Response:

{
  "success": true,
  "task": {
    "id": "task-123",
    "name": "Updated Task Name",
    "enabled": false,
    "cronExpression": "0 3 * * *",
    "nextRun": null
  }
}

Delete Task

DELETE /api/v1/tasks/:id

Permission: tasks:write

Response:

{
  "success": true,
  "message": "Task deleted"
}

Run Task Immediately

POST /api/v1/tasks/:id/run

Permission: tasks:write

Executes the task immediately, regardless of schedule.

Response:

{
  "success": true,
  "execution": {
    "status": "success",
    "duration": 120000,
    "result": {
      "backupId": "backup-790",
      "size": 52428800
    }
  }
}

Task Types

Type	Description
`health-check`	Monitor project health
`backup`	Create backups
`container-update`	Update Docker images
`custom`	Run custom commands

Cron Expression Format

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6)
* * * * *

Examples:

Expression	Description
`/5 * * *`	Every 5 minutes
`0 * * * *`	Every hour
`0 2 * * *`	Daily at 2 AM
`0 2 * * 0`	Sunday at 2 AM
`0 2 1 * *`	1st of month at 2 AM

Error Responses

Invalid Cron Expression

{
  "success": false,
  "error": "Invalid cron expression"
}

Status: 400

Project Not Found

{
  "success": false,
  "error": "Project not found"
}

Status: 400

Task Not Found

{
  "success": false,
  "error": "Task not found"
}

Status: 404