Scheduled Scans API

Maintained by: Aether365 Team Audience: Developers Scope: Scheduled scan API endpoints - creating and managing scan schedules

Scheduled scans define recurring scan jobs. Each scheduled scan defines a recurring trigger that fires at the configured interval.

List Scheduled Scans

Returns all scheduled scans for the authenticated tenant: your stored custom schedules plus, for each scan type without a custom schedule, an automatic plan schedule derived from your plan.

GET /tenants/me/scheduled-scans

Example Request

curl https://api.aether365.io/tenants/me/scheduled-scans \
  -H "Authorization: Bearer ak_live_..."

Example Response

{
  "success": true,
  "data": [
    {
      "id": "plan-compliance",
      "isPlanSchedule": true,
      "name": "Automatic compliance scan",
      "frequency": "weekly",
      "hour": 0,
      "minute": 0,
      "dayOfWeek": 0,
      "dayOfMonth": 1,
      "timezone": "UTC",
      "enabled": true,
      "scanType": "compliance",
      "lastTriggeredAt": "2026-04-07T00:00:00+00:00",
      "createdAt": "2026-01-15T10:05:00+00:00"
    },
    {
      "id": "5e4d3c2b-1a09-4f8e-b7c6-d5e4f3a2b1c0",
      "name": "Custom compliance scan",
      "frequency": "weekly",
      "hour": 6,
      "minute": 0,
      "dayOfWeek": 3,
      "dayOfMonth": null,
      "timezone": "Europe/London",
      "enabled": true,
      "scanType": "compliance",
      "lastTriggeredAt": "2026-04-09T06:00:00+00:00",
      "createdAt": "2026-03-01T08:00:00+00:00",
      "updatedAt": "2026-03-01T08:00:00+00:00"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Schedule identifier: a UUID for custom schedules, plan-compliance for plan schedules
isPlanSchedule	boolean	Present (as true) only on automatic plan schedule rows
name	string	Display name
frequency	string	daily, weekly, or monthly
hour	integer	Hour of day to trigger (0-23)
minute	integer	Minute of hour to trigger (0-59)
dayOfWeek	integer	Day of week for weekly schedules (0=Mon, 6=Sun)
dayOfMonth	integer	Day of month for monthly schedules (1-28)
timezone	string	IANA timezone string
enabled	boolean	Whether the schedule is active
scanType	string	compliance
lastTriggeredAt	string or null	ISO 8601 timestamp of last trigger
createdAt / updatedAt	string or null	ISO 8601 timestamps (updatedAt on custom schedules only)

---

Create Scheduled Scan

Creates a new scheduled scan.

POST /tenants/me/scheduled-scans

Request Body

{
  "name": "Custom compliance scan",
  "frequency": "monthly",
  "hour": 3,
  "minute": 0,
  "dayOfMonth": 1,
  "timezone": "UTC",
  "scanType": "compliance",
  "enabled": true
}

Field	Type	Required	Description
name	string	Yes	Display name (1-200 characters)
frequency	string	Yes	daily, weekly, or monthly
hour	integer	No	0-23, defaults to 0
minute	integer	No	0-59, defaults to 0
dayOfWeek	integer	For weekly	0=Mon, 6=Sun
dayOfMonth	integer	For monthly	1-28
timezone	string	No	IANA timezone (e.g., UTC, Europe/Berlin), defaults UTC
scanType	string	No	compliance
enabled	boolean	No	Defaults to true

Returns 201 with the created schedule.

Example Request

curl -X POST https://api.aether365.io/tenants/me/scheduled-scans \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom compliance scan",
    "frequency": "monthly",
    "hour": 3,
    "minute": 0,
    "dayOfMonth": 1,
    "timezone": "UTC",
    "scanType": "compliance",
    "enabled": true
  }'

Errors

Code	HTTP	Description
SCAN_PLAN_LIMIT_REACHED	403	Custom schedules require a paid plan
SCAN_PLAN_LIMIT_REACHED	429	Custom schedule limit reached for your plan
TENANT_NOT_CONNECTED	400	Microsoft consent has not been completed
VALIDATION_ERROR	400	Missing or invalid fields

---

Update Scheduled Scan

Updates a scheduled scan.

PATCH /tenants/me/scheduled-scans/{scheduledScanId}

Custom schedules are replaced, not patched: send the complete schedule body (same fields and requirements as create - name and frequency are mandatory). Omitted optional fields fall back to their defaults.

Plan schedules (plan-compliance) accept only { "enabled": true|false } and respond with { "enabled": ... }; all other fields are ignored.

Example: Pause the automatic compliance scan

curl -X PATCH https://api.aether365.io/tenants/me/scheduled-scans/plan-compliance \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Example: Change a custom schedule's hour (full body required)

curl -X PATCH https://api.aether365.io/tenants/me/scheduled-scans/5e4d3c2b-1a09-4f8e-b7c6-d5e4f3a2b1c0 \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom compliance scan",
    "frequency": "weekly",
    "dayOfWeek": 3,
    "hour": 8,
    "minute": 0,
    "timezone": "Europe/London",
    "scanType": "compliance",
    "enabled": true
  }'

---

Delete Scheduled Scan

Permanently deletes a scheduled scan and its underlying schedule.

DELETE /tenants/me/scheduled-scans/{scheduledScanId}

WARNING

The automatic plan schedule (plan-compliance) cannot be deleted - deleting it returns 404 NOT_FOUND. Disable it via PATCH with { "enabled": false } instead.

Example Request

curl -X DELETE https://api.aether365.io/tenants/me/scheduled-scans/5e4d3c2b-1a09-4f8e-b7c6-d5e4f3a2b1c0 \
  -H "Authorization: Bearer ak_live_..."

Example Response

{
  "success": true,
  "data": null
}