Maintenance Windows

Maintenance windows allow scheduling periods during which IDIAL suppresses automated certificate operations. A maintenance window groups scheduling metadata (type, timezone, validity range, status). A maintenance rule defines the actual time spans within a window (one-time or recurring). Multiple rules can belong to one window. Deleting a window cascades to all its rules.

note

These endpoints are not present in the existing bxc-documentation. They document a feature introduced after the last bxc-documentation update.

GET /maintenance/inventory

Returns all maintenance windows (summary view).

Authentication: Required (X-API-Key header)

Request

curl -X GET http://localhost:5000/maintenance/inventory \
  -H "X-API-Key: your-api-key"

Response 200

[
  {
    "id": 1,
    "name": "Weekend Maintenance",
    "description": "Regular weekend downtime window",
    "status": "active"
  }
]

Response Fields

Field	Type	Description
id	integer	Window identifier.
name	string	Window name.
description	string | null	Optional description.
status	string	"active" or "inactive".

---

GET /maintenance/inventory/{window_id}

Returns full details for a single maintenance window, including all its rules.

Authentication: Required (X-API-Key header)

Request

curl -X GET http://localhost:5000/maintenance/inventory/1 \
  -H "X-API-Key: your-api-key"

Response 200

{
  "id": 1,
  "name": "Weekend Maintenance",
  "description": "Regular weekend downtime window",
  "status": "active",
  "window_type": "recurring",
  "timezone": "Europe/Berlin",
  "valid_from": null,
  "valid_until": null,
  "created_at": "2026-01-01T10:00:00",
  "updated_at": "2026-01-01T10:00:00",
  "rules": [
    {
      "id": 1,
      "maintenance_window_id": 1,
      "recurrence_type": "weekly",
      "day_of_week": 5,
      "start_time": "02:00",
      "end_time": "06:00",
      "interval_count": 1,
      "start_at": null,
      "end_at": null,
      "day_of_month": null,
      "rrule": null
    }
  ]
}

Response Fields

Field	Type	Description
id	integer	Window identifier.
name	string	Window name.
description	string | null	Optional description.
status	string	"active" or "inactive".
window_type	string	"one_time" or "recurring".
timezone	string	Timezone (e.g. "Europe/Berlin").
valid_from	string | null	ISO 8601 overall validity start.
valid_until	string | null	ISO 8601 overall validity end.
created_at	string	ISO 8601 creation timestamp.
updated_at	string	ISO 8601 last-updated timestamp.
rules	object[]	Array of maintenance rules (see rule schema).

Response 404

{"error": "string"}

---

POST /maintenance/inventory

Creates a new maintenance window.

Authentication: Required (X-API-Key header)

Request

curl -X POST http://localhost:5000/maintenance/inventory \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend Maintenance",
    "status": "active",
    "window_type": "recurring",
    "timezone": "Europe/Berlin"
  }'

Request Fields

Field	Type	Required	Description
name	string	Yes	Window name.
status	string	Yes	"active" or "inactive".
window_type	string	Yes	"one_time" or "recurring".
description	string	No	Optional description.
timezone	string	No	Timezone (default: "Europe/Berlin").
valid_from	string	No	ISO 8601 overall validity start.
valid_until	string	No	ISO 8601 overall validity end.

Response 201

Full window detail. Response format matches GET /maintenance/inventory/{window_id}.

---

PATCH /maintenance/inventory/{window_id}

Updates fields on an existing maintenance window. At least one field must be provided.

Authentication: Required (X-API-Key header)

Request

curl -X PATCH http://localhost:5000/maintenance/inventory/1 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

Request Fields

Same fields as POST /maintenance/inventory. All fields are optional.

Response 200

Updated window detail. Response format matches GET /maintenance/inventory/{window_id}.

Response 400

{"error": "string"}

Response 404

{"error": "string"}

---

DELETE /maintenance/inventory/{window_id}

Deletes a maintenance window and all its associated rules.

Authentication: Required (X-API-Key header)

Request

curl -X DELETE http://localhost:5000/maintenance/inventory/1 \
  -H "X-API-Key: your-api-key"

Response 200

Deleted window detail. Response format matches GET /maintenance/inventory/{window_id}.

Response 404

{"error": "string"}

---

GET /maintenance/rule

Returns all maintenance rules across all windows.

Authentication: Required (X-API-Key header)

Request

curl -X GET http://localhost:5000/maintenance/rule \
  -H "X-API-Key: your-api-key"

Response 200

Array of rule objects. See Maintenance Rule Schema.

---

POST /maintenance/rule

Creates a new maintenance rule and associates it with a window.

Authentication: Required (X-API-Key header)

Request

curl -X POST http://localhost:5000/maintenance/rule \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "maintenance_window_id": 1,
    "recurrence_type": "weekly",
    "day_of_week": 5,
    "start_time": "02:00",
    "end_time": "06:00"
  }'

Request Fields

Field	Type	Required	Description
maintenance_window_id	integer	Yes	ID of the parent window.
start_at	string	No	ISO 8601 one-time start datetime.
end_at	string	No	ISO 8601 one-time end datetime.
recurrence_type	string	No	"weekly", "monthly", "daily", "cron", or "rrule".
day_of_week	integer (0–6)	No	Day of week for weekly recurrence (0=Monday).
day_of_month	integer (1–31)	No	Day of month for monthly recurrence.
start_time	string	No	Time of day for recurrence start (e.g. "02:00").
end_time	string	No	Time of day for recurrence end.
interval_count	integer ≥ 1	No	Interval count for recurring rules.
rrule	string	No	RFC 5545 RRULE string (for recurrence_type: "rrule").

Response 201

Created rule object. See Maintenance Rule Schema.

---

PATCH /maintenance/rule/{rule_id}

Updates fields on a maintenance rule. At least one field must be provided.

Authentication: Required (X-API-Key header)

Request

curl -X PATCH http://localhost:5000/maintenance/rule/1 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"start_time": "03:00", "end_time": "07:00"}'

Request Fields

Same fields as POST /maintenance/rule except maintenance_window_id. All fields are optional.

Response 200

Updated rule object. See Maintenance Rule Schema.

Response 400

{"error": "string"}

Response 404

{"error": "string"}

---

DELETE /maintenance/rule/{rule_id}

Deletes a maintenance rule.

Authentication: Required (X-API-Key header)

Request

curl -X DELETE http://localhost:5000/maintenance/rule/1 \
  -H "X-API-Key: your-api-key"

Response 200

Deleted rule object. See Maintenance Rule Schema.

Response 404

{"error": "string"}

---

POST /maintenance/test/{window_id}

Tests whether a given datetime falls inside any rule of the specified maintenance window.

Authentication: Required (X-API-Key header)

Request

curl -X POST http://localhost:5000/maintenance/test/1 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"at": "2026-05-09T03:00:00"}'

Request Fields

Field	Type	Required	Description
at	string	Yes	ISO 8601 datetime to test (e.g. "2026-05-09T03:00:00").

Response 200

{
  "window_id": 1,
  "at": "2026-05-09T03:00:00",
  "inside": true,
  "matched_rule_id": 1,
  "reason": "Matches weekly rule on Saturday between 02:00 and 06:00"
}

Response Fields

Field	Type	Description
window_id	integer	The window that was tested.
at	string	The datetime that was tested.
inside	boolean	Whether the datetime falls inside the window.
matched_rule_id	integer | null	ID of the first matching rule, if any.
reason	string | null	Human-readable explanation.

Response 400

Returned when at is not a valid ISO 8601 datetime.

Response 404

{"error": "string"}

---

Maintenance Rule Schema

Field	Type	Description
id	integer	Rule identifier.
maintenance_window_id	integer	Parent window ID.
start_at	string | null	One-time start datetime (ISO 8601).
end_at	string | null	One-time end datetime (ISO 8601).
recurrence_type	string | null	"weekly", "monthly", "daily", "cron", or "rrule".
day_of_week	integer | null	Day of week (0–6, 0=Monday).
day_of_month	integer | null	Day of month (1–31).
start_time	string | null	Daily start time (e.g. "02:00").
end_time	string | null	Daily end time.
interval_count	integer | null	Interval count for recurring rules.
rrule	string | null	RFC 5545 RRULE string.