openapi: 3.0.3
info:
  title: Kroki Diagram 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
externalDocs:
  description: Kroki Documentation
  url: https://docs.kroki.io/kroki/
servers:
  - url: https://kroki.io
    description: Public Kroki API
tags:
  - name: Diagrams
    description: Generate diagrams from textual descriptions
  - name: Health
    description: Service health check
paths:
  /:
    get:
      operationId: getHealth
      summary: Get Service Health
      description: Returns the health status of the Kroki service.
      tags:
        - Health
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /{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'
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
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          description: Health status of the service
          example: pass
        version:
          type: string
          description: Version of the Kroki service
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        status_code:
          type: integer
          description: HTTP status code