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 '{ "comparison": { "end": "2026-04-01", "start": "2026-04-01" }, "end": "2026-04-01", "incidents": { "include_children": true, "include_table": true, "severities": [ "SEV-5" ] }, "risks": { "include_children": true, "include_table": true, "urgencies": [ "Info" ] }, "start": "2026-04-01", "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
comparison
One of:

The window the report’s period-over-period figures are measured against. Omit it to have the report derive one from the reporting period: the previous month, quarter, or year for a whole one, and the same span of the previous unit for a to-date window.

object
end
required

End of the comparison window, through the last microsecond of the day it names in its own offset. Must not be earlier than start, and must fall on a day before the reporting period’s start.

string
start
required

Start of the comparison window, from the first instant of the day it names in its own offset.

string
end
required

End of the reporting period, in the same forms as start. The period runs through the last microsecond of the day it names in its own offset, so the whole last day is counted.

string
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: a bare YYYY-MM-DD or an RFC 3339 timestamp in any UTC offset. The period opens at the first instant of the day it names in its own offset (a bare day is a UTC day).

string
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