Skip to content

Scan Comparison, Exports and Bulk Schedules

Compare two runs of an application, export a scan’s findings as CSV, PDF or SARIF, and schedule many applications at once. Base URL: https://api.nightviz.ai/api/v1/. See the API overview for authentication.

GET /scans/{id}/compare/

Shows what changed between this run and an earlier run of the same application: findings fixed, new, still open and not retested. Needs permission to view scans and findings.

Query parameter: against, the id of the earlier run to compare with. Default: the run before this one.

Terminal window
curl -H "Authorization: Token $NIGHTVISION_TOKEN" \
https://api.nightviz.ai/api/v1/scans/00000000-0000-4000-8000-000000000060/compare/
{
"scan": {
"id": "00000000-0000-4000-8000-000000000060",
"ended_at": "2026-03-01T08:00:00Z",
"session": "signed_in"
},
"against": {
"id": "00000000-0000-4000-8000-000000000061",
"ended_at": "2026-02-22T08:00:00Z",
"session": "signed_in"
},
"counts": {"fixed": 1, "new": 1, "still_open": 0, "not_retested": 0},
"fixed": [],
"new": [
{
"kind_id": 101,
"nuclei_template_id": null,
"name": "SQL Injection",
"severity": "HIGH",
"url_path": "/api/orders",
"http_method": "GET",
"parameter_name": "id",
"issue_id": "00000000-0000-4000-8000-000000000050",
"scan_id": "00000000-0000-4000-8000-000000000060",
"reason": null,
"retest": null
}
],
"still_open": [],
"not_retested": [],
"truncated": false
}

session is signed_in, anonymous, login_failed or unverified. Each of fixed, new, still_open and not_retested is a list of rows in the shape shown. For rows in not_retested, reason says why the finding was not retested (for example signed_out, endpoint_not_requested or check_not_run). truncated is true when a list was cut short; counts still shows the totals.

Exports run as background jobs. Start one, then poll until it finishes. Both calls need permission to view scans, and exports are visible only to the user who requested them.

POST /scans/{id}/exports/

Request body:

  • type (required): csv, pdf or sarif.
  • email: true to also email the file to you. Default false; nothing is emailed unless it is true.

Returns 202 with the job straight away. The scan must have ended (otherwise 400). A user can have 3 exports in progress at once; further requests return 429.

Terminal window
curl -X POST -H "Authorization: Token $NIGHTVISION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type": "sarif"}' \
https://api.nightviz.ai/api/v1/scans/00000000-0000-4000-8000-000000000060/exports/
{
"id": "00000000-0000-4000-8000-000000000070",
"type": "sarif",
"status": "queued",
"error": null,
"download_url": null,
"email_requested": false,
"created_at": "2026-03-02T10:00:00Z",
"finished_at": null
}

GET /scans/{id}/exports/{export_id}/

Returns the job. Poll until status is succeeded (use download_url) or failed (read error). status moves through queued, running, then one of those two.

Terminal window
curl -H "Authorization: Token $NIGHTVISION_TOKEN" \
https://api.nightviz.ai/api/v1/scans/00000000-0000-4000-8000-000000000060/exports/00000000-0000-4000-8000-000000000070/
{
"id": "00000000-0000-4000-8000-000000000070",
"type": "sarif",
"status": "succeeded",
"error": null,
"download_url": "https://example.com/download/findings.sarif",
"email_requested": false,
"created_at": "2026-03-02T10:00:00Z",
"finished_at": "2026-03-02T10:00:05Z"
}

download_url is shown here as a placeholder; use the URL the API returns.

GET /scans/{id}/exports/

Returns a JSON array of your last 10 exports of this scan, newest first, each in the shape above.

POST /schedules/bulk/

Schedules up to 50 applications with one cadence. Each application repeats its latest completed security scan. Needs permission to add scans in each application’s project; applications you cannot schedule are skipped, not failed.

Request body:

  • target_ids (required): application ids, at most 50.
  • period: daily, weekly, biweekly, monthly or quarterly.
  • scheduled_time: time of day, for example 09:00:00. Required for every period.
  • scheduled_week_day: 1 (Monday) to 7 (Sunday). Required for weekly and biweekly.
  • scheduled_month_date: day of the month. Required for monthly and quarterly.
  • timezone: an IANA timezone name such as UTC or America/New_York.

The same rules apply as when you create a single schedule, so a bulk request is valid exactly when a single create would be.

Terminal window
curl -X POST -H "Authorization: Token $NIGHTVISION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"target_ids": [
"00000000-0000-4000-8000-000000000010",
"00000000-0000-4000-8000-000000000011"
],
"period": "weekly",
"scheduled_week_day": 1,
"scheduled_time": "02:00:00",
"timezone": "UTC"
}' \
https://api.nightviz.ai/api/v1/schedules/bulk/
{
"results": [
{
"target_id": "00000000-0000-4000-8000-000000000010",
"status": "created",
"schedule_id": "00000000-0000-4000-8000-000000000080",
"reason": null
},
{
"target_id": "00000000-0000-4000-8000-000000000011",
"status": "skipped",
"reason": "already_scheduled"
}
]
}

There is one row per distinct application. status is created, skipped or failed. A row that was not created has a reason:

  • no_completed_scan (skipped): the application never completed a scan.
  • already_scheduled (skipped): it already has an enabled schedule.
  • schedule_paused (skipped): it has a paused schedule; turn that on instead.
  • private (skipped): the application is not reachable from the internet.
  • no_permission (skipped): you cannot add scans to its project.
  • subscription_required (skipped): the organization needs a paid plan to schedule scans.
  • credentials_from_other_project (skipped): the latest run signs in with an authentication from a project the application was in before it moved. Run a new scan first.
  • invalid_schedule (failed): the schedule was rejected for this application.
  • error (failed): the schedule could not be set up.

GET /common/scan-policy/

Reports whether scan policies (scan intensity and request limits) take effect for your deployment. When enabled is false, a stored scan_policy on a target is accepted but scans run with the standard policy.

Terminal window
curl -H "Authorization: Token $NIGHTVISION_TOKEN" \
https://api.nightviz.ai/api/v1/common/scan-policy/
{
"enabled": true
}