{ "openapi": "3.1.1", "info": { "title": "microcharts.dev", "version": "1.0.0", "summary": "Read-only endpoints describing the microcharts chart catalog and documentation.", "description": "Every endpoint here is a static document served from a CDN. All of them are GET, none of them need a key, and none of them rate-limit.\n\nTwo conventions apply site-wide and are worth knowing before you read the paths:\n\n- **Markdown twins.** Every page has one. Add `.md` to the URL, or send `Accept: text/markdown` to the page URL itself, and you get the same content as Markdown. Responses carry `Vary: Accept, Accept-Encoding`.\n- **Errors you can parse.** A 404, 405 or 406 answers with RFC 9457 problem details on this API surface, and with a short Markdown note anywhere else. Each one names where to look next.\n\nTo install the library itself, see https://microcharts.dev/docs/quickstart. To let a model call microcharts directly, run the MCP server: `npx -y @microcharts/mcp`.", "contact": { "name": "microcharts issues", "url": "https://github.com/ganapativs/microcharts/issues", "email": "vsg.inbox@gmail.com" }, "license": { "name": "MIT", "identifier": "MIT" } }, "externalDocs": { "description": "Documentation", "url": "https://microcharts.dev/docs" }, "servers": [ { "url": "https://microcharts.dev", "description": "Production" } ], "tags": [ { "name": "Catalog", "description": "The chart types, their props, and their data shapes." }, { "name": "Documentation", "description": "Pages and their Markdown twins." }, { "name": "Discovery", "description": "Files that map the site for agents and crawlers." } ], "paths": { "/api/charts.json": { "get": { "operationId": "listCharts", "tags": [ "Catalog" ], "summary": "List every chart type", "description": "One line per chart — name, slug, collection, tagline — plus the URLs that expand it. Fetch this to choose a chart, then fetch that chart's document for its props.", "responses": { "200": { "description": "Every chart type the package ships.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartIndex" } } } } } } }, "/api/charts/{slug}.json": { "get": { "operationId": "getChart", "tags": [ "Catalog" ], "summary": "Get one chart's full API surface", "description": "The chart's catalog entry, its shared props, and the instructions for combining the two. Self-contained: this is everything needed to write a correct chart, in about 8 kB rather than the 290 kB of the full catalog.", "parameters": [ { "$ref": "#/components/parameters/ChartSlug" } ], "responses": { "200": { "description": "The chart's props, imports, data shape, and caveats.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartDocument" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/catalog.json": { "get": { "operationId": "getCatalog", "tags": [ "Catalog" ], "summary": "Get the whole catalog in one document", "description": "All 106 charts with their props, imports, data shapes and caveats, plus the shared prop grammar. Prefer the per-chart endpoint unless you need the whole set.", "responses": { "200": { "description": "The full catalog.", "content": { "application/json": { "schema": { "$ref": "https://microcharts.dev/catalog.schema.json" } } } } } } }, "/catalog.schema.json": { "get": { "operationId": "getCatalogSchema", "tags": [ "Catalog" ], "summary": "Get the catalog's JSON Schema", "description": "The contract `/catalog.json` validates against, in CI. Draft 2020-12.", "responses": { "200": { "description": "JSON Schema for the catalog.", "content": { "application/schema+json": { "schema": { "type": "object" } } } } } } }, "/api/search": { "get": { "operationId": "getSearchIndex", "tags": [ "Discovery" ], "summary": "Get the documentation search index", "description": "The prebuilt full-text index the docs site searches in the browser. It is a whole index, not a query endpoint: fetch it once and search it locally. For a one-off lookup, `llms.txt` is smaller.", "responses": { "200": { "description": "Serialized search index.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "tags": [ "Discovery" ], "summary": "Get the agent index of this site", "description": "The llmstxt.org index: what the package is, every guide and chart page as a Markdown link, and the things the library deliberately does not do. Start here when mapping the site.", "responses": { "200": { "description": "Markdown index.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFull", "tags": [ "Discovery" ], "summary": "Get the entire documentation as one file", "description": "Every documentation page concatenated as Markdown, around 880 kB. Use it to load the whole corpus at once; use `llms.txt` to navigate.", "responses": { "200": { "description": "The full documentation text.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/agent-setup.md": { "get": { "operationId": "getAgentSetup", "tags": [ "Discovery" ], "summary": "Get the setup prompt for a coding agent", "description": "A paste-and-run prompt that installs the package, wires the stylesheet, and records the conventions an agent needs to write charts that compile.", "responses": { "200": { "description": "Setup instructions.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "tags": [ "Discovery" ], "summary": "Get this description", "description": "This document. Linked from every HTML and JSON response through the RFC 8631 `service-desc` link relation.", "responses": { "200": { "description": "This OpenAPI document.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/mcp/server-card.json": { "get": { "operationId": "getMcpServerCard", "tags": [ "Discovery" ], "summary": "Get the MCP server card", "description": "How to run the microcharts MCP server, as the MCP registry's `server.json` manifest. Served at the path MCP's draft server-card proposal uses, which is where agents look; the document itself follows the released registry schema. The server is stdio, so a client spawns `npx -y @microcharts/mcp` rather than connecting over HTTP.", "responses": { "200": { "description": "MCP server card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } } } } }, "/": { "get": { "operationId": "getHomePage", "tags": [ "Documentation" ], "summary": "Get the home page, as HTML or Markdown", "description": "Sends `Accept: text/markdown` and you get the Markdown twin from this same URL, which is also fetchable directly at `/index.md`. Every page route on this site behaves this way.", "parameters": [ { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "The page, in the representation you asked for.", "headers": { "Vary": { "description": "Always includes `Accept`, so caches key on it.", "schema": { "type": "string", "examples": [ "Accept, Accept-Encoding" ] } } }, "content": { "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/docs/charts/{slug}": { "get": { "operationId": "getChartPage", "tags": [ "Documentation" ], "summary": "Get a chart's documentation page", "description": "The human page for one chart. Send `Accept: text/markdown` for the Markdown twin, or fetch `/docs/charts/{slug}.md` directly.", "parameters": [ { "$ref": "#/components/parameters/ChartSlug" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "The page, in the representation you asked for.", "content": { "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/docs/charts/{slug}.md": { "get": { "operationId": "getChartMarkdown", "tags": [ "Documentation" ], "summary": "Get a chart's documentation as Markdown", "description": "The Markdown twin at its own URL, for clients that would rather not negotiate. Same bytes as `Accept: text/markdown` on the page.", "parameters": [ { "$ref": "#/components/parameters/ChartSlug" } ], "responses": { "200": { "description": "The page as Markdown.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sitemap.xml": { "get": { "operationId": "getSitemap", "tags": [ "Discovery" ], "summary": "Get every indexable URL", "description": "An XML sitemap with a real `lastmod` per URL, taken from the source file's last commit rather than build time.", "responses": { "200": { "description": "XML sitemap.", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/rss.xml": { "get": { "operationId": "getFeed", "tags": [ "Discovery" ], "summary": "Get the release feed", "description": "Every published version of the package as an Atom feed, newest first, with the changelog entry for each one. Poll this to notice a release without watching the repository.", "responses": { "200": { "description": "Atom feed.", "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } } }, "components": { "parameters": { "ChartSlug": { "name": "slug", "in": "path", "required": true, "description": "The chart's slug, as listed by `listCharts`.", "schema": { "type": "string", "enum": [ "ab-strips", "activity-grid", "balance-beam", "benchmark-strip", "bias-strip", "breathing-dot", "bubble-row", "bullet", "bump-strip", "burn-chart", "calendar-strip", "calibration-strip", "change-point", "city-skyline", "cohort-triangle", "comet-trail", "confusion-grid", "constellation", "control-strip", "coverage-strip", "cycle-plot", "data-diff", "delta", "depth-wedge", "dice-pips", "dot-plot", "dual-sparkline", "dual-window-meter", "dumbbell", "ensemble-ghosts", "error-budget", "eta-bar", "event-raster", "event-timeline", "fat-digits", "fill-word", "folded-day-band", "forecast-cone", "funnel", "garden-grid", "grade-profile", "graded-band", "heartbeat-blip", "heat-cell", "heat-strip", "histogram-strip", "honeycomb", "horizon", "hourglass", "hypnogram", "icon-array", "likert-strip", "micro-box", "micro-donut", "micro-scatter", "mini-bar", "minimap-strip", "moon-phase", "music-staff", "net-flow", "ohlc", "orbit-status", "paired-bars", "pareto-strip", "partition-strip", "percentile-ladder", "percentile-trace", "phase-trace", "pictogram-row", "polar-clock", "progress", "progress-ring", "quadrant-dot", "quantile-dots", "queue-depth", "rate-volume", "retention-curve", "rubric-strip", "rug-strip", "segmented-bar", "seismogram", "shift-histogram", "slope", "sparkbar", "sparkline", "spiral-year", "spread-band", "sprout-row", "stacked-area", "star-spoke", "station-glyph", "status-dot", "streak-spark", "tally-marks", "tape-gauge", "thermometer", "time-in-range", "token-confidence", "trace-fold", "tree-rings", "trend-arrow", "volume-profile", "waterfall", "waveform", "win-prob-worm", "wind-barb" ], "examples": [ "sparkline" ] } }, "Accept": { "name": "Accept", "in": "header", "required": false, "description": "`text/markdown` returns the Markdown twin; anything else, including `*/*`, returns HTML.", "schema": { "type": "string", "enum": [ "text/html", "text/markdown" ], "default": "text/html", "examples": [ "text/markdown" ] } } }, "responses": { "NotFound": { "description": "Nothing is published at this URL. The body names the closest matching URLs and the site's entry points.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "text/markdown": { "schema": { "type": "string", "description": "The same error as a short Markdown note." } } } }, "MethodNotAllowed": { "description": "This site is read-only. The `Allow` header lists what it answers to.", "headers": { "Allow": { "description": "Supported methods.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "text/markdown": { "schema": { "type": "string", "description": "The same error as a short Markdown note." } } } } }, "schemas": { "Problem": { "type": "object", "title": "Problem", "description": "RFC 9457 problem details, extended with the members an agent acts on: a stable `code`, ordered `hints`, entry-point `links`, and `suggestions` — real URLs on this site that resemble the one requested.", "required": [ "type", "title", "status", "detail", "code", "hints", "links" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Where this error is documented." }, "title": { "type": "string", "description": "Short, human-readable summary." }, "status": { "type": "integer", "examples": [ 404 ] }, "detail": { "type": "string", "description": "What happened, in one or two sentences." }, "instance": { "type": "string", "description": "The path that produced this error." }, "code": { "type": "string", "enum": [ "not_found", "method_not_allowed", "not_acceptable" ], "description": "Stable, matchable error code." }, "error": { "type": "object", "description": "The same code and message, under the keys most SDKs reach for first.", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "hints": { "type": "array", "description": "What to do next, most useful first.", "items": { "type": "string" } }, "suggestions": { "type": "array", "description": "Real URLs on this site that look like the one requested.", "items": { "type": "string", "format": "uri" } }, "links": { "type": "array", "description": "Entry points that cover the rest of the site.", "items": { "type": "object", "required": [ "rel", "title", "href" ], "properties": { "rel": { "type": "string" }, "title": { "type": "string" }, "href": { "type": "string", "format": "uri" } } } } } }, "ChartIndex": { "type": "object", "title": "ChartIndex", "description": "Every chart type in one line each.", "required": [ "package", "count", "charts" ], "properties": { "package": { "type": "string", "examples": [ "@microcharts/react" ] }, "homepage": { "type": "string", "format": "uri" }, "catalog": { "type": "string", "format": "uri", "description": "The full catalog document." }, "count": { "type": "integer", "description": "How many chart types ship." }, "charts": { "type": "array", "items": { "type": "object", "required": [ "name", "slug", "collection", "tagline", "api", "docs", "markdown" ], "properties": { "name": { "type": "string", "examples": [ "Sparkline" ] }, "slug": { "type": "string", "enum": [ "ab-strips", "activity-grid", "balance-beam", "benchmark-strip", "bias-strip", "breathing-dot", "bubble-row", "bullet", "bump-strip", "burn-chart", "calendar-strip", "calibration-strip", "change-point", "city-skyline", "cohort-triangle", "comet-trail", "confusion-grid", "constellation", "control-strip", "coverage-strip", "cycle-plot", "data-diff", "delta", "depth-wedge", "dice-pips", "dot-plot", "dual-sparkline", "dual-window-meter", "dumbbell", "ensemble-ghosts", "error-budget", "eta-bar", "event-raster", "event-timeline", "fat-digits", "fill-word", "folded-day-band", "forecast-cone", "funnel", "garden-grid", "grade-profile", "graded-band", "heartbeat-blip", "heat-cell", "heat-strip", "histogram-strip", "honeycomb", "horizon", "hourglass", "hypnogram", "icon-array", "likert-strip", "micro-box", "micro-donut", "micro-scatter", "mini-bar", "minimap-strip", "moon-phase", "music-staff", "net-flow", "ohlc", "orbit-status", "paired-bars", "pareto-strip", "partition-strip", "percentile-ladder", "percentile-trace", "phase-trace", "pictogram-row", "polar-clock", "progress", "progress-ring", "quadrant-dot", "quantile-dots", "queue-depth", "rate-volume", "retention-curve", "rubric-strip", "rug-strip", "segmented-bar", "seismogram", "shift-histogram", "slope", "sparkbar", "sparkline", "spiral-year", "spread-band", "sprout-row", "stacked-area", "star-spoke", "station-glyph", "status-dot", "streak-spark", "tally-marks", "tape-gauge", "thermometer", "time-in-range", "token-confidence", "trace-fold", "tree-rings", "trend-arrow", "volume-profile", "waterfall", "waveform", "win-prob-worm", "wind-barb" ] }, "status": { "type": "string", "enum": [ "stable", "planned" ] }, "collection": { "type": "string" }, "tagline": { "type": "string" }, "api": { "type": "string", "format": "uri", "description": "This chart as JSON." }, "docs": { "type": "string", "format": "uri", "description": "This chart's page." }, "markdown": { "type": "string", "format": "uri", "description": "That page as Markdown." } } } } } }, "ChartDocument": { "type": "object", "title": "ChartDocument", "description": "One chart's full API surface. A chart's props are `sharedProps` plus `chart.props`; `howToRead` states how they combine.", "required": [ "package", "howToRead", "sharedProps", "chart" ], "properties": { "package": { "type": "string", "examples": [ "@microcharts/react" ] }, "homepage": { "type": "string", "format": "uri" }, "howToRead": { "type": "string" }, "api": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" }, "markdown": { "type": "string", "format": "uri" }, "sharedProps": { "$ref": "https://microcharts.dev/catalog.schema.json#/properties/sharedProps" }, "chart": { "$ref": "https://microcharts.dev/catalog.schema.json#/properties/charts/items" } } }, "McpServerCard": { "type": "object", "title": "McpServerCard", "description": "An MCP registry `server.json` document.", "required": [ "name", "version", "packages" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "name": { "type": "string", "examples": [ "io.github.ganapativs/microcharts" ] }, "description": { "type": "string" }, "version": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "repository": { "type": "object" }, "packages": { "type": "array", "description": "How to run the server. One npm package, over stdio.", "items": { "type": "object" } } } } } } }