Document forensics

Reference for fileForensics runs: endpoints, request rules, statuses, every detector and the errors you can get. For what fileForensics is and how it’s metered, see the overview. For a first run end to end, see the quickstart.

How it works

A run checks a file that is already stored in your workspace, identified by its file_id, so there is no upload in the request. Each result appears under forensics.<key> once that detector has reported, and the file checks appear under checks.<key>.

Start a run

POST /v1/forensics returns 202 with a run_id, status: "queued" and a poll_url. Runs started at upload with enabledProducts: ["FILE_FORENSICS"] run all 55 checks; read them with GET /v1/forensics/files/{file_id}.

Poll

GET /v1/forensics/runs/{run_id} until status is complete or error. Web presence can take up to about 180 seconds.

Retry if stuck

A run still queued or running after about 6 minutes is stuck. POST /v1/forensics/runs/{run_id}/retry re-runs the same file and spec_filter under a new run_id, which is the one to poll. The original run then reports error.

Clean up

DELETE /v1/forensics/runs/{run_id} once you have the result. The file itself is not affected.

Forensics runs are not jobs: they do not appear on GET /v1/jobs/{job_id} and have no callback. See Async jobs for how they compare with other async work.

Endpoints

Endpoint	What it does
`POST /v1/forensics`	Start a run. JSON body: `file_id`, `spec_filter`.
`GET /v1/forensics/runs/{run_id}`	Get a run’s status and results.
`GET /v1/forensics/files/{file_id}`	Get the newest run for a file, whether it was started at upload or with `POST /v1/forensics`. `404` if the file has no run.
`POST /v1/forensics/runs/{run_id}/retry`	Re-run with the same file and `spec_filter`. No body. Returns a new `run_id`.
`DELETE /v1/forensics/runs/{run_id}`	Delete the run. Afterwards, GET, retry and DELETE on it return `404`.

Request

Field	Rules
`file_id`	Required. The public `fileId` of a stored file, up to 128 characters. Unknown files are a `404`.
`spec_filter`	Required. A non-empty array of unique detector keys from Detectors. An unknown or repeated key is a `422`.

spec_filter is required so that a detector added later cannot silently change what an existing integration runs.

Response

Field	Meaning
`run_id`, `file_id`, `spec_filter`, `created_at`	The run and what it checks.
`status`	Run status. See Run status.
`poll_url`	The `GET /v1/forensics/runs/{run_id}` URL for this run. Returned when the run starts.
`forensics.<key>`	One result per detector in `spec_filter`, keyed by detector. Results appear as each detector reports.
`forensics.<key>.status`	See Detector status.
`forensics.<key>.value`	A one-line summary, such as `"AI-generated: false"`. Other fields are detector-specific.
`forensics.web_presence.web_presence`	The combined web-presence boolean. Absent when the run reached no conclusion.
`checks.<key>`	The 18 file checks. Present only when `spec_filter` includes at least one forensic check; then all 18 run, whatever else `spec_filter` says.
`mapping.layout_parse`	The layout parse, present only when `spec_filter` includes `layout_parse`.

Run status

`status`	Meaning
`queued`	Waiting to start.
`running`	In progress. Results appear as each detector reports.
`complete`	Final. Read the results under `forensics`.
`error`	Final. The run failed, or was replaced by a retry.

Detector status

Every detector result has a status, and usually a one-line value. Route on each detector’s status, not the run’s: a complete run can still contain an issue.

`status`	Meaning
`none`	Nothing found.
`issue`	Something to review.
`found`	Information reported, not a problem. For example, `magic_byte` when the file signature matches its type, `revision_history` when the file has later saves, `heatmap`, and most file checks.
`skip`	Doesn’t apply to this file. `value` usually says why.
`error`	The detector failed.

For web_presence, the combined web_presence boolean is absent when the run reached no conclusion (still running, skip or error). Do not read a missing value as “not found on the web”.

Detectors

Key	What it checks
`web_presence`	Whether the image appears on the web, from file metadata (`layer1`) and a reverse-image search (`layer2`).
`ai_gen_detection`	AI-generated image
`ai_text_detection`	AI-generated text
`ai_pdf_detection`	AI-generated PDF
`ai_office_detection`	AI-generated Office document
`copy_move`	Copied-and-moved (cloned) regions
`exact_duplicate`	Exact duplicate of a previously seen file
`provenance_credentials`	Content credentials (C2PA)
`generation_toolchain`	Creation tools inferred from metadata
`producer_divergence`	Different producers across pages
`encryption_permissions`	Encryption and permissions
`active_content`	Active content, such as scripts and launch actions
`digital_signature`	Digital signature
`attachments`	Embedded attachments
`revision_history`	Revision history
`magic_byte`	File signature vs declared type
`polyglot`	Polyglot file (valid as more than one format)
`trailing_data`	Data after the end of the file
`entropy`	Entropy anomalies
`heatmap`	Where the image classifier looked (an attention map, not a verdict). Runs on image files; `skip` for images inside a document.
`document_integrity_decisions`	The 17 integrity questions and their overall decision.
`layout_parse`	Optional. The file’s elements with their positions, returned under `mapping.layout_parse` instead of `forensics`. Not counted as a check.

The MCP tool run_file_forensics accepts the same keys. See MCP tools.

File checks

File checks describe the file rather than judge it. They come back under checks.<key> on every run whose spec_filter includes at least one forensic check, using the same statuses. Most report found when there is something to describe, or none when there isn’t. A few report issue when something is worth a look, such as blank pages, skewed or low-resolution scans, or timestamps that disagree.

Key	What it reports
`file_metadata`	Document metadata
`fingerprint`	File hashes
`text_layer`	Whether pages have a text layer
`producer_metadata`	The producing application
`timestamps`	Creation and modification times
`gps`	GPS location in image metadata
`outline`	Bookmarks and outline
`form_fields`	Interactive form fields
`links`	Links in the file
`fonts`	Fonts used
`page_rotation`	Rotated pages
`language`	Language of the text
`resolution`	Page image resolution
`skew`	Skewed scans
`image_quality`	Image quality
`blank_pages`	Blank pages
`page_numbering`	Page numbering
`barcodes`	QR codes and barcodes, decoded

Integrity questions

document_integrity_decisions asks 17 fixed questions about whether the content holds together. Each answer is under decisions, with a class of signal, no_signal or insufficient_evidence.

Answered from	Questions
The file’s text and metadata (10)	Content consistency, metadata consistency, timeline consistency, provenance and integrity claims, structural completeness, typography within comparable roles, visible versus embedded content, authorization and conditions, meaningful change from a prior version, interpretation of the other forensic results
Page images (6)	Handwritten alterations, local visual discontinuities, page assembly, obscured or covered content, visible evidence of stated requirements, repeated distinctive visual content
The file’s signatures, checked locally (1)	Cryptographic integrity of signatures and revisions

final_decision combines the answers and sets the detector’s result:

`status`	`value`	Meaning
`issue`	`review_recommended`	Something is worth a reviewer’s attention. Not a fraud verdict.
`none`	`no_signal`	The questions found nothing inconsistent. Not proof the file is authentic.
`skip`	`incomplete_evidence`	The answers weren’t enough to decide, for example because some questions couldn’t be answered for this file.

A question can go unanswered, for example when the file has no page images or no signature. Its class is then insufficient_evidence, or null when no answer came back. When the integrity questions aren’t enabled, document_integrity_decisions reports skip, and its value says the check is disabled.

Errors

Status	When
`404`	Unknown file or run, a deleted run, or a run the forensics service no longer holds.
`422`	Invalid body, a file with no stored content to analyze, or (on retry) a file that is no longer available.
`502`	The forensics service returned an error or was unreachable.
`503`	fileForensics is not configured.

See Errors for the response format.

Forensics quickstart

Run your first check end to end.

KYC checks

Choose detectors per document and route on the result.

Uploads

Store a file and get its fileId.

MCP tools

Run fileForensics from an AI assistant.

Get started

Products

Build

Go live

How it works

Endpoints

Request

Response

Run status

Detector status

Detectors

File checks

Integrity questions

Errors

Forensics quickstart

KYC checks

Uploads

MCP tools

​How it works

​Endpoints

​Request

​Response

​Run status

​Detector status

​Detectors

​File checks

​Integrity questions

​Errors

​Related

Forensics quickstart

KYC checks

Uploads

MCP tools

How it works

Endpoints

Request

Response

Run status

Detector status

Detectors

File checks

Integrity questions

Errors

Related