Create Schedule

POST /api/auto-update/{containerName}

cURL

curl -X POST "https://dockhand.example.com/api/auto-update/nginx?env=1" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "cronExpression": "0 3 * * *",
    "vulnerabilityCriteria": "critical_high"
  }'

Success - Schedule Created

{
  "id": 1,
  "containerName": "nginx",
  "environmentId": 1,
  "enabled": true,
  "scheduleType": "daily",
  "cronExpression": "0 3 * * *",
  "vulnerabilityCriteria": "critical_high",
  "createdAt": "2026-03-04T10:00:00.000Z",
  "updatedAt": "2026-03-04T10:00:00.000Z"
}

Creates or updates an auto-update schedule for a specific container. Set enabled: false to delete the schedule.

Path Parameters

containerName · string · required

Name of the container to schedule (URL-encoded if contains special characters)

Query Parameters

env · number

Environment ID. If not provided, schedule applies to the default environment.

Request Body

enabled · boolean · required

Enable or disable the schedule. Setting to false will delete the schedule entirely.

scheduleType · string

Schedule frequency type:

• daily - Runs once per day
• weekly - Runs once per week
• custom - Custom cron expression

Auto-detected from cronExpression if not provided.

cronExpression · string · required

Cron expression defining when the schedule runs. Standard 5-field format: minute hour day month weekday

See Cron Expression Format for details and examples.

vulnerabilityCriteria · string

Criteria for blocking updates based on vulnerability scan results:

• never (default) - Never block updates based on vulnerabilities
• any - Block update if any vulnerabilities are found
• critical_high - Block only if critical or high severity vulnerabilities found
• critical - Block only if critical severity vulnerabilities found
• more_than_current - Block if new image has more vulnerabilities than current

Requires vulnerability scanning to be enabled for the environment.

Cron Expression Format

Cron expressions use standard 5-field format:

minute hour day month weekday
*      *    *   *     *

Field Values

• minute: 0-59
• hour: 0-23 (24-hour format)
• day: 1-31 (day of month)
• month: 1-12
• weekday: 0-7 (0 and 7 are Sunday, 1 is Monday)

Special Characters

• * - Any value (e.g., * in hour field means every hour)
• */n - Every nth value (e.g., */6 in hour field means every 6 hours)
• n-m - Range (e.g., 1-5 in weekday field means Monday through Friday)
• n,m - List (e.g., 1,15 in day field means 1st and 15th of month)

Common Schedule Examples

Daily at 3:00 AM

0 3 * * *

Response

Returns the created or updated schedule configuration.

id · number

Unique schedule identifier

containerName · string

Name of the container

environmentId · number | null

Associated environment ID

enabled · boolean

Whether the schedule is enabled

scheduleType · string

Schedule frequency type (daily, weekly, or custom)

cronExpression · string

The cron expression for this schedule

vulnerabilityCriteria · string

The vulnerability blocking criteria

deleted · boolean

Only present when enabled: false is sent, indicating the schedule was deleted

Request Examples

cURL

curl -X POST "https://dockhand.example.com/api/auto-update/nginx?env=1" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "cronExpression": "0 3 * * *",
    "vulnerabilityCriteria": "critical_high"
  }'

Response Examples

Success - Schedule Created

{
  "id": 1,
  "containerName": "nginx",
  "environmentId": 1,
  "enabled": true,
  "scheduleType": "daily",
  "cronExpression": "0 3 * * *",
  "vulnerabilityCriteria": "critical_high",
  "createdAt": "2026-03-04T10:00:00.000Z",
  "updatedAt": "2026-03-04T10:00:00.000Z"
}

Notes

• Setting enabled: false performs a hard delete of the schedule
• The schedule is automatically registered with the task scheduler when enabled
• Vulnerability criteria only applies when environment has scanning enabled
• Schedules respect the environment’s configured timezone
• Updates will be skipped if the container is part of a running stack