Skip to content
adversarial

List the org's stored files

GET
/v1/files
curl --request GET \
  --url 'https://api.adversarial.com/api/v1/files?page=1&page_size=25'

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
kind
Array<string> | null
Allowed values: compliance_document report

Kinds to include, repeatable (?kind=report&kind=compliance_document). Empty means “every kind I am allowed to see” — see the handler for why an explicit ask and an absent one are gated differently.

status
Array<string> | null
Allowed values: pending ready failed

Lifecycle statuses to include, repeatable (?status=pending&status=ready). Empty defaults to ready alone, so a plain catalogue does not advertise rows whose bytes do not exist yet; ask for pending/failed explicitly to follow a report being generated.

page
integer format: int64
default: 1 >= 1 <= 1000000

1-indexed page number. Defaults to 1; zero is rejected.

page_size
integer format: int64
default: 25 >= 1 <= 100

Rows per page. Defaults to 25, max 100; zero is rejected.

Responses

Section titled “Responses”

200

Section titled “200”

Paginated list of stored files

Media typeapplication/json

Paginated list envelope: { "results": [...], "pagination": {...} }.

object
pagination
required

Pagination metadata describing the slice.

object
page
required

1-indexed page number of this result slice.

integer format: int64
page_size
required

Number of items requested per page.

integer format: int64
total_items
required

Total number of matching items across all pages.

integer format: int64
total_pages
required

Total number of pages at this page size.

integer format: int64
results
required

The items on this page.

Array<object>

One row of the stored-file listing (GET /v1/files).

This is the shape a catalogue needs — what it is, when it appeared, who asked for it, and where to get it.

object_key, org_key_id, enc_nonce_prefix and params are deliberately absent. The first three are storage/crypto internals, and params carries the full report descriptor — exposing it would leak the shape of every report request an org has ever made.

object
byte_size

Plaintext byte size; None until the file completes.

integer | null format: int64
content_type
required

MIME content type.

string
created_by

Who requested it, as a display name. None for system-generated files or when the requesting user has since been removed.

string | null
created_date
required

When the row was created.

string format: date-time
download_path

Where to fetch the bytes. None unless status is ready — a client cannot construct a working link for a row that has no bytes yet, and omitting it keeps that unrepresentable rather than merely discouraged.

string | null
error

Why the file failed, when status is failed. Always a message written by the server for display — producers sanitize before persisting it, so the underlying storage/builder error is never echoed here.

string | null
id
required

The stored file’s id.

string format: uuid
kind
required

The file’s kind, which is also what gates its download.

string
name
required

Display name (for a report, its generated filename).

string
status
required

Lifecycle status (pending / ready / failed).

string
Allowed values: pending ready failed
Example
{
  "results": [
    {
      "status": "pending"
    }
  ]
}

403

Section titled “403”

Missing the permission a requested kind requires