List Scans

Retrieve Scans

`GET /api/scans`

Retrieves a paginated list of your security scans.

Query parameters

Param	Type	Default	Description
`limit`	number	`20`	Max items to return
`offset`	number	`0`	Pagination offset
`status`	string	—	Filter by status: `queued`, `pending`, `extracting`, `processing`, `completed`, `failed`, `error`, `unsupported`
`search`	string	—	Substring match on `fileName`

Example

curl -sS \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/scans?limit=20&status=completed'

Response (200)

{
  "scans": [
    {
      "scanId": "2b2f7b8b-7f2c-4b2d-9a5f-5c0c4c3c9d4e",
      "fileName": "suspicious.pdf",
      "fileHash": "<sha256>",
      "status": "completed",
      "threatScore": 0.12,
      "severity": "low",
      "riskCategory": "safe",
      "confidence": 0.95,
      "securityIssuesCount": 0,
      "sensitiveDataCount": 1,
      "detectionClass": ["document"],
      "uploadedBy": "alice@example.com",
      "createdAt": "2026-02-14 12:34:56",
      "updatedAt": "2026-02-14 12:35:10"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Response fields

Field	Type	Description
`scanId`	string	Unique scan identifier (UUID)
`fileName`	string	Original file name
`fileHash`	string	SHA-256 hex digest of the original file
`status`	string	Current scan status (see status values below)
`threatScore`	number \| null	Threat probability score (0–1)
`severity`	string \| null	Severity level: `low`, `medium`, `high`, `critical`
`riskCategory`	string \| null	Risk category: `safe`, `suspicious`, `malicious`
`confidence`	number \| null	Model confidence in the classification (0–1)
`securityIssuesCount`	number \| null	Number of distinct security issues found
`sensitiveDataCount`	number \| null	Number of sensitive data items detected
`detectionClass`	string[]	List of detected content/threat classes
`uploadedBy`	string	Email or name of the user who uploaded the file
`createdAt`	string	ISO-8601 timestamp when the scan was created
`updatedAt`	string	ISO-8601 timestamp of the last status update

Delete Scan

`DELETE /api/scans/:scanId`

Permanently deletes a scan record and its associated file from storage.

Example

curl -sS -X DELETE \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/scans/2b2f7b8b-7f2c-4b2d-9a5f-5c0c4c3c9d4e'

Response (200)

{
  "success": true,
  "message": "Scan deleted successfully",
  "scanId": "2b2f7b8b-7f2c-4b2d-9a5f-5c0c4c3c9d4e"
}

List Scans

On this page