Configure Auto-Update

POST /api/auto-update/{containerName}

Daily updates (allow critical/high)

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

Success - Configured

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

Configures automated update settings for a container, including scheduling and vulnerability-based update policies.

Overview

This endpoint allows you to configure how and when containers are automatically updated. You can:

• Set update schedules using cron expressions
• Define vulnerability criteria to block unsafe updates
• Enable or disable auto-updates per container

Path Parameters

containerName · string · required

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

Query Parameters

env · number

Environment ID. Omit for default environment.

Request Body

enabled · boolean · required

Enable or disable auto-updates. Setting to false deletes the configuration.

cronExpression · string · required

Cron expression for update schedule. Uses standard 5-field format.

Example: "0 3 * * *" (daily at 3 AM)

vulnerabilityCriteria · string · default: "never"

Policy for blocking updates based on vulnerability scan results:

Show Criteria Options

• never - Always update regardless of vulnerabilities (default)
• any - Block if new image has any vulnerabilities
• critical_high - Block if critical or high severity vulnerabilities found
• critical - Block only on critical severity vulnerabilities
• more_than_current - Block if new image has more vulnerabilities than current

Requires vulnerability scanning to be enabled for the environment. If scanning is disabled, this setting is ignored.

scheduleType · string

Optional schedule type hint. Auto-detected from cronExpression if omitted.

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

Vulnerability Criteria Details

How Vulnerability Blocking Works

When auto-update runs:

1. Checks if new image version is available
2. If scanning enabled, scans the new image
3. Evaluates scan results against configured criteria
4. Blocks or proceeds with update based on criteria

Criteria Behavior

never

Updates are never blocked based on vulnerabilities. This is the default and most permissive setting.

Use when: You want updates to always proceed, relying on other security measures.

any

Blocks updates if the new image contains any vulnerabilities at any severity level.

Use when: You have a zero-tolerance policy for vulnerabilities.

Example: New image has 1 low severity vulnerability → Update blocked

critical_high

Blocks updates only if critical or high severity vulnerabilities are found.

Use when: You want to prevent serious vulnerabilities while accepting minor risks.

Example: New image has 5 medium vulnerabilities → Update proceeds
Example: New image has 1 critical vulnerability → Update blocked

critical

Blocks updates only if critical severity vulnerabilities are found.

Use when: You want to balance security with update frequency.

Example: New image has 2 high vulnerabilities → Update proceeds
Example: New image has 1 critical vulnerability → Update blocked

more_than_current

Blocks updates if the new image has more total vulnerabilities than the currently running image.

Use when: You want to ensure security posture never degrades.

Example: Current: 5 vulns, New: 3 vulns → Update proceeds
Example: Current: 5 vulns, New: 7 vulns → Update blocked

If current image has no scan data, update proceeds regardless.

Cron Expression Format

Schedules use standard 5-field cron format:

minute hour day month weekday

Field Ranges

Field	Values	Special
minute	0-59	* = every minute
hour	0-23	*/n = every n hours
day	1-31	Day of month
month	1-12	* = every month
weekday	0-7	0 or 7 = Sunday

Example Schedules

Daily at 3 AM

0 3 * * *

Response

id · number

Auto-update configuration ID

containerName · string

Container name

environmentId · number | null

Associated environment ID

enabled · boolean

Whether auto-update is enabled

scheduleType · string

Detected schedule type

cronExpression · string

Cron expression for schedule

vulnerabilityCriteria · string

Active vulnerability criteria

createdAt · string

ISO 8601 timestamp of creation

updatedAt · string

ISO 8601 timestamp of last update

Examples

Daily updates (allow critical/high)

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

Success - Configured

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

Important Notes

Disabling auto-update: Setting enabled: false permanently deletes the configuration. Re-enabling requires creating a new configuration.

Vulnerability scanning: The vulnerabilityCriteria setting only takes effect if vulnerability scanning is enabled for the environment. Check environment scanner settings.

Testing schedules: Monitor the schedules list to verify your configuration is active.

Related Endpoints

• List Schedules - View all configured schedules
• Create Schedule - Create additional schedules