File Inspection API: SHA-256, Real MIME, Antivirus Signal and Metadata in One REST Call

File Inspection API: SHA-256, Real MIME, Antivirus Signal and Metadata in One REST Call

Applications that accept uploads often need a small technical checkpoint before they hand a file to a parser, a workflow or a storage pipeline. A marketplace may receive seller documents, a SaaS product may accept customer attachments, and a sharing platform may need to record what entered the system. Each team can build its own hash, MIME detection, metadata extraction and initial malware-triage layer, but maintaining those checks consistently is not always the best use of engineering time. FileInspection exposes these checks through an asynchronous REST contract and returns one JSON report.

The multipart request

Authenticated clients send a multipart request to POST /api/files/start-process. The request uses actionName=FileInspection, one uploaded file in the file field, parameters=[] and async=true. One non-empty file is accepted per call, up to 50 MB, and the service does not filter by extension. Server-side validation still checks the actual request and size; a frontend accept attribute or a filename is not a security boundary.

The initial response represents a queued action rather than a completed report. Store the returned process identifier and trackingUrl, then poll /api/actions/get-action-infos/{id} with the authenticated context. Processing is asynchronous, so an integration should not keep the upload request open while MIME detection, the antivirus engine triage, metadata extraction or media probing runs.

What the JSON report contains

A successful FileInspection result is one JSON file. It records the original filename and size, a SHA-256 hash and the real detected MIME type. The MIME value is derived from the content rather than being accepted from the browser as proof. That gives an application a better basis for logging, routing or deciding whether a downstream parser should receive the file.

The report can also include filtered EXIF metadata through ExifTool when the file format supports it. For audio and video, FFprobe can provide codec, resolution, duration and bitrate information. Images and PDFs can receive an OCR preview limited to 500 characters. These are inspection fields, not a claim that every format exposes every field. An integration should handle absent, empty or unavailable values without assuming that a missing field means a failed upload.

Triage signals and their limits

The antivirus section reports a antivirus engine status of clean, infected or error. This is a preliminary triage signal, never a guarantee of antivirus protection. In particular, clean means only that this inspection did not report a detection; it must not be mapped to “certified safe” in a user interface or automated policy. An error must remain distinguishable from clean so that an integrator can choose a cautious fallback.

The detection rule section reports clean, matched or not_run. The starter rule set is intentionally minimal and is not an exhaustive detection base. A match can be useful for routing a file to review, while a clean or not-run status must not be presented as proof that no threat exists. Keep this wording in product documentation and logs so that a technical signal does not become an accidental security promise.

Designing the integration

Save the action ID as the durable reference for the asynchronous job. Distinguish at least four states in the calling application: rejected validation, processing, failed processing and completed with a result. If polling times out, retrieve the existing action before considering another submission. Starting a second inspection because one status request failed can create duplicate work and unnecessary token usage.

When the action succeeds, use the authenticated result flow and the server-provided result reference to download the JSON. Do not build a result URL from an integer ID alone, and do not treat a client-supplied action ID as authorization. Your own application should also enforce ownership when it associates the report with an upload record. Hashes help with deduplication and traceability, but they do not grant access to the underlying file.

Documentation, cost and practical scope

Request examples and the response contract are available in the FileInspection API documentation. A successful inspection costs 12 tokens. Validation failures, including an empty file or a file that exceeds 50 MB, are not billed. The service is therefore suited to a bounded first checkpoint before parsing or human review, not as a replacement for a complete malware-analysis platform or a business-specific content policy.

With one REST call, an integration can obtain a SHA-256 fingerprint, real MIME detection, a preliminary antivirus engine signal, minimal detection rule status, filtered metadata and format-dependent media or OCR details. The asynchronous contract leaves the calling system free to queue its own work while preserving a clear, auditable reference to the inspection.