Schedules

Set up recurring automated scans (Business+ tier)

POST/v1/schedules

Create a schedule

Create a recurring scan schedule for a verified target. Scheduled scans run automatically at the specified frequency and time. Requires Business tier or above. Each scheduled run deducts credits from your quota; enable `allowPayg` to continue scanning via pay-as-you-go when plan credits are exhausted.

Requires Business tier or above. Returns 403 if your subscription does not include scheduled scans. All times are in UTC.

Request Body

Name	Type	Description
`targetId`required	`string`	ID of the verified target to schedule scans for
`frequency`required	`string` dailyweeklybiweeklymonthly	How often to run the scan
`hour`required	`number`	Hour of day to run (0-23, UTC)
`minute`	`number`	Minute of hour to run (0-59, UTC). Defaults to 0
`dayOfWeek`	`number`	Day of week for weekly/biweekly schedules (0 = Sunday, 6 = Saturday)
`dayOfMonth`	`number`	Day of month for monthly schedules (1-28). Values above 28 are not supported to avoid month-length issues
`modelPreset`	`string` freelowmediumhighultra	AI model quality preset for scheduled scans
`allowPayg`	`boolean`	Allow pay-as-you-go billing when plan credits are exhausted. Defaults to false

Example Request

bash

curl -X POST "https://apviso.com/api/v1/v1/schedules" \
  -H "X-API-Key: apvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "frequency": "weekly",
  "hour": 3,
  "minute": 0,
  "dayOfWeek": 1,
  "modelPreset": "medium",
  "allowPayg": false
}'

Response

Returns the newly created schedule with the computed next run time. The schedule is enabled by default.

json

{
  "id": "019414d5-e6f7-7a8b-c9d0-1e2f3a4b5c6d",
  "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "target": {
    "domain": "example.com"
  },
  "frequency": "weekly",
  "hour": 3,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "medium",
  "allowPayg": false,
  "enabled": true,
  "nextRunAt": "2026-04-14T03:00:00Z",
  "lastRunAt": null,
  "lastScanId": null,
  "createdAt": "2026-04-10T16:00:12Z",
  "updatedAt": "2026-04-10T16:00:12Z"
}

GET/v1/schedules

List schedules

Retrieve all scan schedules configured for your account. Returns both enabled and disabled schedules.

Example Request

bash

curl -X GET "https://apviso.com/api/v1/v1/schedules" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns the list of all schedules with their configuration, next run time, and last execution details.

json

{
  "data": [
    {
      "id": "019414d5-e6f7-7a8b-c9d0-1e2f3a4b5c6d",
      "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
      "target": {
        "domain": "example.com"
      },
      "frequency": "weekly",
      "hour": 3,
      "minute": 0,
      "dayOfWeek": 1,
      "modelPreset": "medium",
      "enabled": true,
      "nextRunAt": "2026-04-14T03:00:00Z",
      "lastRunAt": "2026-04-07T03:00:00Z",
      "lastScanId": "019414b0-c1d2-7e3f-a4b5-6c7d8e9f0a1b",
      "createdAt": "2026-03-15T10:30:00Z",
      "updatedAt": "2026-04-07T03:00:00Z"
    }
  ]
}

GET/v1/schedules/:id

Get schedule details

Retrieve detailed information about a specific scan schedule, including its execution history summary.

Path Parameters

Name	Type	Description
`id`required	`string`	Schedule ID (UUIDv7)

Example Request

bash

curl -X GET "https://apviso.com/api/v1/v1/schedules/:id" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns the full schedule details including run history statistics. `skippedRuns` counts executions that were skipped due to insufficient credits when `allowPayg` is false.

json

{
  "id": "019414d5-e6f7-7a8b-c9d0-1e2f3a4b5c6d",
  "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "target": {
    "domain": "example.com"
  },
  "frequency": "weekly",
  "hour": 3,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "medium",
  "allowPayg": false,
  "enabled": true,
  "nextRunAt": "2026-04-14T03:00:00Z",
  "lastRunAt": "2026-04-07T03:00:00Z",
  "lastScanId": "019414b0-c1d2-7e3f-a4b5-6c7d8e9f0a1b",
  "totalRuns": 4,
  "successfulRuns": 4,
  "failedRuns": 0,
  "skippedRuns": 0,
  "createdAt": "2026-03-15T10:30:00Z",
  "updatedAt": "2026-04-07T03:00:00Z"
}

PATCH/v1/schedules/:id

Update a schedule

Update the configuration of an existing scan schedule. You can modify the frequency, timing, model preset, pay-as-you-go setting, or enable/disable the schedule. Only provided fields are updated.

Path Parameters

Name	Type	Description
`id`required	`string`	Schedule ID (UUIDv7)

Request Body

Name	Type	Description
`frequency`	`string` dailyweeklybiweeklymonthly	Updated frequency
`hour`	`number`	Updated hour (0-23, UTC)
`minute`	`number`	Updated minute (0-59)
`dayOfWeek`	`number`	Updated day of week (0-6)
`dayOfMonth`	`number`	Updated day of month (1-28)
`modelPreset`	`string` freelowmediumhighultra	Updated model preset
`allowPayg`	`boolean`	Updated pay-as-you-go setting
`enabled`	`boolean`	Enable or disable the schedule

Example Request

bash

curl -X PATCH "https://apviso.com/api/v1/v1/schedules/:id" \
  -H "X-API-Key: apvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "frequency": "biweekly",
  "modelPreset": "high",
  "enabled": true
}'

Response

Returns the full updated schedule object with the recomputed next run time.

json

{
  "id": "019414d5-e6f7-7a8b-c9d0-1e2f3a4b5c6d",
  "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "target": {
    "domain": "example.com"
  },
  "frequency": "biweekly",
  "hour": 3,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "high",
  "allowPayg": false,
  "enabled": true,
  "nextRunAt": "2026-04-21T03:00:00Z",
  "lastRunAt": "2026-04-07T03:00:00Z",
  "lastScanId": "019414b0-c1d2-7e3f-a4b5-6c7d8e9f0a1b",
  "createdAt": "2026-03-15T10:30:00Z",
  "updatedAt": "2026-04-10T16:15:44Z"
}

DELETE/v1/schedules/:id

Delete a schedule

Permanently delete a scan schedule. Any currently running scan initiated by this schedule will continue to completion, but no future scans will be triggered.

Path Parameters

Name	Type	Description
`id`required	`string`	Schedule ID (UUIDv7)

Example Request

bash

curl -X DELETE "https://apviso.com/api/v1/v1/schedules/:id" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns a confirmation message. In-progress scans triggered by this schedule are not affected.

json

{
  "message": "Schedule deleted successfully"
}

Back to API Reference