Local API

Automate around local scan evidence.

Use the API to trigger scans, fetch findings, export reports, and feed results into weekly review, tickets, or internal dashboards. The surface stays small on purpose, but it is broad enough for real automation.

Scan jobs Findings Reports Webhooks OpenAPI

Quick start

Run one read-only scan locally, read the findings, then export a report for review. That sequence is enough for most teams to automate the first useful workflow.

Base URLLocal host
http://127.0.0.1:<configured-port>/v1
Example requestcurl
curl "http://127.0.0.1:8080/v1/findings?provider=aws&status=open"

What the API covers

  • Start and inspect scan jobs from the desktop app or an internal orchestrator.
  • Read findings, account metadata, provider summaries, and compatibility information.
  • Export PDF, CSV, JSON, or text evidence packages for finance and engineering review.
  • Deliver signed webhook callbacks when event-driven automation is needed.

Complete example: weekly waste handoff

Problem: finance asks why AWS network cost is still rising after the team says cleanup was finished. The useful API workflow is not one call; it is scan, filter, export, then notify the owner with evidence.

POST/v1/scans

Start a scoped scan for the AWS account and network waste policy.

GET/v1/findings?provider=aws&category=network&status=open

Read only open network findings, ranked by confidence and estimated monthly impact.

POST/v1/reports/export

Create a PDF for review and JSON for the ticketing or weekly governance system.

End-to-end workflowcURL
curl -X POST "http://127.0.0.1:8080/v1/scans" \
  -H "Authorization: Bearer $CWS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"aws","account_id":"prod-shared-services","policy_scope":["network-waste"]}'
OutputHow the team uses it
pdf_pathAttach to the weekly review note for finance and owners.
json_pathFeed into an internal ticket, dashboard, or AI evidence skill.
finding_idsKeep cleanup scoped to reviewed findings, not broad provider deletion.

Common endpoints

Discover capabilities

Use these first when building an internal client or checking whether a local app version supports the workflow you need.

GET/v1/openapi.json

Fetch the OpenAPI document for local integration and client generation.

GET/v1/meta/compatibility

Read app and API compatibility metadata before calling newer fields or routes.

Run and monitor scans

Trigger a scoped scan from an internal job, then poll state until findings and exports are ready.

POST/v1/scans

Start a scan using a configured provider account and policy scope.

GET/v1/scans/{id}

Check scan state, high-level counts, and whether export artifacts are ready.

GET/v1/findings

List findings with provider, status, severity, category, team, and cursor filters.

Build governance views

Pull enough summarized data for weekly review without copying every raw finding into another system.

GET/v1/reports/trends

Pull weekly trend lines for review cadence, closure, and savings movement.

GET/v1/reports/categories

Summarize the taxonomy behind the findings so teams can compare like with like.

GET/v1/reports/teams

See backlog and closure by team, owner, or business unit.

Export and automate handoff

Create evidence artifacts and test event delivery before connecting cleanup decisions to internal systems.

POST/v1/reports/export

Generate PDF, CSV, JSON, or text exports for tickets, weekly review, or audit notes.

POST/v1/webhooks/test

Verify webhook delivery and signature handling before wiring production automation.

Language examples

The same API can be called from scripts, jobs, or internal tools. These examples stay intentionally small.

cURL
Findingsbash
curl -H "Authorization: Bearer $CWS_TOKEN" \
  "http://127.0.0.1:8080/v1/findings?provider=aws&status=open"
JavaScript / TypeScript
Fetchjs
const res = await fetch("http://127.0.0.1:8080/v1/reports/trends?group_by=week", {
  headers: { Authorization: `Bearer ${token}` }
});
Python
Requestspy
import requests

res = requests.get(
    "http://127.0.0.1:8080/v1/reports/categories",
    headers={"Authorization": f"Bearer {token}"},
)
Go
net/httpgo
req, _ := http.NewRequest("GET", "http://127.0.0.1:8080/v1/scans/123", nil)
req.Header.Set("Authorization", "Bearer "+token)

Webhook signing

Webhook payloads use HMAC-SHA256 over the raw body and timestamp. Keep the signing secret inside the internal receiver and reject stale timestamps.

HeaderMeaning
X-CWS-TimestampEvent timestamp used to limit replay.
X-CWS-SignatureHMAC signature computed over the body and timestamp.
X-CWS-EventEvent type for the receiving system.

Errors and retries

  • Use cursor pagination for large result sets.
  • Retry transient network failures with backoff, not tight loops.
  • Check compatibility metadata before depending on new fields.
  • Prefer read-only scan access until your cleanup workflow is approved.

Safe integration

  • Do not expose the local API directly to the public internet.
  • Keep automation scoped to reviewed findings rather than broad deletion.
  • Attach report exports to tickets or review notes before cleanup.
  • Store tokens only in trusted internal systems.