Reference

Diagram Import Format

This is the real, currently-supported JSON format accepted by POST /api/ingest — the same payload the diagram editor sends when you click Analyze. You can build this JSON yourself (from a script, CI pipeline, or another tool) and POST it directly.

Not yet available

Importing UML diagrams, Mermaid/PlantUML diagram-as-code, or drawio/Visio files is on the roadmap but not built yet. The format below (a plain JSON graph) is the only supported import path today — the editor draws it visually, but the format itself is provider/tool agnostic and you're welcome to generate it programmatically.

Top-level request

Field	Type	Notes
diagrams	Diagram[]	At least one. See below.

Diagram object

Field	Type	Notes
clientId	string	Any unique string you choose — echoed back in the response.
level	"l1" \| "l2" \| "l3"	System context, service-level, or infra-level.
name	string	Diagram title.
parentDiagramClientId	string \| null	For L2/L3 diagrams that drill into a parent element.
parentElementClientId	string \| null	Which element in the parent diagram this drills into.
dfd	{ elements, dataFlows }	See below.

Element object (`dfd.elements[]`)

Field	Type	Notes
id	string	Unique within this diagram; referenced by dataFlows.
type	"process" \| "data_store" \| "external_entity"	The abstract STRIDE element type the rule engine keys off.
kind	string (optional)	Taxonomy label — e.g. "web_app", "database", "worker", "auth_service". Drives which rules apply and default icon.
name	string
description	string (optional)
attributes	{ [key]: string \| boolean }	Rule-relevant flags, e.g. `encryptionAtRest`, `mfaEnforced`, `publicAccess`. Also where cloud provider/service selection lives (`provider`, `service`).

Data flow object (`dfd.dataFlows[]`)

Field	Type	Notes
from / to	string	Element ids within the same diagram.
protocol	string (optional)	e.g. "HTTPS", "gRPC", "TCP".
authMechanism	string (optional)	Leave unset/empty to signal "no auth" — the rule engine treats blank the same as "none".
dataClassification	string (optional)
crossesBoundary	boolean	Any flow touching an external entity is automatically treated as boundary-crossing regardless of this value.

Worked example

{
  "diagrams": [
    {
      "clientId": "l1-root",
      "level": "l1",
      "name": "System Context (L1)",
      "parentDiagramClientId": null,
      "parentElementClientId": null,
      "dfd": {
        "elements": [
          {
            "id": "sys1",
            "type": "process",
            "kind": "system",
            "name": "Checkout System",
            "attributes": {}
          },
          {
            "id": "ext1",
            "type": "external_entity",
            "kind": "external_entity",
            "name": "Customer",
            "attributes": { "hasWriteAccess": true }
          }
        ],
        "dataFlows": [
          {
            "from": "ext1",
            "to": "sys1",
            "protocol": "HTTPS",
            "authMechanism": "oauth2",
            "crossesBoundary": true
          }
        ]
      }
    }
  ]
}