See what the current API covers, how it is validated, and where integration support is going next.
Use this page to review the current local API surface, runtime validation notes, auth and error expectations, and the related reference pages for implementation work.
Use now
Status, scans, accounts, notifications, reports, schedules, and MCP routes are already documented.
Validate first
Check HTTPS mode, bearer token requirements, and local runtime behavior before automation rollout.
Plan next
Track OpenAPI, SDK, webhook signing, and compatibility governance on a single page.
Docs > API & Automation > API Overview
Use this as the API entry point, then move to reference, tokens, errors, and playbooks in order.
Current API Coverage
The currently available local API covers secure settings management, scan orchestration, Kubernetes/container waste scanning, findings and reports, notifications, schedules, webhooks, and MCP bridge routes.
GET /statusfor health checks./v1/settings/*for general, network, scan policy, and license snapshot controls./v1/cloud-accounts*,/v1/proxies*, and/v1/notifications*for operator configuration./v1/scans*,/v1/findings*,/v1/scan-history*, and/v1/reports*for scan and evidence lifecycle./v1/k8s/*,/v1/reports/k8s-*, and/v1/mcp/tools/k8s-*for local Kubernetes/container inventory, findings, governance reports, and action planning./v1/events*,/v1/webhooks*, and/v1/schedules*for event-driven automation./v1/mcp/*for MCP beta capability and tool endpoints.
Scan contract note: POST /v1/scans supports full-scope mode (no body or {}), targeted mode (selected_accounts), and optional Kubernetes fields (include_kubernetes, kubeconfig_path, kube_context).
Runtime Validation Snapshot
Validated against a live local API runtime on March 2, 2026 (https://192.168.1.4:9098, self-signed TLS, bearer auth enabled).
- Contract suite result: 14 passed.
- Transport requirement: HTTPS with self-signed certificate accepted in local test mode.
- Auth requirement: all non-
/statusroutes requireAuthorization: Bearer <token>.
CWS_LOCAL_API_BASE_URL='https://192.168.1.4:9098' CWS_LOCAL_API_TOKEN='YOUR_TOKEN' CWS_LOCAL_API_INSECURE_TLS=1 ./scripts/test_local_api_contract.shAuthentication and Trust Boundary
All non-public routes require bearer token authentication. API exposure supports local-only and LAN modes with explicit host and token controls.
Error Contract
Diagnostic responses use a stable stage/reason/http shape so operators can distinguish proxy-connect, target-connect, auth, and provider-specific failures.
Expansion Tracks Now Available
These API expansion tracks are implemented in the current local API contract while preserving existing v1 clients.
1) OpenAPI Export
GET /v1/openapi.json returns a machine-readable OpenAPI 3.1 route contract generated from the active local API surface.
2) Official SDKs
Source-visible Python and TypeScript SDKs are included with the Community repository for local API calls, Kubernetes scans, pagination, and webhook verification.
3) Webhook Signing
Webhook deliveries include X-CWS-Event, X-CWS-Timestamp, and X-CWS-Signature when a secret is configured. Verify within a 300-second replay window.
4) Pagination and Filters
List endpoints keep legacy array responses by default. Add envelope=true or a cursor to receive {items,page} with next_cursor.
5) MCP Tool Expansion
MCP beta now exposes settings read/update, scan policy update, report list/retrieval, and Kubernetes governance/action-plan tools.
6) Compatibility Governance
GET /v1/meta/compatibility documents versioning, deprecation windows, pagination compatibility, and webhook signing semantics.
Recommended API Documentation Layout
Operator Policy
All API growth will keep local-first credential handling unchanged. Cloud credentials remain on-device, and API endpoints expose operational controls rather than raw secret exfiltration paths.
Validate the API against a real local runtime.
Save your first $1,000 before the next billing cycle.