Skip to content
adversarial

Generate a report deck

POST
/v1/documents/report
curl --request POST \
  --url https://api.adversarial.com/api/v1/documents/report \
  --header 'Content-Type: application/json' \
  --data '{ "end": "2026-04-15T12:00:00Z", "incidents": { "include_children": true, "include_table": true, "severities": [ "SEV-5" ] }, "risks": { "include_children": true, "include_table": true, "urgencies": [ "Info" ] }, "start": "2026-04-15T12:00:00Z", "tags": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "title": "example" }'

Enqueues a PowerPoint deck describing the organization’s risk and incident registers over the requested reporting period, and returns immediately. The artifact is reserved in the files list as pending before this responds, so generation is observable through GET /v1/files alone — there is no separate job-status surface to poll.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

How to build a report.

Report-wide settings — title, window, tag scope — are top level; each register’s band selection and table toggles are nested under risks and incidents. Omitting either register’s settings admits Critical and High risks, SEV-1 to SEV-3 incidents, and appends both register tables.

object
end
required

End of the reporting period.

string format: date-time
incidents

Incident-register settings.

object
include_children

Count incidents linked under a parent incident. Independent of the risk setting so one register can expand without the other.

boolean
include_table

Append the paginated incident-register table slides.

boolean
default: true
severities

Severities the report admits — an explicit set, not a threshold, so a report can describe one band on its own. Order and duplicates don’t matter. Must name at least one severity.

Array<string>
Allowed values: SEV-5 SEV-4 SEV-3 SEV-2 SEV-1
risks

Risk-register settings.

object
include_children

Count risks linked under a parent risk. Off by default: a report represents each cluster by its parent, and counting both double-counts it.

boolean
include_table

Append the paginated risk-register table slides.

boolean
default: true
urgencies

Urgencies the report admits — an explicit set, not a threshold, so a report can describe one band on its own. Order and duplicates don’t matter. Must name at least one urgency.

Array<string>
Allowed values: Info Low Medium High Critical
start
required

Start of the reporting period.

string format: date-time
tags

Restrict the report to items carrying at least one of these tags. Empty means unscoped. Applies to both registers.

Array<string>
title
required

Report title. Rendered on the title slide, in the per-slide footer, and in the download filename.

string

Responses

Section titled “Responses”

202

Section titled “202”

Report generation enqueued. The artifact is already listed by GET /v1/files as pending; download it from GET /v1/files/{file_id} once it reports ready.

Media typeapplication/json

202 body for an enqueued report.

file_id is the artifact’s identity from the moment this returns: it appears immediately in GET /v1/files as a pending row and becomes downloadable via GET /v1/files/{file_id} once the worker finishes. A client that keeps neither id loses nothing — the row is in the list either way.

object
file_id
required

The stored file the artifact is reserved under.

string format: uuid
job_id
required

Queue job id, for correlating with GET /v1/jobs and with worker logs.

string
Examplegenerated
{
  "file_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "job_id": "example"
}

400

Section titled “400”

Invalid report parameters