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, including the automatic plan scan.

GET /tenants/me/scheduled-scans

Example Request

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

Example Response

{
  "success": true,
  "data": [
    {
      "id": "plan",
      "isPlanSchedule": true,
      "name": "Automatic plan scan",
      "frequency": "weekly",
      "hour": 0,
      "minute": 0,
      "dayOfWeek": 0,
      "dayOfMonth": 1,
      "timezone": "UTC",
      "enabled": true,
      "scanType": "compliance",
      "lastTriggeredAt": "2026-04-07T00:00:00Z"
    },
    {
      "id": "sched_abc123",
      "isPlanSchedule": false,
      "name": "Weekly exposure scan",
      "frequency": "weekly",
      "hour": 6,
      "minute": 0,
      "dayOfWeek": 3,
      "dayOfMonth": null,
      "timezone": "Europe/London",
      "enabled": true,
      "scanType": "exposure",
      "lastTriggeredAt": "2026-04-09T06:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Schedule identifier ("plan" for the automatic plan schedule)
isPlanSchedule	boolean	true if this is the automatic plan scan
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–31)
timezone	string	IANA timezone string
enabled	boolean	Whether the schedule is active
scanType	string	compliance or exposure
lastTriggeredAt	string or null	ISO 8601 timestamp of last trigger

---

Create Scheduled Scan

Creates a new scheduled scan.

POST /tenants/me/scheduled-scans

Request Body

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

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

Example Request

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

Errors

Code	HTTP	Description
SCAN_PLAN_LIMIT_REACHED	429	Custom schedule limit reached for your plan
VALIDATION_ERROR	400	Missing or invalid fields

---

Update Scheduled Scan

Updates an existing scheduled scan. Only the fields you include are updated.

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

Example: Pause a schedule

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

Example: Change the hour

curl -X PATCH https://api.aether365.io/tenants/me/scheduled-scans/sched_abc123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"hour": 8}'

---

Delete Scheduled Scan

Permanently deletes a scheduled scan and its underlying schedule.

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

WARNING

The automatic plan scan (id: "plan") cannot be deleted via the API.

Example Request

curl -X DELETE https://api.aether365.io/tenants/me/scheduled-scans/sched_abc123 \
  -H "Authorization: Bearer <token>"

Example Response

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