From 09eb22af6284d026a2e4a01e6d054fbf693ea355 Mon Sep 17 00:00:00 2001
From: Max Mayfield <max@dd0c.net>
Date: Mon, 2 Mar 2026 05:42:27 +0000
Subject: [PATCH] Add comprehensive API reference doc for all 6 products

---
 products/API.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 products/API.md

diff --git a/products/API.md b/products/API.md
new file mode 100644
index 0000000..726832b
--- /dev/null
+++ b/products/API.md
@@ -0,0 +1,108 @@
+# dd0c API Reference
+
+All endpoints require JWT authentication via `Authorization: Bearer <token>` unless noted.
+
+Base URLs (NAS): `http://192.168.86.11:{port}`
+
+## Auth (all products)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/v1/auth/signup` | Create account. Body: `{email, password, tenant_name}` → `{token, tenant_id}` |
+| POST | `/api/v1/auth/login` | Login. Body: `{email, password}` → `{token}` |
+| GET | `/api/v1/auth/me` | Current user info |
+| POST | `/api/v1/auth/api-keys` | Generate API key → `{api_key}` |
+
+API keys: pass via `X-API-Key` header.
+
+---
+
+## dd0c/drift (:3002)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/stacks` | List monitored stacks (latest report per stack) |
+| GET | `/api/v1/stacks/:stackName/history` | Drift history for a stack (last 50 reports) |
+| GET | `/api/v1/reports/:reportId` | Get single drift report |
+| POST | `/api/v1/reports` | Submit drift report. Body: `{stack_name, stack_fingerprint, state_serial, total_resources, drift_score, raw_report}` |
+| DELETE | `/api/v1/stacks/:stackName` | Delete all reports for a stack |
+| GET | `/api/v1/dashboard` | Dashboard summary (total stacks, drifted, critical last 24h) |
+
+---
+
+## dd0c/alert (:3003)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/incidents` | List incidents |
+| GET | `/api/v1/incidents/:id` | Get incident detail |
+| POST | `/api/v1/incidents/:id/acknowledge` | Acknowledge incident |
+| POST | `/api/v1/incidents/:id/resolve` | Resolve incident |
+| POST | `/api/v1/incidents/:id/suppress` | Suppress incident |
+| GET | `/api/v1/summary` | Alert summary (open totals by severity) |
+| GET | `/api/v1/notifications` | List notification configs |
+| PUT | `/api/v1/notifications/:channel` | Set notification config. Body: `{enabled, config, min_severity}` |
+| POST | `/api/v1/notifications/:channel/test` | Send test notification |
+| GET | `/api/v1/webhooks/secrets` | List webhook integration secrets |
+| PUT | `/api/v1/webhooks/secrets` | Register webhook secret. Body: `{provider, secret}` |
+| DELETE | `/api/v1/webhooks/secrets/:provider` | Delete webhook secret |
+
+**Webhook endpoints (no auth — HMAC validated):**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/webhooks/datadog/:tenantSlug` | Datadog webhook receiver |
+| POST | `/webhooks/pagerduty/:tenantSlug` | PagerDuty webhook receiver |
+| POST | `/webhooks/opsgenie/:tenantSlug` | OpsGenie webhook receiver |
+| POST | `/webhooks/grafana/:tenantSlug` | Grafana webhook receiver (Bearer token) |
+
+---
+
+## dd0c/portal (:3004)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/services` | List services |
+| GET | `/api/v1/services/:id` | Get service detail |
+| PUT | `/api/v1/services` | Create/update service. Body: `{name, description, owner, tier, language, repo_url, tags}` |
+| DELETE | `/api/v1/services/:id` | Delete service |
+| GET | `/api/v1/ownership` | Ownership report |
+| GET | `/api/v1/search?q=` | Search services (Meilisearch with PG fallback) |
+| POST | `/api/v1/search/reindex` | Trigger Meilisearch reindex |
+| POST | `/api/v1/discovery/aws` | Trigger AWS discovery scan |
+| POST | `/api/v1/discovery/github` | Trigger GitHub discovery scan |
+| GET | `/api/v1/discovery/history` | Scan history (last 20) |
+| GET | `/api/v1/discovery/staged` | List pending staged updates |
+| POST | `/api/v1/discovery/staged/:id/:action` | Apply or reject staged update |
+
+---
+
+## dd0c/cost (:3007)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/v1/ingest` | Ingest cost events. Body: `{events: [{account_id, resource_type, hourly_cost, region, tags}]}` |
+| GET | `/api/v1/anomalies` | List detected anomalies |
+| POST | `/api/v1/anomalies/:id/acknowledge` | Acknowledge anomaly |
+| POST | `/api/v1/anomalies/:id/snooze` | Snooze anomaly |
+| POST | `/api/v1/anomalies/:id/expected` | Mark anomaly as expected |
+| GET | `/api/v1/baselines` | List Welford baselines |
+| DELETE | `/api/v1/baselines/:accountId/:resourceType` | Reset baseline |
+| GET | `/api/v1/dashboard` | Cost dashboard |
+| GET | `/api/v1/governance` | Governance rules |
+| POST | `/api/v1/governance/promotion` | Promote governance rule |
+
+---
+
+## dd0c/run (:3006)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/runbooks` | List runbooks |
+| GET | `/api/v1/runbooks/:id` | Get runbook detail |
+| POST | `/api/v1/runbooks` | Create runbook. Body: `{name, description, yaml_content}` |
+| POST | `/api/v1/runbooks/:id/execute` | Execute runbook. Body: `{dry_run?, variables?}` → `{execution_id, status}` |
+| GET | `/api/v1/runbooks/:id/executions` | List executions for a runbook |
+| GET | `/api/v1/executions/:executionId` | Get execution status |
+| GET | `/api/v1/approvals` | List pending approvals |
+| POST | `/api/v1/approvals/:stepId` | Approve or reject step |