openapi: 3.0.3
info:
  title: Kroki Diagram Diagrams API
  description: Kroki provides a unified HTTP API for generating diagrams from textual descriptions. It supports over 20 diagram types including PlantUML, Mermaid, GraphViz, BlockDiag, BPMN, C4, Structurizr, Excalidraw, Vega, WaveDrom, and more. Diagrams can be submitted as GET requests with the source encoded in the URL or as POST requests with the source in the request body.
  version: 1.0.0
  contact:
    name: Kroki
    url: https://kroki.io/
  license:
    name: MIT
    url: https://github.com/yuzutech/kroki/blob/master/LICENSE
servers:
- url: https://kroki.io
  description: Public Kroki API
tags:
- name: Diagrams
  description: Generate diagrams from textual descriptions
paths:
  /{diagram_type}/{output_format}/{encoded_diagram}:
    get:
      operationId: getDiagramGet
      summary: Get Diagram via GET
      description: Generates a diagram from an encoded source using a GET request. The diagram source must be compressed with deflate and encoded in base64url format. The diagram type and output format are specified in the URL path.
      tags:
      - Diagrams
      parameters:
      - name: diagram_type
        in: path
        required: true
        description: 'The type of diagram to generate. Supported types: plantuml, mermaid, graphviz, blockdiag, seqdiag, actdiag, nwdiag, packetdiag, rackdiag, bpmn, bytefield, c4plantuml, d2, dbml, ditaa, erd, excalidraw, nomnoml, pikchr, structurizr, svgbob, symbolator, tikz, umlet, vega, vega-lite, wavedrom, wireviz'
        schema:
          type: string
          enum:
          - plantuml
          - mermaid
          - graphviz
          - blockdiag
          - seqdiag
          - actdiag
          - nwdiag
          - packetdiag
          - rackdiag
          - bpmn
          - bytefield
          - c4plantuml
          - d2
          - dbml
          - ditaa
          - erd
          - excalidraw
          - nomnoml
          - pikchr
          - structurizr
          - svgbob
          - symbolator
          - tikz
          - umlet
          - vega
          - vega-lite
          - wavedrom
          - wireviz
      - name: output_format
        in: path
        required: true
        description: 'Output format for the diagram. Supported formats: svg, png, jpeg, pdf (availability depends on diagram type)'
        schema:
          type: string
          enum:
          - svg
          - png
          - jpeg
          - pdf
      - name: encoded_diagram
        in: path
        required: true
        description: Deflate + base64url encoded diagram source text
        schema:
          type: string
      responses:
        '200':
          description: Generated diagram in the requested output format
          content:
            image/svg+xml:
              schema:
                type: string
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request — invalid diagram type, format, or source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{diagram_type}/{output_format}:
    post:
      operationId: postDiagram
      summary: Post Diagram for Rendering
      description: Generates a diagram from a plain-text source using a POST request. The diagram source is sent in the request body. Supports plain text (text/plain) or JSON (application/json) with a "diagram_source" key. The output format is specified in the URL path.
      tags:
      - Diagrams
      parameters:
      - name: diagram_type
        in: path
        required: true
        description: 'The type of diagram to generate. Supported types: plantuml, mermaid, graphviz, blockdiag, seqdiag, actdiag, nwdiag, bpmn, c4plantuml, d2, ditaa, erd, excalidraw, nomnoml, structurizr, svgbob, umlet, vega, vega-lite, wavedrom, wireviz'
        schema:
          type: string
      - name: output_format
        in: path
        required: true
        description: Output format for the diagram (svg, png, jpeg, pdf)
        schema:
          type: string
          enum:
          - svg
          - png
          - jpeg
          - pdf
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: Plain text diagram source
          application/json:
            schema:
              $ref: '#/components/schemas/DiagramRequest'
      responses:
        '200':
          description: Generated diagram in the requested output format
          content:
            image/svg+xml:
              schema:
                type: string
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request — invalid diagram type, format, or source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /png/{encoded}:
    get:
      operationId: getDiagramPng
      summary: Get Diagram as PNG
      description: Renders a PlantUML diagram as a PNG image. The encoded parameter is the PlantUML source compressed with deflate and encoded in base64url.
      tags:
      - Diagrams
      parameters:
      - name: encoded
        in: path
        required: true
        description: Deflate + base64url encoded PlantUML source
        schema:
          type: string
      responses:
        '200':
          description: PNG image of the rendered diagram
          content:
            image/png:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid or malformed encoded diagram source
  /svg/{encoded}:
    get:
      operationId: getDiagramSvg
      summary: Get Diagram as SVG
      description: Renders a PlantUML diagram as an SVG image. The encoded parameter is the PlantUML source compressed with deflate and encoded in base64url.
      tags:
      - Diagrams
      parameters:
      - name: encoded
        in: path
        required: true
        description: Deflate + base64url encoded PlantUML source
        schema:
          type: string
      responses:
        '200':
          description: SVG image of the rendered diagram
          content:
            image/svg+xml:
              schema:
                type: string
        '400':
          description: Invalid or malformed encoded diagram source
  /txt/{encoded}:
    get:
      operationId: getDiagramAscii
      summary: Get Diagram as ASCII Art
      description: Renders a PlantUML diagram as ASCII art text. Useful for text-only environments or embedding in documentation.
      tags:
      - Diagrams
      parameters:
      - name: encoded
        in: path
        required: true
        description: Deflate + base64url encoded PlantUML source
        schema:
          type: string
      responses:
        '200':
          description: ASCII art text representation of the diagram
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Invalid or malformed encoded diagram source
  /pdf/{encoded}:
    get:
      operationId: getDiagramPdf
      summary: Get Diagram as PDF
      description: Renders a PlantUML diagram as a PDF document.
      tags:
      - Diagrams
      parameters:
      - name: encoded
        in: path
        required: true
        description: Deflate + base64url encoded PlantUML source
        schema:
          type: string
      responses:
        '200':
          description: PDF document of the rendered diagram
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid or malformed encoded diagram source
  /map/{encoded}:
    get:
      operationId: getDiagramImageMap
      summary: Get Diagram HTML Image Map
      description: Returns an HTML image map for the diagram, enabling clickable areas on diagrams rendered as PNG.
      tags:
      - Diagrams
      parameters:
      - name: encoded
        in: path
        required: true
        description: Deflate + base64url encoded PlantUML source
        schema:
          type: string
      responses:
        '200':
          description: HTML image map for the diagram
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Invalid or malformed encoded diagram source
components:
  schemas:
    DiagramRequest:
      type: object
      required:
      - diagram_source
      properties:
        diagram_source:
          type: string
          description: The plain text source of the diagram to render
        diagram_options:
          type: object
          description: Optional rendering options specific to the diagram type
          additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        status_code:
          type: integer
          description: HTTP status code
externalDocs:
  description: Kroki Documentation
  url: https://docs.kroki.io/kroki/