> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.detectant.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.detectant.com/_mcp/server. # Scan a file POST https://api.detectant.com/v1/scans Content-Type: multipart/form-data Uploads one file and synchronously runs content-type and malware analysis. Only the first multipart part named `file` with a filename is scanned; other parts are ignored. Free accounts accept files up to 50 MB; Grow and Scale accounts accept files up to 250 MB. Direct API uploads never exceed 250 MB; S3 integration limits are separate. Reference: https://docs.detectant.com/api-reference/scan ## Authentication - `X-API-Key` header (required) — API key in the `mak..` format. ## Request ### Body (multipart/form-data) This endpoint expects a multipart form containing a file. - `file` (file, required) — File content to scan. The part must include a filename. ## Response ### 201 The scan completed and was stored. - `id` (string, required) — Server-generated scan identifier. - `created_at` (datetime, required) - `status` (enum, required) - Allowed values: `completed`, `failed` - `verdict` (enum, required) - Allowed values: `clean`, `malicious`, `suspicious`, `unknown` - `filename` (string, required) — Filename supplied by the multipart upload. - `sha256` (string, required) - `size_bytes` (long, required) - `duration_ms` (double, required) - `timings` (ScanTimings, required) - `failure` (ScanFailure, required, nullable) — Failure information, or `null` when the scan completed. - `detections` (list of string, required) — Detection names reported for the file. Empty when no threats were detected. - `type_analysis` (TypeAnalysis, required) - `source` (ScanSource, required) ## Errors ### 400 Bad Request Error The request parameters or upload are invalid. - `error` (APIError, required) ### 401 Unauthorized Error The API key is missing or invalid. - `error` (APIError, required) ### 403 Forbidden Error A dashboard session was supplied where an API key is required. - `error` (APIError, required) ### 413 Content Too Large Error The upload or safely expanded content exceeds a scanner limit. - `error` (APIError, required) ### 429 Too Many Requests Error The plan's current-period scan allowance, global request rate, or concurrent scanner capacity was exceeded. Plan exhaustion uses `USAGE_LIMIT_EXCEEDED` and includes the plan, limit, and reset time in `details`. - `error` (APIError, required) ### 500 Internal Server Error An unexpected internal failure occurred. - `error` (APIError, required) ### 503 Service Unavailable Error Scanner infrastructure or signatures are unavailable. - `error` (APIError, required) ## Types ### ScanTimings - `file_type_ms` (double, required) - `malware_scan_ms` (double, required) ### ScanFailure - `code` (enum, required) - Allowed values: `SCANNER_UNAVAILABLE`, `CONTENT_EXPANSION_LIMIT_EXCEEDED` - `message` (string, required) ### TypeAnalysis - `declared` (TypeDeclaration, required) - `identified` (TypeIdentification, required) - `status` (enum, required) - Allowed values: `match`, `compatible`, `mismatch`, `malformed`, `unscannable`, `unknown` - `structurally_valid` (boolean, required, nullable) - `confidence` (enum, required) - Allowed values: `high`, `medium`, `low` - `reason` (TypeAnalysisReason, required, nullable) ### ScanSource - `type` (enum, required) - Allowed values: `api`, `s3` - `integration_id` (string, required, nullable) — S3 integration identifier, or `null` for direct API scans. - `integration_name` (string, required, nullable) — S3 integration name, or `null` for direct API scans. ### APIError - `code` (string, required) — Stable machine-readable error code. - `message` (string, required) — Human-readable error message. - `details` (map from string to string, required) — Context such as the ID of a failed stored scan. Empty when no context applies. ### TypeDeclaration - `extension` (string, optional) — Raw extension from the uploaded filename, without the leading dot. - `mime` (string, optional) — Normalized MIME type declared by the multipart part. ### TypeIdentification - `format` (string, optional) — Canonical format identified from file content. - `mime` (string, optional) — Canonical MIME type identified from file content. ### TypeAnalysisReason - `code` (enum, required) - Allowed values: `malformed_file`, `encrypted_archive`, `unsupported_archive`, `content_expansion_limit_exceeded`, `file_type_mismatch` - `claimed` (string, optional) - `detected` (string, optional) ## Examples **Request** ```json { "file": "" } ``` **Response** ```json { "id": "scan_0123456789abcdef0123456789abcdef", "created_at": "2024-01-15T09:30:00Z", "status": "completed", "verdict": "clean", "filename": "string", "sha256": "string", "size_bytes": 1, "duration_ms": 1.1, "timings": { "file_type_ms": 1.1, "malware_scan_ms": 1.1 }, "failure": { "code": "SCANNER_UNAVAILABLE", "message": "string" }, "detections": [ "string" ], "type_analysis": { "declared": { "extension": "string", "mime": "string" }, "identified": { "format": "string", "mime": "string" }, "status": "match", "structurally_valid": true, "confidence": "high", "reason": { "code": "malformed_file", "claimed": "string", "detected": "string" } }, "source": { "type": "api", "integration_id": "string", "integration_name": "string" } } ``` **SDK Code** ```python import requests url = "https://api.detectant.com/v1/scans" files = { "file": "open('[object Object]', 'rb')" } headers = {"X-API-Key": ""} response = requests.post(url, files=files, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.detectant.com/v1/scans'; const form = new FormData(); form.append('file', '[object Object]'); const options = {method: 'POST', headers: {'X-API-Key': ''}}; options.body = form; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.detectant.com/v1/scans" payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"[object Object]\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.detectant.com/v1/scans") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-Key"] = '' request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"[object Object]\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.detectant.com/v1/scans") .header("X-API-Key", "") .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"[object Object]\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n") .asString(); ``` ```php request('POST', 'https://api.detectant.com/v1/scans', [ 'multipart' => [ [ 'name' => 'file', 'filename' => '[object Object]', 'contents' => null ] ] 'headers' => [ 'X-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.detectant.com/v1/scans"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"[object Object]\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["X-API-Key": ""] let parameters = [ [ "name": "file", "fileName": "[object Object]" ] ] let boundary = "---011000010111000001101001" var body = "" var error: NSError? = nil for param in parameters { let paramName = param["name"]! body += "--\(boundary)\r\n" body += "Content-Disposition:form-data; name=\"\(paramName)\"" if let filename = param["fileName"] { let contentType = param["content-type"]! let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8) if (error != nil) { print(error as Any) } body += "; filename=\"\(filename)\"\r\n" body += "Content-Type: \(contentType)\r\n\r\n" body += fileContent } else if let paramValue = param["value"] { body += "\r\n\r\n\(paramValue)" } } let request = NSMutableURLRequest(url: NSURL(string: "https://api.detectant.com/v1/scans")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```