API Reference

The sentrik REST API exposes the scanning pipeline over HTTP, enabling remote scanning, gating, and report generation.

Starting the server

sentrik dashboard                     # Default: localhost:8000
sentrik dashboard --port 9000         # Custom port
sentrik dashboard --host 0.0.0.0     # Expose to network (auto-generates API key if needed)
sentrik dashboard --reload            # Dev mode with auto-reload

Auto-generated interactive docs are available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• API Landing: http://localhost:8000/api

Rate limiting

All /api/ endpoints are rate-limited per client IP using a sliding window (default: 60 requests/minute). Dashboard and static routes are not rate-limited.

Variable	Default	Description
GUARD_RATE_LIMIT_ENABLED	true	Enable/disable rate limiting
GUARD_RATE_LIMIT_RPM	60	Requests per minute per IP

When exceeded, the server returns 429 Too Many Requests with a Retry-After header.

Core endpoints

GET /health

Health check. Always accessible (no auth required).

{"status": "ok", "version": "1.0.0"}

POST /scan

Scan code and return findings.

Request body:

Field	Type	Required	Description
repo_path	string	No	Path to repository (default: .)
files	object	No	Map of file path to content for inline scanning
changed_files	string[]	No	Limit scan to these files
config_overrides	object	No	Override .guard.yaml settings

Response: { findings: [...], total: N, by_severity: {...} }

POST /gate

Scan code and return pass/fail gate result.

Request body: Same as /scan.

Response: { passed: bool, total_findings: N, critical: N, high: N, ... }

POST /report

Generate a report. Query param format: html, junit, sarif.

Response: { format: "html", content: "..." }

GET /rules

List all configured rules.

Response: { rules: [...], total: N }

Configuration endpoints

Endpoint	Method	Description
/api/config	GET	Get current configuration
/api/config	POST	Update configuration
/api/config/validate	GET	Validate configuration
/api/metrics	GET	Get scan metrics (includes false_positive_rate)
/api/posture	GET	Aggregate security posture score (ASPM)
/api/trends	GET	Get scan trend data

Governance endpoints

Endpoint	Method	Description
/api/governance	GET	Get governance settings
/api/governance	POST	Update governance settings
/api/audit	GET	Get audit log entries
/api/license	GET	Get license information

Standards pack endpoints

Endpoint	Method	Description
/api/packs	GET	List all packs
/api/packs	POST	Create a custom pack
/api/packs/{id}	DELETE	Delete a custom pack
/api/packs/{id}/export	GET	Export pack as YAML
/api/packs/import	POST	Import a pack from YAML
/api/packs/{id}/overrides	POST	Set pack rule overrides

DevOps endpoints

Endpoint	Method	Description
/api/work-items	GET	List work items
/api/reconcile	POST	Reconcile findings with work items
/api/devops/test-connection	POST	Test DevOps provider connectivity
/api/devops/status	GET	Get DevOps connection status

Requirements endpoints

Endpoint	Method	Description
/api/generate-reqs	POST	Auto-generate requirements from code
/api/check-coverage	GET	Check requirement coverage

Findings & reporting endpoints

Endpoint	Method	Description
/api/findings	GET	Get scan findings
/api/suppressions	GET	Get active suppressions
/api/compliance-report	GET	Generate per-framework compliance report (HTML)
/api/trust-center	GET	Generate public-safe trust center page
/api/audit/runs	GET	List historical scan runs
/api/audit/runs/{run_id}/report	GET	Generate report for a past scan run

GET /api/compliance-report

Parameter	Type	Description
framework	string	Standard name filter (e.g. IEC 62304). Omit for all.
list	bool	If true, return available frameworks instead of report.

GET /api/trust-center

Returns a public-safe compliance summary (no file paths, code, or finding details).

Parameter	Type	Description
format	string	html (default) or json
org_name	string	Organization name for the page header

SBOM & supply chain endpoints

GET /api/sbom

Generate a Software Bill of Materials (SBOM) from dependency manifests detected in the project (e.g. requirements.txt, package.json).

Parameter	Type	Default	Description
format	string	cyclonedx	SBOM format: cyclonedx or spdx

Response: CycloneDX or SPDX JSON document with all detected components.

GET /api/vulns

Return vulnerability scan results. Reads cached results from out/vulnerabilities.json by default, or triggers a live scan against OSV.dev when refresh=true.

Parameter	Type	Default	Description
refresh	bool	false	Force a fresh scan instead of reading cached results

Response: { vulnerable_count: N, total_dependencies: N, vulnerabilities: [...] }

GET /api/vulns/report

Generate an HTML vulnerability report from cached or live scan results.

Response: { html: "...", vulnerable_count: N, total_dependencies: N }

GET /api/licenses

Return dependency license scan results. Detects project manifests, parses dependencies, and queries registries (PyPI, npm) for license metadata. Results are cached in out/licenses.json.

Parameter	Type	Default	Description
refresh	bool	false	Force a fresh license scan instead of reading cached results

Response: License scan result with per-dependency license information.

Compliance & evidence endpoints

GET /api/evidence-export

Generate an audit evidence package mapped to compliance framework controls.

Parameter	Type	Default	Description
framework	string	""	Framework name (e.g. SOC2, IEC 62304). Omit for framework list.
format	string	json	Output format: json or html
list	bool	false	If true, return available frameworks instead of evidence

Response (list=true or no framework): { frameworks: ["SOC2", "IEC 62304", ...] }

Response (json): Evidence package with items mapped to framework controls.

Response (html): { html: "...", framework: "SOC2" }

GET /api/impact

Analyze which rules, requirements, and frameworks are affected by changed files.

Parameter	Type	Default	Description
git_range	string	""	Git range for diff (e.g. origin/main...HEAD)
staged	bool	false	Analyze staged changes instead of a git range

Response: Impact analysis report with affected rules, requirements, and frameworks.

GET /api/posture

Return the aggregate Application Security Posture Management (ASPM) score. Combines four weighted components into a single 0–100 score with status labels.

Response:

{
  "overall": 78.5,
  "status": "needs_attention",
  "components": {
    "compliance": {"score": 92.0, "weight": 0.35},
    "vulnerability": {"score": 60.0, "weight": 0.30},
    "trend": {"score": 65.0, "weight": 0.15},
    "gate_reliability": {"score": 85.0, "weight": 0.20}
  },
  "details": { ... }
}

Status values: healthy (≥80), needs_attention (≥60), at_risk (≥40), critical (<40).

GET /api/metrics/history

Return scan history and statistics from the metrics database.

Parameter	Type	Default	Description
days	int	90	Number of days of history (1–365)
limit	int	50	Maximum records to return (1–500)

Response: { scans: [...], trend: [...], compliance_trend: [...], stats: {...} }

SDK endpoints

Compliance checking endpoints designed for AI coding agents.

POST /api/sdk/check

Check code for compliance violations.

Request body:

Field	Type	Required	Description
code	string	Yes	Source code to check
filename	string	Yes	Filename for language detection and rule matching
frameworks	string[]	No	Limit checks to specific frameworks

Response: { compliant: bool, findings: [...], suggestions: [...], confidence: N }

GET /api/sdk/context

Return compliance context for a file (applicable rules, frameworks, requirements).

Parameter	Type	Required	Description
filename	string	Yes	Target file path (e.g. src/main.cpp)

Response: Compliance context object with applicable rules and framework mappings.

GET /api/sdk/rules

Return applicable rules for a file, optionally filtered by framework.

Parameter	Type	Required	Description
filename	string	Yes	Target file path (e.g. src/main.cpp)
frameworks	string	No	Comma-separated framework names (e.g. HIPAA,SOC2)

Response: List of rules that apply to the given file.

Organization endpoints

GET /api/org/projects

Aggregate compliance data across multiple repositories under an organization root directory.

Parameter	Type	Default	Description
root	string	Parent of cwd	Root directory containing sub-projects

Response: Per-project compliance data with aggregated organization-level statistics.

Auditor portal endpoints

Time-boxed, read-only access for external auditors. Tokens are generated via sentrik auditor-token CLI.

GET /auditor

Serve the auditor portal HTML page. The page handles token validation client-side via the /api/auditor/portal-data endpoint.

Parameter	Type	Description
token	string	Auditor access token (passed as query param, read by the page JS)

Response: HTML page.

GET /api/auditor/portal-data

Return read-only portal data for a valid auditor token. No source code, full file paths, configuration secrets, or API keys are included in the response.

Parameter	Type	Required	Description
token	string	Yes	Auditor access token

Response: { auditor_name, auditor_email, expires_at, access_scope, metrics, findings_by_rule, frameworks, audit_log, trends } — fields present depend on the token's access_scope.

GET /api/auditor/download

Download a report for a valid auditor token. Requires evidence in the token's access scope.

Parameter	Type	Required	Description
token	string	Yes	Auditor access token
type	string	No	Report type: compliance (default), evidence, or trust-center

Response: HTML report content.

Requirements endpoints

POST /api/pull-reqs

Pull requirements from the configured DevOps provider into requirements.yaml.

Parameter	Type	Default	Description
merge	bool	false	Merge with existing requirements instead of overwriting
map-files	bool	false	Auto-map requirements to source files

Response: { status, requirements: [...], requirements_file, count, provider }

OAuth endpoints

Connect to DevOps providers (Azure DevOps, GitHub, Jira) via OAuth instead of managing PATs manually. Valid provider values: azure, github, jira.

GET /oauth/{provider}/connect

Initiate the OAuth authorization flow. Redirects the user to the provider's login page. Returns an error redirect to /dashboard?oauth_error=... if the client ID is not configured.

GET /oauth/{provider}/callback

Handle the OAuth callback from the provider after user authorization. Exchanges the authorization code for access/refresh tokens, stores them locally in .sentrik/local/oauth_tokens.json, and redirects to /dashboard?oauth_success={provider}.

Parameter	Type	Description
code	string	Authorization code from the provider
state	string	CSRF state parameter
error	string	Error code if authorization was denied

POST /oauth/{provider}/disconnect

Remove stored OAuth tokens for a provider.

Response: { status: "ok", message: "Disconnected from {provider}" }

GET /api/oauth/status

Return OAuth connection status for all providers.

Response: { azure: {...}, github: {...}, jira: {...} } — each value contains connection status details.

SSE endpoint

Endpoint	Method	Description
/api/run-scan-stream	POST	Scan with real-time progress via SSE

Approval endpoints (Enterprise)

Endpoint	Method	Description
/api/approvals	GET	List approval requests
/api/approvals/{id}	GET	Get approval request details
/api/approvals/{id}	PATCH	Approve or reject a request
/api/approvals/{id}/status	GET	Get approval status

Error handling

Status	Meaning
200	Success
400	Bad request
401	Invalid or missing API key
403	Insufficient permissions
422	Validation error
429	Rate limit exceeded (includes Retry-After header)
500	Internal server error

Error response format:

{"detail": "Error description"}

Note: Error responses never include internal file paths, stack traces, or library versions. Full error details are logged server-side only.

AI assistant & fix endpoints

These endpoints require API key authentication when GUARD_API_KEY is set.

Endpoint	Method	Description
/api/ai-key	POST	Set LLM API key for current session (in-memory only)
/api/vuln-fix	POST	Apply a dependency version fix to a manifest
/api/apply-fix	POST	Apply a code fix to a source file (path-traversal protected)

POST /api/apply-fix

Apply a code fix suggested by the AI chat assistant. The endpoint enforces path traversal protection — the target file must be within the project root, and symlinks that escape the root are rejected.

Field	Type	Required	Description
file_path	string	Yes	Relative path within the project
original_code	string	No	Expected original code (soft verification)
fixed_code	string	Yes	Replacement code
start_line	int	Yes	Start line number
end_line	int	Yes	End line number

Security notes

• API key comparison uses hmac.compare_digest() for constant-time validation (prevents timing attacks)
• OAuth tokens are encrypted at rest using Fernet symmetric encryption with a machine-derived PBKDF2 key
• Audit log entries include HMAC-SHA256 integrity signatures (_integrity field) — tampered entries are flagged on read
• CSRF state validation on OAuth callbacks requires both cookie presence and value match
• Pack import validation enforces regex pattern length limits (2000 chars) to prevent ReDoS