brycewang-stanford/kroki-diagram-api

Kroki Diagram API

Overview

Kroki provides a unified HTTP API to render 20+ text-based diagram formats into images (SVG, PNG, PDF). It supports Mermaid, PlantUML, Graphviz, D2, BPMN, and more — all through a single endpoint. Self-hostable or use the free public instance. No authentication required. Ideal for generating research figures, architecture diagrams, and flowcharts programmatically.

API Usage

GET Request (URL-encoded)

# Graphviz DOT diagram
curl "https://kroki.io/graphviz/svg/digraph{A->B->C}" -o diagram.svg

# Mermaid diagram (base64-encoded)
echo "graph TD; A-->B; B-->C;" | base64 | \
  curl "https://kroki.io/mermaid/svg/$(cat -)" -o diagram.svg

POST Request (Recommended)

# PlantUML sequence diagram
curl -X POST "https://kroki.io/plantuml/svg" \
  -H "Content-Type: text/plain" \
  -d '@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi!
@enduml' -o sequence.svg

# Mermaid flowchart
curl -X POST "https://kroki.io/mermaid/svg" \
  -H "Content-Type: text/plain" \
  -d 'graph TD
    A[Data Collection] --> B[Preprocessing]
    B --> C[Model Training]
    C --> D[Evaluation]
    D -->|Good| E[Deploy]
    D -->|Bad| B' -o flowchart.svg

# Graphviz
curl -X POST "https://kroki.io/graphviz/svg" \
  -H "Content-Type: text/plain" \
  -d 'digraph {
    rankdir=LR
    "Raw Data" -> "Feature Extraction" -> "Model" -> "Prediction"
  }' -o pipeline.svg

# D2 diagram
curl -X POST "https://kroki.io/d2/svg" \
  -H "Content-Type: text/plain" \
  -d 'Client -> API: Request
API -> Database: Query
Database -> API: Results
API -> Client: Response' -o d2.svg

URL Format

https://kroki.io/{diagram_type}/{output_format}/{encoded_source}

# Or POST to:
https://kroki.io/{diagram_type}/{output_format}

Supported Diagram Types

| Type | Keyword | Best for | |------|---------|----------| | Mermaid | mermaid | Flowcharts, sequences, Gantt | | PlantUML | plantuml | UML, sequences, class diagrams | | Graphviz | graphviz | Network graphs, DAGs | | D2 | d2 | Modern text-to-diagram | | Ditaa | ditaa | ASCII art diagrams | | BlockDiag | blockdiag | Block diagrams | | Nomnoml | nomnoml | UML-like diagrams | | WaveDrom | wavedrom | Digital timing diagrams | | Vega | vega | Data visualizations | | Vega-Lite | vegalite | Simplified data viz | | C4 PlantUML | c4plantuml | C4 architecture | | BPMN | bpmn | Business processes | | Bytefield | bytefield | Protocol/byte diagrams | | Excalidraw | excalidraw | Hand-drawn style |

Output Formats

| Format | Extension | Use case | |--------|-----------|----------| | SVG | /svg | Web, scalable | | PNG | /png | Documents, slides | | PDF | /pdf | Papers, print | | JPEG | /jpeg | Compatibility |

Python Usage

import requests
import base64
import zlib


KROKI_URL = "https://kroki.io"


def render_diagram(source: str, diagram_type: str = "mermaid",
                   output_format: str = "svg") -> bytes:
    """Render a text diagram to image via Kroki."""
    resp = requests.post(
        f"{KROKI_URL}/{diagram_type}/{output_format}",
        headers={"Content-Type": "text/plain"},
        data=source,
    )
    resp.raise_for_status()
    return resp.content


def save_diagram(source: str, output_path: str,
                 diagram_type: str = "mermaid",
                 output_format: str = "svg"):
    """Render and save a diagram to file."""
    content = render_diagram(source, diagram_type, output_format)
    with open(output_path, "wb") as f:
        f.write(content)


def render_research_pipeline(steps: list) -> bytes:
    """Create a research pipeline flowchart."""
    nodes = []
    for i, step in enumerate(steps):
        node_id = chr(65 + i)
        nodes.append(f"    {node_id}[{step}]")
        if i > 0:
            prev_id = chr(65 + i - 1)
            nodes.append(f"    {prev_id} --> {node_id}")

    mermaid = "graph TD\n" + "\n".join(nodes)
    return render_diagram(mermaid, "mermaid", "svg")


# Example: create a research workflow diagram
workflow = """graph TD
    A[Literature Review] --> B[Hypothesis]
    B --> C[Data Collection]
    C --> D[Statistical Analysis]
    D --> E{Significant?}
    E -->|Yes| F[Write Paper]
    E -->|No| G[Revise Hypothesis]
    G --> B
    F --> H[Peer Review]"""

save_diagram(workflow, "research_workflow.svg", "mermaid")

# Example: Graphviz citation network
citation_graph = """digraph {
    rankdir=BT
    node [shape=box, style=rounded]
    "Vaswani 2017" -> "BERT 2018"
    "Vaswani 2017" -> "GPT 2018"
    "BERT 2018" -> "RoBERTa 2019"
    "GPT 2018" -> "GPT-2 2019"
    "GPT-2 2019" -> "GPT-3 2020"
}"""
save_diagram(citation_graph, "citations.svg", "graphviz")

# Example: research pipeline helper
pipeline_svg = render_research_pipeline([
    "Raw Data", "Cleaning", "Feature Engineering",
    "Model Training", "Evaluation", "Deployment"
])

Self-Hosting

# Run Kroki locally via Docker
docker run -d -p 8000:8000 yuzutech/kroki

# Then use http://localhost:8000 instead of https://kroki.io

References

• Kroki
• Kroki Documentation
• Kroki GitHub