API

Falcn provides a REST API for programmatic access to scanning capabilities.

Starting the Server

falcn serve --port 8080

Authentication

Use Bearer token authentication:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8080/v1/scan

Endpoints

POST /v1/scan

Scan a project or package list.

curl -X POST http://localhost:8080/v1/scan \
  -H "Content-Type: application/json" \
  -d '{
    "packages": [
      {"name": "lodash", "version": "4.17.21", "ecosystem": "npm"},
      {"name": "express", "version": "4.18.2", "ecosystem": "npm"}
    ],
    "options": {
      "check_vulnerabilities": true,
      "asset_criticality": "CRITICAL"
    }
  }'

Response

{
  "scan_id": "abc123",
  "status": "completed",
  "duration_ms": 94,
  "summary": {
    "total": 2,
    "safe": 2,
    "threats": 0
  },
  "results": [...]
}

GET /v1/scan/:id

Get scan results by ID.

GET /v1/health

Health check endpoint.

GET /metrics

Prometheus metrics endpoint.

WebSocket Streaming

const ws = new WebSocket('ws://localhost:8080/v1/stream');
ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  console.log(result);
};