{ "openapi": "3.1.1", "info": { "title": "Technical Diagrams API", "version": "1.0.0", "description": "Free, keyless, read-only visual references for agents. Search metadata, choose a recipe, retrieve editable scene JSON or an SVG. Scores are editorial judgments. No application-level quota; hosting limits and best-effort availability apply.", "license": { "name": "MIT", "identifier": "MIT" }, "contact": { "name": "Tom Granot", "url": "https://github.com/TomGranot/actually-useful-technical-diagrams/issues" } }, "servers": [ { "url": "https://technicaldiagrams.com", "description": "Canonical production domain" }, { "url": "https://actually-useful-technical-diagrams.netlify.app", "description": "Netlify production host" } ], "security": [], "paths": { "/api": { "get": { "operationId": "getApiDiscovery", "summary": "Discover the public API and agent entry points", "description": "Discover the public API and agent entry points. Use this to locate documentation and protocols.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown diagram or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/diagrams": { "get": { "operationId": "listDiagrams", "summary": "Search diagram references by query and family", "description": "Search diagram references by query and family. Compare useWhen and avoidWhen, then retrieve one scene by ID.", "parameters": [ { "name": "q", "in": "query", "description": "Case-insensitive search across name, description and use case.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "family", "in": "query", "description": "Exact family name from the catalog.", "schema": { "type": "string", "enum": [ "Architecture", "Flows", "Sequences", "Data structures", "Charts", "Time & planning", "Developer surfaces" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown diagram or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/diagrams/{id}": { "get": { "operationId": "getDiagram", "summary": "Retrieve one reference’s metadata and source links", "description": "Retrieve one reference’s metadata and source links. Use after selecting an ID from listDiagrams.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipe ID from listDiagrams.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recipe" } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown diagram or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/diagrams/{id}/scene": { "get": { "operationId": "getDiagramScene", "summary": "Retrieve an editable version-1 scene", "description": "Retrieve an editable version-1 scene. Adapt labels and coordinates locally with the documented parser and renderer.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipe ID from listDiagrams.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scene" } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown diagram or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/diagrams/{id}/svg": { "get": { "operationId": "renderDiagram", "summary": "Render an existing catalog reference as SVG", "description": "Render an existing catalog reference as SVG. Inspect the visual result; arbitrary edited scenes must be rendered locally.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipe ID from listDiagrams.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "theme", "in": "query", "description": "Background and semantic palette.", "schema": { "type": "string", "enum": [ "light", "dark", "paper" ], "default": "light" } }, { "name": "accent", "in": "query", "description": "Highlight color.", "schema": { "type": "string", "enum": [ "blue", "green", "orange", "rose" ], "default": "blue" } } ], "responses": { "200": { "description": "Successful response.", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown diagram or endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error", "documentation" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "hint" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } } }, "documentation": { "type": "string", "format": "uri" } } }, "Scene": { "type": "object", "required": [ "version", "width", "height", "title", "description", "elements" ], "properties": { "version": { "type": "integer", "const": 1 }, "width": { "type": "number", "minimum": 100, "maximum": 2400 }, "height": { "type": "number", "minimum": 100, "maximum": 2400 }, "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "elements": { "type": "array", "maxItems": 300, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "x", "y", "w", "h" ], "properties": { "type": { "type": "string", "const": "box" }, "x": { "type": "number", "minimum": -10000, "maximum": 10000 }, "y": { "type": "number", "minimum": -10000, "maximum": 10000 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 10000 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 10000 }, "fill": { "type": "string", "enum": [ "ink", "muted", "accent", "soft", "surface", "rule", "positive", "negative", "none" ] }, "stroke": { "type": "string", "enum": [ "ink", "muted", "accent", "soft", "surface", "rule", "positive", "negative", "none" ] }, "dashed": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "x", "y", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "x": { "type": "number", "minimum": -10000, "maximum": 10000 }, "y": { "type": "number", "minimum": -10000, "maximum": 10000 }, "text": { "type": "string", "maxLength": 500 }, "size": { "type": "number", "exclusiveMinimum": 0, "maximum": 10000 }, "fill": { "type": "string", "enum": [ "ink", "muted", "accent", "soft", "surface", "rule", "positive", "negative", "none" ] }, "align": { "type": "string", "enum": [ "start", "middle", "end" ] }, "mono": { "type": "boolean" }, "bold": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "x", "y", "x2", "y2" ], "properties": { "type": { "type": "string", "const": "line" }, "x": { "type": "number", "minimum": -10000, "maximum": 10000 }, "y": { "type": "number", "minimum": -10000, "maximum": 10000 }, "x2": { "type": "number", "minimum": -10000, "maximum": 10000 }, "y2": { "type": "number", "minimum": -10000, "maximum": 10000 }, "stroke": { "type": "string", "enum": [ "ink", "muted", "accent", "soft", "surface", "rule", "positive", "negative", "none" ] }, "arrow": { "type": "boolean" }, "dashed": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "d" ], "properties": { "type": { "type": "string", "const": "path" }, "d": { "type": "string", "maxLength": 20000, "pattern": "^[Mm][MmLlHhVvCcSsQqTtAaZz0-9eE.,+\\s-]+$" }, "fill": { "type": "string", "enum": [ "ink", "muted", "accent", "soft", "surface", "rule", "positive", "negative", "none" ] }, "stroke": { "type": "string", "enum": [ "ink", "muted", "accent", "soft", "surface", "rule", "positive", "negative", "none" ] }, "arrow": { "type": "boolean" }, "dashed": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "x", "y", "r" ], "properties": { "type": { "type": "string", "const": "circle" }, "x": { "type": "number", "minimum": -10000, "maximum": 10000 }, "y": { "type": "number", "minimum": -10000, "maximum": 10000 }, "r": { "type": "number", "exclusiveMinimum": 0, "maximum": 10000 }, "fill": { "type": "string", "enum": [ "ink", "muted", "accent", "soft", "surface", "rule", "positive", "negative", "none" ] }, "stroke": { "type": "string", "enum": [ "ink", "muted", "accent", "soft", "surface", "rule", "positive", "negative", "none" ] } } } ] } } } }, "Recipe": { "type": "object", "required": [ "id", "name", "family", "description", "useWhen", "avoidWhen", "primitives", "visual", "ease", "overall", "rationale", "reviewed", "revision", "status", "page", "scene", "svg" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "family": { "type": "string", "enum": [ "Architecture", "Flows", "Sequences", "Data structures", "Charts", "Time & planning", "Developer surfaces" ] }, "description": { "type": "string" }, "useWhen": { "type": "string" }, "avoidWhen": { "type": "string" }, "primitives": { "type": "array", "items": { "type": "string" } }, "visual": { "type": "integer", "minimum": 0, "maximum": 100 }, "ease": { "type": "integer", "minimum": 0, "maximum": 100 }, "overall": { "type": "integer", "minimum": 0, "maximum": 100 }, "rationale": { "type": "string" }, "reviewed": { "type": "string", "format": "date" }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "baseline" ] }, "page": { "type": "string" }, "scene": { "type": "string" }, "svg": { "type": "string" } } }, "Catalog": { "type": "object", "required": [ "version", "families", "recipes" ], "properties": { "version": { "type": "integer", "const": 1 }, "families": { "type": "array", "items": { "type": "string" } }, "recipes": { "type": "array", "items": { "$ref": "#/components/schemas/Recipe" } } } }, "Discovery": { "type": "object", "required": [ "name", "version", "authentication", "price", "openapi", "catalog", "mcp", "documentation" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "authentication": { "type": "string", "const": "none" }, "price": { "type": "number", "const": 0 }, "openapi": { "type": "string" }, "catalog": { "type": "string" }, "mcp": { "type": "string" }, "documentation": { "type": "string" } } } } } }