Assessment API

Assessment API

Authorize scan scope, start and cancel runs, review coverage, and verify findings.

Assessment mutations require Administrator authority over the approved target set. Credential references are write-only secrets managed through the credential workflow.

Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.

Create a scope

POST/organizations/{organization_id}/assessment-scopes
Scope
assessments:write
Auth
Bearer API key

Creates an authorized assessment boundary. An ownership or authorization check failure rejects admission.

Request body
namestringrequired

Display name; does not change resource identity.

rule1–120 characters
asset_idsstring[]required

Existing assets visible to the caller; duplicates reject the request.

rule1–200 unique IDs
allowed_cidrsstring[]required

Explicit permitted scan networks; addresses outside them are excluded.

excluded_cidrsstring[]optional

Additional networks never scanned.

default[]
authorization_referencestringrequired

Approved owner authorization reference.

201Created

Returns scope ID, revision, authorized targets, and ETag.

Start a scan

POST/organizations/{organization_id}/scan-runs
Scope
assessments:write
Auth
Bearer API key

Starts a scan pinned to the approved scope revision and profile. Invalid credentials do not silently establish authenticated coverage.

Request body
scope_idstringrequired

Approved assessment scope.

scope_revisionintegerrequired

Reviewed scope revision.

ruleAt least 1
scanner_idstringrequired

Enrolled scanner allowed for this scope.

profile_idstringrequired

Installed scan profile including intensity and fallback behavior.

credential_idstringoptional

Optional credential permitted for these targets; omission runs unauthenticated.

202Accepted

The response is similar to the following:

JSON
{
  "data": {
    "id": "scan_001",
    "state": "queued",
    "scope_id": "scp_001",
    "scope_revision": 2
  },
  "operation": {
    "id": "op_scan01",
    "state": "queued"
  },
  "request_id": "req_scan01"
}

List scan runs

GET/organizations/{organization_id}/scan-runs
Scope
assessments:read
Auth
Bearer API key

Returns run, scope revision, scanner, credential version when used, and target coverage counts. Standard limit and cursor apply. Unknown filters return 422.

Query parameters
scope_idstringoptional

Filter approved scope.

statestringoptional

Execution state.

one ofqueued, running, succeeded, failed, canceled
200Result

Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.

Read a scan run

GET/organizations/{organization_id}/scan-runs/{scan_id}
Scope
assessments:read
Auth
Bearer API key

Returns per-target reachability, authenticated access level, completed and skipped checks, errors, and finding references. Unreachable targets remain not_assessed.

200Result

Returns data and request_id.

Cancel a scan

POST/organizations/{organization_id}/scan-runs/{scan_id}/cancel
Scope
assessments:write
Auth
Bearer API key

Cancels future and cancelable scan checks. Send an empty object; already sent network requests and collected observations remain.

202Accepted

Returns run data and its canceling operation. Poll until the terminal scan state is observed.

List findings

GET/organizations/{organization_id}/findings
Scope
assessments:read
Auth
Bearer API key

Returns technical severity, affected component, authentication basis, first/last seen, owner, and risk context. Standard limit and cursor apply. Unknown filters return 422.

Query parameters
asset_idstringoptional

Filter affected asset.

cvestringoptional

Exact CVE identifier.

statestringoptional

Remediation state.

one ofopen, in_progress, pending_verification, resolved, accepted_risk, false_positive
200Result

Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.

Review a finding

PATCH/organizations/{organization_id}/findings/{finding_id}
Scope
assessments:write
Auth
Bearer API key

Updates a finding's review state or owner. Requires If-Match; risk acceptance requires its separate grant. Directly setting resolved is not permitted.

Request body
statestringoptional

Requested review state.

one ofopen, in_progress, accepted_risk, false_positive
owner_idstringoptional

Responsible organization member.

expires_attimestampoptional

Required future expiry for accepted risk; forbidden for false-positive disposition.

reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
200Result

Returns updated finding and ETag. Original detector evidence is preserved.

Verify remediation

POST/organizations/{organization_id}/findings/{finding_id}/verify
Scope
assessments:write
Auth
Bearer API key

Starts a verification scan using an authorized matching check and sufficient authentication coverage. Requires If-Match.

Request body
scope_idstringrequired

Approved scope containing the affected asset.

scanner_idstringrequired

Authorized scanner.

profile_idstringrequired

Profile containing the affected check.

credential_idstringoptional

Required when verification needs authenticated coverage.

202Accepted

Returns finding in pending verification and an operation. Failed coverage leaves the finding unresolved.