Scan Endpoint

Submit code for security analysis.

POST /api/v1/scan

Analyzes source code files for AI agent security vulnerabilities.

Request

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	`multipart/form-data`

Body (multipart form):

Field	Type	Required	Description
`file`	File	Yes	Source file to scan (can send multiple)

Supported file types:

Python (.py)
JavaScript (.js, .jsx)
TypeScript (.ts, .tsx)
Go (.go)
YAML (.yaml, .yml)
JSON (.json)

Response


{
  "success": true,
  "risk_score": 65,
  "findings_count": 3,
  "critical_count": 0,
  "high_count": 2,
  "medium_count": 1,
  "low_count": 0,
  "findings": [
    {
      "id": "f8a3b2c1",
      "severity": "HIGH",
      "file": "agent.py",
      "line": 42,
      "column": 12,
      "message": "User input directly concatenated into LLM prompt",
      "cwe": "CWE-77",
      "owasp": "LLM01"
    }
  ],
  "files_scanned": 5,
  "scan_duration": "2.1s"
}

Response Fields

Field	Type	Description
`success`	boolean	Whether the scan completed
`risk_score`	integer	Overall risk score (0-100)
`findings_count`	integer	Total number of findings
`critical_count`	integer	Critical severity findings
`high_count`	integer	High severity findings
`medium_count`	integer	Medium severity findings
`low_count`	integer	Low severity findings
`findings`	array	List of security findings
`files_scanned`	integer	Number of files analyzed
`scan_duration`	string	Time taken for analysis

Finding Object

Field	Type	Description
`id`	string	Unique finding identifier
`severity`	string	`CRITICAL`, `HIGH`, `MEDIUM`, or `LOW`
`file`	string	File path where issue was found
`line`	integer	Line number
`column`	integer	Column number
`message`	string	Description of the vulnerability
`cwe`	string	CWE identifier (e.g., `CWE-77`)
`owasp`	string	OWASP LLM Top 10 category

Severity Levels

Severity	Description
`CRITICAL`	Immediate risk, fix before deployment
`HIGH`	Significant risk, fix before release
`MEDIUM`	Moderate risk, fix in normal cycle
`LOW`	Minor risk, address when convenient

Rate Limits

Limit	Value
Requests per minute	5
Max file size	10 MB
Max files per request	50

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Example Request


curl -X POST https://api.inkog.io/api/v1/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./src/agent.py" \
  -F "file=@./src/tools.py"

Scanning a Directory

To scan multiple files, send each file as a separate form field:


# Find all Python files and scan them
find ./src -name "*.py" -exec curl -X POST https://api.inkog.io/api/v1/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@{}" \;

Or use the CLI for easier directory scanning:


inkog scan ./src

GET /v1/scans/{id}/diff

Compare a scan with the previous scan of the same agent to detect new and fixed findings. Useful for CI/CD regression tracking.

Request

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`

Query Parameters:

Parameter	Type	Required	Description
`base`	string	No	UUID of specific base scan to compare against (defaults to previous scan)

Response


{
  "success": true,
  "diff": {
    "base_scan_id": "550e8400-e29b-41d4-a716-446655440000",
    "base_scan_time": "2024-01-15T10:30:00Z",
    "head_scan_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "head_scan_time": "2024-01-16T14:22:00Z",
    "summary": {
      "total_new": 2,
      "total_fixed": 1,
      "total_unchanged": 15,
      "new_by_severity": { "CRITICAL": 1, "HIGH": 1 },
      "fixed_by_severity": { "HIGH": 1 },
      "base_risk_score": 450,
      "head_risk_score": 480,
      "risk_delta": 30
    },
    "new_findings": [],
    "fixed_findings": [],
    "unchanged_findings": []
  }
}

Summary Fields

Field	Type	Description
`total_new`	integer	Number of new findings in this scan
`total_fixed`	integer	Number of findings fixed since baseline
`total_unchanged`	integer	Findings present in both scans
`new_by_severity`	object	Breakdown of new findings by severity
`fixed_by_severity`	object	Breakdown of fixed findings by severity
`base_risk_score`	integer	Risk score of the baseline scan
`head_risk_score`	integer	Risk score of the current scan
`risk_delta`	integer	Change in risk score (positive = worse)

First Scan Behavior

If this is the first scan for an agent (no previous scan exists), the response will contain:

base_scan_id: null
summary.total_new: All findings in the current scan
summary.total_unchanged: 0

Example Request


# Compare with previous scan (auto-detected)
curl https://api.inkog.io/v1/scans/6ba7b810-9dad-11d1-80b4-00c04fd430c8/diff \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Compare with specific baseline scan
curl "https://api.inkog.io/v1/scans/6ba7b810-9dad-11d1-80b4-00c04fd430c8/diff?base=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Regression Detection

The diff endpoint includes helper fields for regression detection:

Status	Condition	Description
`REGRESSION`	new_by_severity.CRITICAL > 0 OR new_by_severity.HIGH > 0	New critical/high severity findings
`IMPROVED`	No regression AND (fixed_by_severity.CRITICAL > 0 OR fixed_by_severity.HIGH > 0)	Fixed critical/high findings without new ones
`CHANGED`	New findings but only MEDIUM/LOW severity	Changes but not critical
`UNCHANGED`	total_new == 0 AND total_fixed == 0	No changes