> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Finsys/dockhand/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Schedule

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

## Path Parameters

<ParamField path="containerName" type="string" required>
  Name of the container to schedule (URL-encoded if contains special characters)
</ParamField>

## Query Parameters

<ParamField query="env" type="number">
  Environment ID. If not provided, schedule applies to the default environment.
</ParamField>

## Request Body

<ParamField body="enabled" type="boolean" required>
  Enable or disable the schedule. Setting to `false` will delete the schedule entirely.
</ParamField>

<ParamField body="scheduleType" type="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.
</ParamField>

<ParamField body="cronExpression" type="string" required>
  Cron expression defining when the schedule runs. Standard 5-field format: `minute hour day month weekday`

  See [Cron Expression Format](#cron-expression-format) for details and examples.
</ParamField>

<ParamField body="vulnerabilityCriteria" type="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.
</ParamField>

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

<CodeGroup>
  ```text Daily at 3:00 AM theme={null}
  0 3 * * *
  ```

  ```text Every Monday at 2:30 AM theme={null}
  30 2 * * 1
  ```

  ```text Every 6 hours theme={null}
  0 */6 * * *
  ```

  ```text Twice daily (6 AM and 6 PM) theme={null}
  0 6,18 * * *
  ```

  ```text First day of every month at midnight theme={null}
  0 0 1 * *
  ```

  ```text Weekdays at 9 AM theme={null}
  0 9 * * 1-5
  ```
</CodeGroup>

## Response

Returns the created or updated schedule configuration.

<ResponseField name="id" type="number">
  Unique schedule identifier
</ResponseField>

<ResponseField name="containerName" type="string">
  Name of the container
</ResponseField>

<ResponseField name="environmentId" type="number | null">
  Associated environment ID
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Whether the schedule is enabled
</ResponseField>

<ResponseField name="scheduleType" type="string">
  Schedule frequency type (daily, weekly, or custom)
</ResponseField>

<ResponseField name="cronExpression" type="string">
  The cron expression for this schedule
</ResponseField>

<ResponseField name="vulnerabilityCriteria" type="string">
  The vulnerability blocking criteria
</ResponseField>

<ResponseField name="deleted" type="boolean">
  Only present when `enabled: false` is sent, indicating the schedule was deleted
</ResponseField>

## Request Examples

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://dockhand.example.com/api/auto-update/nginx?env=1',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        enabled: true,
        cronExpression: '0 3 * * *',
        vulnerabilityCriteria: 'critical_high'
      })
    }
  );

  const schedule = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://dockhand.example.com/api/auto-update/nginx',
      params={'env': 1},
      json={
          'enabled': True,
          'cronExpression': '0 3 * * *',
          'vulnerabilityCriteria': 'critical_high'
      }
  )

  schedule = response.json()
  ```
</RequestExample>

## Response Examples

<ResponseExample>
  ```json Success - Schedule Created theme={null}
  {
    "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"
  }
  ```

  ```json Success - Schedule Deleted theme={null}
  {
    "success": true,
    "deleted": true
  }
  ```

  ```json Error - Invalid Schedule theme={null}
  {
    "error": "Invalid cron expression"
  }
  ```
</ResponseExample>

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