---
title: "Create scan mode"
method: POST
path: "/api/scan-modes"
tags: ["Scan Modes"]
---

# Create scan mode

`POST /api/scan-modes`

Creates a new scan mode with the provided configuration

## Request body

- ScanModeCommandDTO — Command DTO for creating or updating a scan mode. Used as the request body for scan mode creation/update endpoints.
  - `name` string, required — The name of the scan mode.
  - `description` string, required — A description of the scan mode's purpose or behavior.
  - `type` 'cron' | 'interval', required — How a scan mode decides when to tick. - `cron`: driven by a cron expression (the historical behaviour). - `interval`: driven by a fixed period between ticks.
  - `cron` string, required — A cron expression defining the scan schedule. Ignored when `type` is `"interval"`.
  - `interval` ScanModeInterval, required — Fixed period between two ticks of an `interval` scan mode.
    - `value` number, double, required — How many `unit`s between two ticks.
    - `unit` 'ms' | 's' | 'min' | 'hour', required
  - `activationWindow` ActivationWindow, required — Optional gate applied on top of the schedule. A tick only fires when it satisfies every configured criterion; the two criteria below are combined with AND. A tick falling outside the window is skipped silently — it is never queued or deferred.
    - `dateRange` ActivationWindowDateRange — Absolute bounds of an activation window. Each side is independently optional: an absent bound means the window is open-ended on that side.
      - `start` string — Represents an instant in time as an ISO 8601 string.
      - `end` string — Represents an instant in time as an ISO 8601 string.
    - `recurring` ActivationWindowRecurring — A civil-time recurrence rule. Unlike the date range, this is not a pair of instants: "Thursday 12:00" shifts by an hour across DST transitions, so the rule carries the IANA timezone it is expressed in and is re-derived at every evaluation.
      - `timezone` string, required — Represents a timezone as an IANA timezone string.
      - `daysOfWeek` number[], nullable — Days on which the window is active, 0 = Sunday … 6 = Saturday. Absent or empty means every day.
      - `timeOfDay` ActivationWindowTimeOfDay — Local time-of-day bounds. `start` is inclusive, `end` is exclusive. When `end` is earlier than `start` the window is overnight and spans into the following day.
        - `start` string, required — Represents a local time as an ISO time string (HH:MM:SS).
        - `end` string, required — Represents a local time as an ISO time string (HH:MM:SS).

## Response `201`

Scan mode created successfully

- ScanModeDTO — Data Transfer Object for a scan mode. Represents a configured scan mode with its metadata and schedule.
  - `id` string, required — The unique identifier of the entity.
  - `createdBy` UserInfo, required — Represents the user who performed an action, with a computed display name.
    - `id` string, required — The unique identifier of the user.
    - `friendlyName` string, required — A human-readable display name for the user. "OIAnalytics" for the oianalytics system user, "Admin" for the admin login, or "Firstname Lastname (login)" for regular users.
  - `updatedBy` UserInfo, required — Represents the user who performed an action, with a computed display name.
    - `id` string, required — The unique identifier of the user.
    - `friendlyName` string, required — A human-readable display name for the user. "OIAnalytics" for the oianalytics system user, "Admin" for the admin login, or "Firstname Lastname (login)" for regular users.
  - `createdAt` string, required — Represents an instant in time as an ISO 8601 string.
  - `updatedAt` string, required — Represents an instant in time as an ISO 8601 string.
  - `name` string, required — The name of the scan mode.
  - `description` string, required — A description of the scan mode's purpose or behavior.
  - `type` 'cron' | 'interval', required — How a scan mode decides when to tick. - `cron`: driven by a cron expression (the historical behaviour). - `interval`: driven by a fixed period between ticks.
  - `cron` string, required — A cron expression defining the scan schedule. Empty when `type` is `"interval"`.
  - `interval` ScanModeInterval, required — Fixed period between two ticks of an `interval` scan mode.
    - `value` number, double, required — How many `unit`s between two ticks.
    - `unit` 'ms' | 's' | 'min' | 'hour', required
  - `activationWindow` ActivationWindow, required — Optional gate applied on top of the schedule. A tick only fires when it satisfies every configured criterion; the two criteria below are combined with AND. A tick falling outside the window is skipped silently — it is never queued or deferred.
    - `dateRange` ActivationWindowDateRange — Absolute bounds of an activation window. Each side is independently optional: an absent bound means the window is open-ended on that side.
      - `start` string — Represents an instant in time as an ISO 8601 string.
      - `end` string — Represents an instant in time as an ISO 8601 string.
    - `recurring` ActivationWindowRecurring — A civil-time recurrence rule. Unlike the date range, this is not a pair of instants: "Thursday 12:00" shifts by an hour across DST transitions, so the rule carries the IANA timezone it is expressed in and is re-derived at every evaluation.
      - `timezone` string, required — Represents a timezone as an IANA timezone string.
      - `daysOfWeek` number[], nullable — Days on which the window is active, 0 = Sunday … 6 = Saturday. Absent or empty means every day.
      - `timeOfDay` ActivationWindowTimeOfDay — Local time-of-day bounds. `start` is inclusive, `end` is exclusive. When `end` is earlier than `start` the window is overnight and spans into the following day.
        - `start` string, required — Represents a local time as an ISO time string (HH:MM:SS).
        - `end` string, required — Represents a local time as an ISO time string (HH:MM:SS).
  - `activationWindowExpired` boolean, required — Whether the activation window can never trigger again (for instance its end date is already past). Computed server-side; drives a non-blocking warning in the UI.

## Changes

- **2026-08-24** `c7fdedb4e501` — 3 breaking, 4 info
  - added the new required request property `activationWindow`
  - added the new required request property `interval`
  - added the new required request property `type`
  - added the required property `activationWindow` to the response with the `201` status
  - …3 more
- **2026-08-18** `87fa588c6b1b` — 4 breaking, 3 warning
  - removed the required property `activationWindow` from the response with the `201` status
  - removed the required property `activationWindowExpired` from the response with the `201` status
  - removed the required property `interval` from the response with the `201` status
  - removed the required property `type` from the response with the `201` status
  - …3 more
- **2026-08-03** `8ee92ea35845` — 3 breaking, 4 info
  - added the new required request property `activationWindow`
  - added the new required request property `interval`
  - added the new required request property `type`
  - added the required property `activationWindow` to the response with the `201` status
  - …3 more
- **2026-07-28** `9a6250881fa7` — 4 breaking, 3 warning
  - removed the required property `activationWindow` from the response with the `201` status
  - removed the required property `activationWindowExpired` from the response with the `201` status
  - removed the required property `interval` from the response with the `201` status
  - removed the required property `type` from the response with the `201` status
  - …3 more
- …earlier changes not shown

[Full history](https://skmtc.dev/optimistiksas/apis/oibus-api/changes/api/scan-modes/post.md)

---

[API](https://skmtc.dev/optimistiksas/apis/oibus-api.md) · [All operations](https://skmtc.dev/optimistiksas/apis/oibus-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/optimistiksas/oibus-api/revisions/08f74b792a13/schema)