Technical Diagrams for developers

Use this free, public reference API when an agent needs a familiar technical diagram, a visual example, or editable source. No account, API key, payment, or sales conversation is required. The same endpoints serve the gallery and this sandbox. There is no separate privileged environment and no write API.

Quickstart

curl https://technicaldiagrams.com/api/diagrams
curl 'https://technicaldiagrams.com/api/diagrams?q=request'
# Replace ID with a recipe ID from the list:
curl https://technicaldiagrams.com/api/diagrams/ID/scene
curl 'https://technicaldiagrams.com/api/diagrams/ID/svg?theme=dark&accent=green'

Start with the compact index, compare useWhen and avoidWhen, and fetch one scene. Adapt its labels and coordinates using the primitive reference. Inspect the result visually before shipping it. Diagram scores are editorial assessments, not model benchmarks.

REST API and errors

OpenAPI 3.1 specification describes typed inputs, response schemas, and unique operation IDs. GET /api lists the entry points. GET /api/diagrams accepts optional q (up to 200 characters) and family. GET /api/diagrams/{id} returns metadata, /scene returns version-1 scene JSON, and /svg returns SVG with optional theme and accent. GET endpoints support HEAD. OPTIONS describes CORS access. The original /api/catalog.json and /api/scenes/{id}.json downloads remain available.

Invalid IDs return HTTP 404. Invalid query parameters return 400. Unsupported methods return 405. Errors are JSON with error.code, error.message, error.hint, and a documentation URL. Empty search results return a successful empty list. Correct the request rather than repeatedly retrying a 4xx response. There is no application-level quota today; hosting limits still apply. Cache catalog data locally, avoid unbounded concurrent calls, and respect any hosting-level Retry-After response. Availability is best effort.

MCP

Connect a Streamable HTTP client to https://technicaldiagrams.com/.well-known/mcp (alias /mcp). This is Technical Diagrams’ own server. It exposes list_diagrams, get_diagram, and render_diagram. Tools are read-only and need no credentials. render_diagram renders a catalog recipe with a selected theme and accent; edit arbitrary scenes locally with the MIT renderer. The server uses the official MCP SDK, negotiates its supported protocol version at initialization, and uses stateless JSON responses over Streamable HTTP. Clients must send the protocol’s required Accept and Content-Type headers. GET event streams are not offered.

Markdown and discovery

Send Accept: text/markdown to gallery, recipe, and documentation pages. HTML remains the browser default. Both representations include Vary: Accept, Accept-Encoding; negotiated responses disable CDN caching. Unsupported representation requests return 406. HTML advertises a downloadable Markdown alternate through a Link header. Agent instructions, sitemap, About, Contact, and Privacy provide context and recovery paths.

CLI

The official CLI source lives in packages/cli in the repository. Run node packages/cli/bin/technical-diagrams.mjs list, scene ID, or svg ID. The CLI uses https://technicaldiagrams.com by default; use --base-url URL to target another deployment. The package is ready for npm packaging; registry publication requires the maintainer’s npm credentials. Do not assume an npm package is available until a release is announced.

Try the read-only sandbox

Choose a reference and presentation below. The sandbox calls the public SVG endpoint; it cannot alter the catalog, execute code, or store a diagram. Its default example works without entering any data.

Ready. No API key required.