Scan

Submit a File for Scanning

`POST /api/upload`

Uploads a file to be scanned for security threats, malware, and suspicious content.

Request

Content-Type: multipart/form-data

File fields

Field	Required	Description
`file`	Yes	The file to scan (max 32 MB)
`originalFileName`	No	Original filename when the payload is compressed or renamed
`originalMimeType`	No	Original MIME type of the file
`originalSize`	No	Original size in bytes (required when `isCompressed=true`)
`originalFileHash`	No	Pre-computed SHA-256 hex digest of the original (uncompressed) file
`isCompressed`	No	`"true"` if the uploaded payload is gzip-compressed
`compressionRatio`	No	Numeric compression ratio (informational)

Scan options

Field	Required	Default	Description
`fullRescan`	No	`false`	Force a fresh scan even if a completed scan for the same file hash exists
`secretScan`	No	`true`	Enable secret / credential detection
`iocScan`	No	`true`	Enable indicator-of-compromise (IoC) detection
`ocrStrategy`	No	`hybrid`	OCR strategy: `hybrid`, `force`, or `skip`
`inputType`	No	`document`	Input classification hint: `document`, `code`, `image`, etc.
`normalizationMode`	No	`aggressive`	Text normalization: `aggressive` or `conservative`
`analysisMode`	No	`quick`	Analysis depth: `quick` or `deep`

Example

curl -sS -X POST \
  -H 'X-API-Key: <YOUR_PAT>' \
  -F 'file=@./suspicious.pdf' \
  -F 'secretScan=true' \
  -F 'analysisMode=deep' \
  'https://api.sieve.godel-labs.ai/api/upload'

Response (201 — queued)

{
  "scanId": "2b2f7b8b-7f2c-4b2d-9a5f-5c0c4c3c9d4e",
  "fileName": "suspicious.pdf",
  "fileSize": 123456,
  "fileHash": "<sha256>",
  "status": "queued",
  "message": "File uploaded successfully. Scan queued for processing."
}

Response (200 — cached)

When a completed scan with the same file hash already exists and fullRescan is not set, the cached result is returned immediately:

{
  "scanId": "2b2f7b8b-7f2c-4b2d-9a5f-5c0c4c3c9d4e",
  "fileName": "suspicious.pdf",
  "fileSize": 123456,
  "fileHash": "<sha256>",
  "status": "completed",
  "cached": true,
  "message": "A previous scan with the same file hash was found. Returning cached results."
}

Response (201 — archive extracted)

Archives (zip, tar, etc.) are extracted before scanning. Each file in the archive is scanned individually.

{
  "scanId": "2b2f7b8b-7f2c-4b2d-9a5f-5c0c4c3c9d4e",
  "fileName": "bundle.zip",
  "fileSize": 456789,
  "fileHash": "<sha256>",
  "status": "extracting",
  "isArchive": true,
  "message": "Archive uploaded. Files will be extracted and scanned individually."
}

Notes

Maximum file size is 32 MB.
Use scanId to poll status and results via GET /api/scans/:scanId.
File type is validated against magic bytes in addition to the file extension.
Rate limits: free tier 5 uploads per 5 min / 20 per hour; premium tier 10,000 per 5 min / 20,000 per hour.

Scan

On this page