API overview

The SARC portal exposes a REST API at /api/*, an MCP server at /api/mcp/*, and webhook ingest endpoints at /api/webhooks/*.

Authentication

Three authentication paths, depending on caller:

Caller	Auth	Header
Browser session (operator using the portal)	NextAuth session cookie	`Cookie: next-auth.session-token=...`
External AI client (Claude Desktop, Cursor)	Portal Access Token (PAT)	`Authorization: Bearer karc_pat_...`
External AI client via OAuth 2.1	OAuth bearer	`Authorization: Bearer eyJ...`
CI webhook	HMAC-SHA256 over body	`x-karc-signature: <hex>`

PATs are issued at /t/<tenant>/settings/api-tokens. OAuth issuer config is at /t/<tenant>/settings/mcp-oauth. Webhook secrets are rotated from /t/<tenant>/settings/webhooks.

High-level API map

Read endpoints

Path	Returns
`GET /api/dashboard`	Per-env release health, latest deploys, pending CRs
`GET /api/compliance/status`	Per-framework summary (pass/fail/skipped counts)
`GET /api/compliance/controls`	All controls for the tenant (global + overrides)
`GET /api/services`	Service catalogue
`GET /api/services/[slug]`	Service detail + dependencies
`GET /api/cmdb/{ci_type}`	ServiceNow CMDB browse
`GET /api/change-requests`	ServiceNow CRs (paginated)
`GET /api/change-requests/[id]`	CR detail incl. 5-axis risk + Kosli evidence chain
`GET /api/timeline`	SSE stream of every deploy/CR/Kosli/ArgoCD event
`GET /api/audit`	Hash-chained audit log
`GET /api/vulnerabilities`	Aggregated vuln list
`GET /api/sbom/[id]`	SBOM document
`GET /api/costs/services`	Per-service cost from Cost Explorer / Cost Management / Billing
`GET /api/costs/chargeback`	Per-team chargeback report
`GET /api/argocd/[cluster]`	ArgoCD application list per cluster
`GET /api/tekton/[cluster]`	Tekton PipelineRun list per cluster
`GET /api/dora`	DORA metrics for the tenant

Write endpoints (gated)

Path	Purpose	Gate
`POST /api/compliance/evidence/generate`	Generate evidence pack (JSON + PDF)	ADMIN; rate-limited 5/h/tenant
`POST /api/agents/run`	Dispatch an agent recipe	ADMIN; per-tenant rate-limit
`POST /api/mcp/propose`	MCP gateway — propose a write (dry-run)	non-AUDITOR; `mcp.gateway` flag
`POST /api/mcp/execute`	MCP gateway — ADMIN-approved write	ADMIN; argsSha anti-tamper
`POST /api/audit/verify-chain`	Verify the hash chain over the AuditLog	any role
`POST /api/webhooks/agent-dispatch`	Receive CI state transition for an AgentDispatch	HMAC-SHA256
`POST /api/webhooks/policy-result`	Receive Kyverno PreSync policy result	per-tenant secret

MCP server

/api/mcp is the MCP server for external AI clients. Exposes 12 read tools + 3 prompts. Tools list:

get_compliance_status
get_change_request
list_change_requests
get_problem
list_problems
get_service
list_services
get_sla_compliance
list_deployments
list_audit_log
list_release_notes
list_vulnerabilities

Use mcp_protocol_version: 2024-11-05. See MCP Gateway runbook for the write-path equivalent (Phase 1: GitHub issue_write only).

SDKs

None today. The portal API surface follows REST conventions; any HTTP client works. The MCP server speaks standard Model Context Protocol so any MCP client library works — Claude Desktop, Cursor, the Anthropic SDK, etc.

Versioning

The API surface is not versioned today. Breaking changes are announced in release notes (/releases). Customer engagements pin to a specific portal image SHA, so the API for a given install never changes underneath the customer mid-engagement.