Skip to main content
POST
/
api
/
auto-update
/
{containerName}
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"
  }'

{
  "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 weekdaySee 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

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 -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

{
  "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

Build docs developers (and LLMs) love

Get started for freeTalk to us