API Reference

This page is auto-generated from Zod schema source files by scripts/generate-api-docs.ts. Run pnpm docs:api to regenerate.

Generated: 2026-02-24T08:36:31.355Z

CALMGuard exposes three API routes. All routes are Next.js App Router API routes in src/app/api/.

Method	Path	Purpose
POST	/api/analyze	Run full analysis — returns SSE stream
POST	/api/calm/parse	Validate CALM document — no AI
GET	/api/pipeline	Retrieve last generated pipeline config

POST /api/analyze

Runs the full 4-agent analysis pipeline on a CALM architecture document. Returns a Server-Sent Events (SSE) stream (text/event-stream).

Events stream in real-time as agents execute. The stream closes after a terminal done or error event.

Note: This is an SSE endpoint, not a standard JSON endpoint. Use EventSource in the browser or any SSE client.

Status Codes

Code	Description
200	SSE stream opened. Events stream until analysis completes.
400	Invalid request body or invalid CALM document.
500	Catastrophic failure before stream could open.

Request Body (AnalyzeRequest)

Content-Type: application/json

Field	Type	Required	Description
calm	CalmDocument	Yes	The CALM architecture JSON to analyze
frameworks	string[]	No	Compliance frameworks to evaluate: "SOX"

Response Body (SSE Events)

Field	Type	Required	Description
message	string	No	—
data	any	No	—
timestamp	string	Yes	—

Example Request

{
  "calm": {
    "nodes": [
      {
        "unique-id": "svc-1",
        "node-type": "service",
        "name": "Payment API",
        "description": "Handles payments"
      }
    ],
    "relationships": []
  },
  "frameworks": [
    "PCI-DSS",
    "SOX"
  ]
}

Example Response

data: {"type":"started","agent":{"name":"architecture-analyzer","displayName":"Architecture Analyzer","icon":"search","color":"#8b5cf6"},"timestamp":"2026-02-24T10:00:00Z"}

data: {"type":"finding","agent":{...},"message":"Missing encryption controls on service node","severity":"high","timestamp":"2026-02-24T10:00:02Z"}

data: {"type":"done","result":{"score":65,"findings":[...],"pipeline":{...}}}

---

POST /api/calm/parse

Validates and parses a CALM JSON document without running AI agents. Use this endpoint for pre-flight validation before triggering a full analysis.

Returns the parsed AnalysisInput (structured representation of the CALM document) on success, or a ParseError with field-level validation issues on failure.

Status Codes

Code	Description
200	CALM document is valid. Returns success=true with data as AnalysisInput.
400	Invalid request body or CALM validation failure. Returns error and details.

Request Body (ParseRequest)

Content-Type: application/json

Field	Type	Required	Description
calm	unknown	Yes	The CALM JSON to validate. Any shape is accepted — validation reports issues.

Response Body (ParseResponse)

Field	Type	Required	Description
success	boolean	Yes	Whether the CALM document is valid
data	AnalysisInput	No	Parsed analysis input (present when success=true)
error	string	No	Error message (present when success=false)
details	ParseError	No	Field-level validation issues (present when success=false)

Example Request

{
  "calm": {
    "nodes": [],
    "relationships": []
  }
}

Example Response

{
  "error": "Invalid CALM document",
  "details": {
    "issues": [
      {
        "path": [
          "nodes"
        ],
        "message": "Array must contain at least 1 element(s)"
      }
    ]
  }
}

---

GET /api/pipeline

Returns the pipeline configuration generated by the most recent analysis.

The pipeline result is stored in memory (globalThis.__lastPipelineResult) after a successful /api/analyze call. This endpoint retrieves it.

Note: This is ephemeral in-memory storage. The pipeline result is lost on server restart. In production, pipeline configs should be persisted to a database.

Status Codes

Code	Description
200	Returns the PipelineConfig JSON.
404	No pipeline result available. Run /api/analyze first.

Example Response

{
  "githubActions": {
    "name": "Security Scanning",
    "on": {
      "push": {
        "branches": [
          "main"
        ]
      },
      "pull_request": {}
    },
    "jobs": {
      "security": {
        "runs-on": "ubuntu-latest",
        "steps": [
          {
            "name": "Checkout",
            "uses": "actions/checkout@v4"
          },
          {
            "name": "Run Trivy",
            "uses": "aquasecurity/trivy-action@master",
            "with": {
              "scan-type": "fs",
              "format": "sarif"
            }
          }
        ]
      }
    }
  }
}

---

Error Response Format

All non-SSE error responses follow this shape:

{
  "error": "Description of the error",
  "issues": [
    {
      "path": [
        "field"
      ],
      "message": "Validation message"
    }
  ]
}

CALM Document Schema

The CALM document schema is defined in src/lib/calm/types.ts using Zod. See Uploading Architectures for the full structure.

Agent Event Schema

Defined in src/lib/agents/types.ts:

type AgentEventType = 'started' | 'thinking' | 'finding' | 'completed' | 'error';
type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';

interface AgentEvent {
  type: AgentEventType;
  agent: {
    name: string;
    displayName: string;
    icon: string;
    color: string;
  };
  message?: string;
  severity?: Severity;
  data?: unknown;
  timestamp: string; // ISO 8601
}