{ "openapi": "3.1.1", "info": { "title": "Embeddable Chart Builder API", "version": "1.0.0", "summary": "Make a self-contained chart to embed anywhere: inline SVG, standalone HTML, accessible snippet.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://embeddablechartbuilder.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Make a self-contained chart to embed anywhere: inline SVG, standalone HTML, accessible snippet.", "description": "Paste a small table and get a chart you can host yourself: inline SVG markup, a
snippet with an accessible data-table fallback, a standalone .svg file and a standalone .html file with no external scripts (optionally with a tiny inline script for tooltips and keyboard focus).\n\nMethodology:\n- The data is parsed like the CSV/Excel Chart Studio (delimiter, number formats and dates detected automatically) and drawn with the site’s deterministic SVG chart library: Okabe–Ito colours, dash patterns, a /<desc> text alternative and role=\"img\".\n- The SVG is passed through a strict allow-list sanitiser, so the markup contains no scripts, event handlers, external links or style attributes and can be pasted into most CMSs.\n- The <figure> snippet keeps the data accessible: the SVG is labelled by its title and description, the caption carries the source line, and a <details> element holds the full data table as a fallback for screen readers, text browsers and copy-paste.\n- The standalone HTML file contains everything inline (a few lines of CSS; with the interactive option a ~1 KB vanilla script that makes data marks focusable and shows their values). It loads nothing from other servers.", "tags": [ "charts" ], "x-mcp-tool": "embeddable_chart_builder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddableChartBuilderInput" }, "examples": { "example1": { "summary": "Grouped bars with a source line", "value": { "data": "Fruit,2025,2026\nApples,12,15\nPears,9,11\nPlums,4,7", "chartType": "bar", "title": "Fruit sold (tonnes)", "yLabel": "tonnes", "sourceNote": "Source: example data" } }, "example2": { "summary": "Interactive donut", "value": { "data": "Channel,Visits\nSearch,5200\nDirect,2100\nSocial,1300\nEmail,600", "chartType": "donut", "title": "Visits by channel", "interactive": true } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddableChartBuilderResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "EmbeddableChartBuilderInput": { "type": "object", "additionalProperties": false, "properties": { "data": { "title": "Data", "description": "First row = headers. First column = labels (or dates/numbers for line and scatter charts); every further numeric column becomes a series.", "type": "string", "maxLength": 200000 }, "file": { "title": "Or upload CSV/XLSX", "description": "Max 5 MB; the first sheet is used. Upload as {filename, contentType?, contentBase64}. Max 5120 KiB. Accepts .csv,.tsv,.txt,.xlsx,text/csv,text/tab-separated-values,text/plain,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.", "type": "object", "additionalProperties": false, "required": [ "filename", "contentBase64" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "contentBase64": { "type": "string" } } }, "chartType": { "title": "Chart type", "type": "string", "enum": [ "line", "area", "bar", "stacked", "scatter", "pie", "donut" ], "default": "bar" }, "title": { "title": "Title", "type": "string", "maxLength": 140, "default": "My chart" }, "description": { "title": "Text alternative (description)", "description": "What the chart shows, for screen readers and as the image alt text. Empty: generated from the data.", "type": "string", "maxLength": 1000 }, "xLabel": { "title": "X axis label", "type": "string", "maxLength": 80 }, "yLabel": { "title": "Y axis label", "type": "string", "maxLength": 80 }, "sourceNote": { "title": "Source / credit line", "description": "Shown under the chart, e.g. \"Source: Eurostat, 2026\".", "type": "string", "maxLength": 200 }, "width": { "title": "Width", "description": "The SVG scales to its container; this sets the aspect ratio and text size.", "type": "integer", "minimum": 320, "maximum": 1600, "default": 640, "x-unit": "px" }, "height": { "title": "Height", "type": "integer", "minimum": 200, "maximum": 1200, "default": 360, "x-unit": "px" }, "interactive": { "title": "Add hover/keyboard tooltips to the standalone HTML file", "type": "boolean", "default": false }, "png": { "title": "Also create a PNG image", "type": "boolean", "default": false } }, "required": [ "title" ] }, "EmbeddableChartBuilderResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "chartType", "title", "categories", "series", "svgMarkup", "figureSnippet", "imgSnippet", "standaloneHtml", "interactive", "png" ], "properties": { "chartType": { "type": "string" }, "title": { "type": "string" }, "categories": { "type": "integer" }, "series": { "type": "array", "items": { "type": "string" } }, "svgMarkup": { "type": "string", "description": "Standalone SVG (sanitised, no scripts or external references)." }, "figureSnippet": { "type": "string", "description": "HTML <figure> with the inline SVG, caption and a data-table fallback." }, "imgSnippet": { "type": "string", "description": "<img> tag for a self-hosted copy of the SVG file." }, "standaloneHtml": { "type": "string", "description": "Complete HTML document (no external resources)." }, "interactive": { "type": "boolean" }, "png": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, { "type": "null" } ] } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }