Filtering & Sorting

Filter and sort API results.

Filtering

Many endpoints support filtering via query parameters.

Vulnerabilities

# Filter by severity
GET /api/v1/vulnerabilities?severity=critical

# Filter by status
GET /api/v1/vulnerabilities?status=open

# Filter by scanner
GET /api/v1/vulnerabilities?scanner_ids=slither,mythril

# Filter by category
GET /api/v1/vulnerabilities?categories=reentrancy,access_control

# Filter by minimum confidence score
GET /api/v1/vulnerabilities?min_confidence=0.8

# Combine multiple filters
GET /api/v1/vulnerabilities?severity=high&status=open&scanner_ids=slither

Available Filters

Parameter	Type	Values
`severity`	string	`critical`, `high`, `medium`, `low`
`status`	string	`open`, `acknowledged`, `fixed`, `false_positive`
`scanner_ids`	string	Comma-separated scanner IDs
`categories`	string	Comma-separated category names
`min_confidence`	float	0.0 to 1.0
`contract_id`	UUID	Filter by specific contract

Scans

# Filter by status
GET /api/v1/scans?status=completed

# Filter by contract
GET /api/v1/scans?contract_id=abc123

# Combine filters
GET /api/v1/scans?status=completed&contract_id=abc123

Available Filters

Parameter	Type	Values
`status`	string	`queued`, `running`, `completed`, `failed`, `cancelled`
`contract_id`	UUID	Filter by specific contract
`project_id`	UUID	Filter by specific project

Contracts

# Filter by language
GET /api/v1/contracts?language=solidity

# Filter by project
GET /api/v1/contracts?project_id=abc123

Available Filters

Parameter	Type	Values
`language`	string	`solidity`, `vyper`, `rust`, `move`, `cairo`
`project_id`	UUID	Filter by specific project
`status`	string	`pending`, `uploaded`, `analyzed`

Audit Logs

# Filter by action
GET /api/v1/audit-logs?action=scan.started

# Filter by resource type
GET /api/v1/audit-logs?resource_type=contract

# Filter by date range
GET /api/v1/audit-logs?from=2025-01-01&to=2025-01-31

Available Filters

Parameter	Type	Description
`action`	string	Action type (e.g., `scan.started`)
`resource_type`	string	Resource type (e.g., `contract`, `scan`)
`from`	date	Start date (ISO 8601)
`to`	date	End date (ISO 8601)
`user_id`	UUID	Filter by user

Sorting

Results are sorted by default (newest first for most endpoints).

Default Sort Order

Endpoint	Default Sort
`GET /vulnerabilities`	`detected_at DESC`
`GET /scans`	`created_at DESC`
`GET /contracts`	`created_at DESC`
`GET /audit-logs`	`created_at DESC`

The default sort order is optimized for cursor-based pagination.

Combining Filters with Pagination

Filters work with both pagination styles:

With Cursor Pagination

GET /api/v1/vulnerabilities?severity=high&status=open&first=50
GET /api/v1/vulnerabilities?severity=high&status=open&first=50&after=eyJ2IjoxLC...

With Offset Pagination

GET /api/v1/vulnerabilities?severity=high&status=open&skip=0&limit=50
GET /api/v1/vulnerabilities?severity=high&status=open&skip=50&limit=50

Filter Examples

Find Critical Open Vulnerabilities

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?severity=critical&status=open&first=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Find Reentrancy Vulnerabilities from Slither

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?categories=reentrancy&scanner_ids=slither&first=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Find High-Confidence Results Only

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?min_confidence=0.9&first=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Completed Scans for a Project

curl -X GET "https://api.blocksecops.com/api/v1/scans?project_id=abc123&status=completed&first=20" \
  -H "Authorization: Bearer YOUR_API_KEY"