{"openapi":"3.1.0","info":{"title":"ArchTruth API","version":"1.0.0","description":"Create, read, patch, search and render diagrams. Authenticate with an org-scoped API key: `Authorization: Bearer as_live_…`. Writes require a write-scope key and honour `If-Match: <revision>` (412 on mismatch). The same operations are exposed as MCP tools at /api/mcp."},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer"}},"schemas":{"DiagramSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"revision":{"type":"integer"}},"required":["id","name","updatedAt","revision"]},"Diagram":{"allOf":[{"$ref":"#/components/schemas/DiagramSummary"},{"type":"object","properties":{"dsl":{"type":"string"},"layout":{"type":"object","additionalProperties":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/Diagnostic"}},"layers":{"type":"array","items":{"type":"string"}}},"required":["dsl","layout","diagnostics","layers"]}]},"Diagnostic":{"type":"object","properties":{"line":{"type":"integer"},"message":{"type":"string"},"severity":{"type":"string","enum":["error","warning"]}}},"Op":{"type":"object","description":"A typed edit. `op` is one of addNode, removeNode, setNode, moveNode, addEdge, removeEdge, setEdge, setTitle, setDiagramProps, addLayer, removeLayer, setLayer. add/remove node/edge accept `layer` to target a layer.","properties":{"op":{"type":"string"}},"required":["op"],"additionalProperties":true},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"security":[{"apiKey":[]}],"paths":{"/diagrams":{"get":{"summary":"List diagrams","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"diagrams":{"type":"array","items":{"$ref":"#/components/schemas/DiagramSummary"}}}}}}}}},"post":{"summary":"Create a diagram from DSL (write scope)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"dsl":{"type":"string"}},"required":["name","dsl"]}}}},"responses":{"201":{"description":"Created","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Diagram"}}}},"422":{"description":"DSL has errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get DSL, layout, diagnostics","responses":{"200":{"description":"OK","headers":{"ETag":{"description":"revision","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Diagram"}}}},"404":{"description":"Not found"}}},"patch":{"summary":"Apply typed ops (write scope)","parameters":[{"name":"If-Match","in":"header","schema":{"type":"string"},"description":"Revision the edit is based on; 412 when stale"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ops":{"type":"array","items":{"$ref":"#/components/schemas/Op"}},"message":{"type":"string"}},"required":["ops"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Diagram"}}}},"412":{"description":"Revision mismatch"},"422":{"description":"Op failed or produced invalid DSL"}}},"put":{"summary":"Replace DSL text (write scope)","parameters":[{"name":"If-Match","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dsl":{"type":"string"},"message":{"type":"string"}},"required":["dsl"]}}}},"responses":{"200":{"description":"Updated"},"412":{"description":"Revision mismatch"},"422":{"description":"DSL has errors"}}}},"/diagrams/{id}/render":{"get":{"summary":"Render SVG","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"layer","in":"query","schema":{"type":"string"},"description":"Resolve this layer over the base"}],"responses":{"200":{"description":"SVG","content":{"image/svg+xml":{"schema":{"type":"string"}}}}}}},"/search":{"get":{"summary":"Search names and DSL lines","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/validate":{"post":{"summary":"Parse DSL without saving","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dsl":{"type":"string"}},"required":["dsl"]}}}},"responses":{"200":{"description":"ok + diagnostics + stats"}}}}}}