File type detector API
Detect the real type of a file from its bytes (130+ formats), compare it with the name and Content-Type, and flag disguised executables and macros.
Upload a file (multipart, raw body or file_base64) or give a url and the API identifies what the bytes really are, without trusting the extension: images (JPEG, PNG, WebP, AVIF, HEIC, raw photos…), PDF, Office documents (DOCX / XLSX / PPTX told apart by their ZIP entries, legacy DOC / XLS / PPT by their OLE2 streams, ODF, EPUB), archives (ZIP, RAR, 7z, gzip, bzip2, xz, zstd, tar, ISO…), audio and video containers, executables (Windows PE with architecture and DLL / .NET flags, ELF, Mach-O, APK, JAR, DEX, WebAssembly, scripts with a shebang, LNK shortcuts, MSI, DEB / RPM), fonts, SQLite and many data formats; text files are classified as SVG, HTML, XML, JSON, CSV, PEM and so on.
The answer gives the MIME type, canonical extension, kind and details, then compares it with the file name (filename, or the uploaded name) and the declared content_type. Warnings have a severity and the overall risk is the highest one: executables hidden behind a document or image extension, VBA macros (especially in a file named .docx / .xlsx), double extensions (invoice.pdf.exe), right-to-left override characters in names, SVG / HTML with scripts, PDF with JavaScript or Launch actions, archives containing executables.
Only the first 64 KB are inspected (plus the ZIP central directory for uploads), so a URL is fetched with a 64 KB cap. The file is not stored. This is a content-type check, not an antivirus: a "none" risk does not prove a file is harmless.
Parameters
| Name | In | Type | Required | Default | |
|---|---|---|---|---|---|
file | body | file | no | The file (multipart, raw body or file_base64). | |
url | query|body | string | no | Public URL of the file (first 64 KB are read). | |
filename | query|body | string | no | File name to compare with (default: uploaded name or URL path). | |
content_type | query|body | string | no | Declared MIME type to compare with (default: upload / response Content-Type). |
Example
curl -X POST "https://apibox.io.vn/v1/file-type" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "0=@./my-file"const form = new FormData();
form.append('0', fileInput.files[0]);
const res = await fetch('https://apibox.io.vn/v1/file-type', {
method: 'POST',
headers: { Authorization: 'Bearer YOUR_API_KEY' },
body: form,
});
console.log(await res.json());import requests
res = requests.post(
"https://apibox.io.vn/v1/file-type",
headers={"Authorization": "Bearer YOUR_API_KEY"},
files={"0": open("my-file", "rb")},
timeout=30,
)
print(res.json())<?php
$ch = curl_init('https://apibox.io.vn/v1/file-type');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
CURLOPT_POSTFIELDS => ['0' => new CURLFile('my-file')],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));Response
{
"source": "upload",
"file_name": "contract.docx",
"size_bytes": 401,
"bytes_inspected": 401,
"type": {
"extension": "docm",
"mime": "application/vnd.ms-word.document.macroEnabled.12",
"kind": "document",
"description": "Word document with macros",
"executable": false,
"details": {
"entries": 3,
"entries_listed": "all",
"macros": true
}
},
"extension": "docx",
"extension_matches": false,
"declared_content_type": null,
"content_type_matches": null,
"expected_extensions": [
"docm",
"dotm"
],
"risk": "high",
"warnings": [
{
"code": "macros",
"severity": "high",
"message": "The file contains VBA macros but is named .docx (macro-free format)"
},
{
"code": "extension_mismatch",
"severity": "low",
"message": "The name ends in .docx but the content is Word document with macros (.docm)"
}
]
}Use cases
- Validate uploads before storing them (OWASP file upload checks)
- Reject executables renamed as images or PDFs
- Spot macro-enabled Office files sent by e-mail
- Fix wrong Content-Type headers when serving user files
FAQ
How are DOCX, XLSX and PPTX distinguished?
They are all ZIP files: the API reads the entry names ([Content_Types].xml, word/, xl/, ppt/, vbaProject.bin) to tell them apart and to detect macros.
Does it scan for viruses?
No. It detects the real format and risky traits (executable code, macros, scripts); use an antivirus for malware.
How much of a URL is downloaded?
At most 64 KB. For ZIP-based files only the local headers in that part are read, which is enough to recognise Office files.
Related APIs
Image Metadata & EXIF
Read image dimensions, format, EXIF camera data, capture settings and GPS location from JPEG, PNG, WebP, HEIC, AVIF, GIF and more – upload or URL.
PDFPDF Metadata
Read PDF metadata: page count, title, author, creator, producer, dates, PDF version, encryption, form fields and the size of each page (A4, Letter…).
PDF₫Quote & Receipt PDF
Generate clean PDF quotations, receipts, orders and simple invoices from JSON, with Vietnamese text, VAT, totals in words and a VietQR code for payment.