Skip to content
adversarial

Commit a reviewed set of AI-parsed risks: create them all, tag the batch with the engagement/report name, and attach the document they were parsed from, so each risk can be traced back to its source.

POST
/v1/risks/import/ai/commit
curl --request POST \
  --url https://api.adversarial.com/api/v1/risks/import/ai/commit \
  --header 'Content-Type: application/json' \
  --data '{ "risks": [], "source_file_id": null, "tags": [] }'

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Request body for the AI import commit step: the (possibly edited) set of risks the reviewer accepted, plus any tags to apply to the whole batch.

object
risks

The finalized risks to create.

Array<object>
default:

A single risk the AI extracted from an uploaded narrative document.

The same shape is returned by the preview call and accepted back on commit, so it carries every field a reviewer may edit before import.

object
description
required

Full narrative description of the risk, grounded in the source document.

string
discovered_date

When the risk was discovered, as a plain YYYY-MM-DD calendar date, taken from the document — normally its report date, or a date the document ties specifically to the activity that surfaced this finding.

A bare date string rather than a timestamp on purpose: it is what the model can reliably lift out of a narrative, and what the CSV import template already uses. None (or anything unparseable) means the document carried no usable date, and the risk falls back to the creation time on import.

string | null
initially_reported_urgency
required

Initially reported urgency (IRU) inferred from how the source framed the finding.

string
Allowed values: Critical High Medium Low Info
rationale
required

One- or two-sentence justification tying the proposal back to the source document.

string
source
required

Suggested intake source (how the risk was identified), chosen from the organization’s configured risk_source list — usually the same for every finding in a document.

Reduced server-side to a configured name, or to "" when the model returned something that is not one. Empty means “the AI did not pick a source”, which the reviewer resolves in the preview; it must not be quietly swapped for a default, because an intake nobody chose is indistinguishable from one somebody did.

string
source_excerpt
required

A short span copied verbatim from the source document that this risk was drawn from. The client substring-matches it against document_text to scroll to and highlight the originating passage.

string
title
required

Concise risk title.

string
type
required

Best-fit risk category, presented as the risk’s class.

string
Allowed values: Code Configuration Control Deficiency Policy Procedural Vulnerability Third-party
source_file_id

The source_file_id the parse step returned. The document is attached to every created risk, recording where the batch came from. Optional.

string | null format: uuid
tags

Tags (by content) to apply to every imported risk — e.g. the engagement or report name — so the whole batch can be traced back to its source. Each is created if it doesn’t already exist. Optional.

Array<string>
default:

Responses

Section titled “Responses”

201

Section titled “201”

Risks created and tagged

Media typeapplication/json

Response from the AI import commit step.

object
risks
required

The created risks as register rows, in the order they were imported.

Returned so the client can drop them straight into its cached register views — the same thing the single-risk create endpoint enables — and the reviewer sees the batch land immediately, even under a filter the new rows don’t satisfy.

Each carries the source document among its attachments when it was attached. It is not when no source_file_id was sent, or when that id no longer names a document you uploaded for import, such as one already discarded or claimed; the risks are imported either way.

Array<object>

Register row for Organization Risks (RSKs). A Risk plus the relational data shown on the risk register: threat objectives, incident associations, tags, and comment count.

object
attachments
required

Files attached to this risk, newest-first.

Array<object>

A file attached to a risk, an incident, or a comment on either.

Embedded in the attachments list of the record it is attached to, and returned when a file is uploaded to a risk or incident.

object
byte_size

File size in bytes.

integer | null format: int64
content_type
required

MIME content type.

string
created_by

The user who uploaded the file, if known. On a comment’s attachments this can differ from the comment’s author: a comment may reference a file someone else uploaded to the same record.

string | null format: uuid
created_date
required

When the file was uploaded.

string format: date-time
id
required

The attachment’s id; download it with GET /v1/files/{id}.

string format: uuid
name
required

Original file name as uploaded.

string
status
required

The file’s upload status. Attachments are only listed once their upload has finished, so this is always ready.

string
Allowed values: pending ready failed
comments
required

Count of comments on this risk (not the comments themselves).

integer format: int64
incident_associations
required
Array<string>
linked_children_count
required

Number of risks linked under this risk (i.e. children pointing at it). A risk is itself a linked child when risk.parent_id is set.

integer format: int64
risk
required

The core view of an Organization Risk (RSK).

Relational data — threat objectives, comments, incident associations, and tags — is exposed on RiskRegisterEntry, not here.

object
assigned_to
One of:

A User as returned by the API.

Profile images are not embedded — clients fetch them from GET /api/v1/{icon} when icon is Some.

object
email
required
string
first_name
required
string
icon

Relative path to the user’s avatar endpoint, e.g. "users/{id}/avatar?v={hash}". None when the user has no avatar.

string | null
id
required
string format: uuid
last_name
required
string
closed_date
string | null format: date-time
control_statement
string | null
created_date
required
string format: date-time
deleted_date
string | null format: date-time
description
required
string
discovered_date
required
string format: date-time
due_date
string | null format: date-time
expected_date
string | null format: date-time
id
required
string
impact
One of:
string
Allowed values: Very Low Low Medium High Severe
impact_reasoning
string | null
initially_reported_urgency
One of:
string
Allowed values: Critical High Medium Low Info
likelihood
One of:
string
Allowed values: Remote Unlikely Possible Probable Imminent
likelihood_reasoning
string | null
opened_by
required

A User as returned by the API.

Profile images are not embedded — clients fetch them from GET /api/v1/{icon} when icon is Some.

object
email
required
string
first_name
required
string
icon

Relative path to the user’s avatar endpoint, e.g. "users/{id}/avatar?v={hash}". None when the user has no avatar.

string | null
id
required
string format: uuid
last_name
required
string
parent_id

When set, this risk is linked under the named parent risk.

string | null
remediation_task
string | null
source
string | null
status
required

The status of a risk

string
Allowed values: New Urgency Proposed Remediation Closure Proposed Closed
title
required
string
type
required
string
Allowed values: Code Configuration Control Deficiency Policy Procedural Vulnerability Third-party
updated_by
required

A User as returned by the API.

Profile images are not embedded — clients fetch them from GET /api/v1/{icon} when icon is Some.

object
email
required
string
first_name
required
string
icon

Relative path to the user’s avatar endpoint, e.g. "users/{id}/avatar?v={hash}". None when the user has no avatar.

string | null
id
required
string format: uuid
last_name
required
string
updated_date
required
string format: date-time
urgency
One of:

Derived from likelihood and impact. Null when either is missing.

string
Allowed values: Info Low Medium High Critical
tags
required
Array<object>
object
content
required
string
creator_id
required
string format: uuid
id
required
string format: uuid
org_id
string | null format: uuid
threat_objectives
required
Array<object>

A threat objective paired with how relevant it is to a risk.

Two relations are considered the same when the objective and its relevance match; created_date records when the relation was last changed and is not part of its identity.

object
created_date

The time that this relation was mutated

string | null format: date-time
relevance
One of:

How relevant the threat objective is. Responses always carry a relevance. In a request, null removes the objective.

string
Allowed values: Moderate Substantial
threat_objective
required

The threat objective type

string
Allowed values: Sabotage Data Disclosure Extortion Customer Targeting Resource Hijacking Fraud
risks_imported
required

Number of risks created.

integer format: int64
tags
required

The tags applied to the imported batch.

Array<string>
Example
{
  "risks": [
    {
      "attachments": [
        {
          "status": "pending"
        }
      ],
      "incident_associations": "INC-00001",
      "risk": {
        "id": "RSK-00001",
        "impact": "Very Low",
        "initially_reported_urgency": "Critical",
        "likelihood": "Remote",
        "parent_id": "RSK-00001",
        "status": "New",
        "type": "Code",
        "urgency": "Info"
      },
      "threat_objectives": [
        {
          "relevance": "Moderate",
          "threat_objective": "Sabotage"
        }
      ]
    }
  ]
}

400

Section titled “400”

No risks to import, too many, or a source that is not one of the organization’s risk sources

403

Section titled “403”

Tags were requested without tags:write