A file scanner API is one component in an upload pipeline, not the whole pipeline. Before an engine receives the bytes, the application decides who may upload, which formats are useful, and where the object is stored. After inspection, the application decides which version may be displayed, downloaded, transformed, or shared. A weak decision on either side can undermine an otherwise useful scan.
Design the workflow around a deliberate sequence: accept only the requests your application needs, stage the object privately, inspect it with appropriate checks, and release a defined version under a documented policy. This guide proposes that architecture for an application you operate. It does not describe an upload service on ScannerAPI.com, and it does not treat any single result as an absolute safety guarantee.
Begin with the business allowlist
List the file formats the product genuinely needs. For each format, identify the maximum useful size, whether active content is permitted, and what the user should be able to do with the result. A profile image and a complex project archive do not need the same policy. Accepting fewer well-understood formats can make the rest of the inspection and delivery design easier to explain.
The OWASP File Upload Cheat Sheet recommends layered validation, limits, controlled storage, and appropriate inspection. Use that as a foundation rather than looking for one decisive check. A filename extension, a declared content type, and a parser’s observation each contribute information; none should silently stand in for all the others.
Authenticate and bound the incoming request
Associate the upload with an authenticated identity where the workflow requires one, and verify that the identity may create the relevant object. Apply request-size and rate controls before expensive processing. Make the client-facing limit agree with what downstream components can handle so users receive predictable feedback instead of a late, mysterious failure after transferring a large file.
Treat the supplied name as display data, not as a server path. Give the object an internal storage key and keep the original name only where it is useful and safely handled. Consider names in logs, downloaded responses, and user interfaces as well as in storage. An upload policy should describe these uses rather than assuming that renaming the file resolves every input-handling concern.
Use private staging with explicit states
Store new objects in a restricted area that is not available through public download routes. Associate each object with a state such as awaiting inspection, under review, approved, or rejected. Those are proposed application states; choose names that suit the product and document the allowed transitions. No state should become publicly available merely because a background worker failed to update it.
Keep the storage identity version-aware. When the bytes change, invalidate decisions that depended on the earlier content. A digest or immutable storage version can help bind a result to the object being released. The release step should check that binding explicitly. Without it, a replacement uploaded under the same name can accidentally inherit approval intended for a different file.
Keep temporary storage temporary
Define retention and cleanup for rejected, abandoned, and unresolved uploads. Cleanup must not race with inspection or remove evidence that an authorized review process needs. Record a small audit reference where appropriate without keeping every private file indefinitely. Assign ownership for stuck objects so a queue of unfinished jobs does not quietly become permanent storage outside the application’s normal controls.
Compare declared type with inspected content
Check the allowlisted extension and the declared media type, then use suitable content-level inspection for the supported format. Treat disagreement as something to resolve by policy, not as an invitation to pick whichever description permits release. A parser error, malformed structure, or unsupported variant should remain visible. The application needs a defined response when its tools cannot confidently process the object.
Keep the purpose of each check clear. Type validation asks whether the file belongs to a permitted class. Antivirus inspection looks for the kinds of threats supported by an engine. Document processing may create a constrained representation for display. Metadata review examines information carried with the file. A successful result from one does not automatically complete the others.
Give archives and encrypted content their own rules
An archive can contain many objects and multiple levels of nesting. Define limits for expansion, member count, nesting, and total processing work according to the tools you use. Avoid presenting inspection of the outer container as complete inspection of every member. Report which parts were examined and which were skipped or could not be processed.
Encrypted content requires an explicit policy when the system cannot inspect inside it. That might mean rejecting the format for a public upload path or routing it through an authorized private review process. Do not label the contents clean simply because no scanner could read them. The same principle applies to unsupported document variants and processing limits that stop inspection early.
Treat transformed outputs as separate artifacts
A preview, thumbnail, sanitized document, and original file can have different properties. Record which transformation produced each output and which checks apply to it. If a user will download the original, a safe-looking preview is not a substitute for evaluating the original’s release policy. If only a constrained derivative is public, keep the original inaccessible through alternate paths.
Verify the final output, not just the input to the transformation. A processing step may change metadata, dimensions, file structure, or content. The EXIF data scanner guide describes checking a published image derivative for privacy-relevant metadata. Keep those privacy checks separate from malware inspection while ensuring both occur at the stage where their results are meaningful.
Make incomplete inspection a visible outcome
A scan job can fail because an engine is unavailable, a file cannot be read, or the processing deadline is reached. Preserve the reason and keep it distinct from a completed result with no detection. A release policy should say what happens for every outcome that the integration can produce. Avoid a generic exception handler that returns approval simply to prevent the user interface from hanging.
Use a bounded waiting policy and a clear user message. “Inspection could not finish” is more accurate than describing an unsupported file as malicious or reassuring the user that it passed. A review path needs an owner, access controls, and a completion condition. The antivirus scanner API guide covers engine readiness and result handling as part of this larger release gate.
Check delivery as carefully as upload
Once an object is approved, serve it through the intended delivery path with the response behavior appropriate to the format and product. Keep authorization checks on private downloads. Avoid exposing the staging location or relying on a hidden URL as the only control. Review how the application handles filenames, media types, and browser display behavior during delivery.
Test alternate representations and routes. An approved thumbnail should not accidentally expose a rejected original. A deleted object should not remain accessible through an overlooked application endpoint. Keep caching and storage cleanup aligned with the product’s lifecycle requirements. These are application decisions that a scanner cannot infer from the bytes, so they need their own acceptance tests.
Test the complete pipeline
Create harmless fixtures for allowed types, mismatched types, oversized requests, unsupported content, encrypted archives, duplicate events, and changed object versions. For every fixture, record the expected processing state, storage visibility, and user-facing outcome. Simulate engine errors and verify that incomplete inspection does not become approval. Check the behavior after a restart or a delayed completion event as well.
A safer upload pipeline is a chain of explicit decisions. A file scanner API supplies useful evidence inside that chain, while the application controls identity, storage, interpretation, and release. Build the sequence so each component says what it knows, each failure remains visible, and only the intended object reaches the intended audience.
