Usage

Kroki provides an HTTP API to convert plain text diagrams to images.

Kroki handles both GET and POST requests. When using GET requests, your diagram must be encoded in the URL using a deflate + base64 algorithm.

Don’t worry, if you’re not familiar with deflate or base64 (or if you don’t want to use them), you can also send your diagram as plain text using POST requests.

Let’s take an example with a GraphViz "Hello World":

hello.dot
digraph G {
  Hello->World
}

Here we are using a Python one-liner to encode our diagram using deflate + base64:

cat hello.dot | python -c "import sys; import base64; import zlib; print(base64.urlsafe_b64encode(zlib.compress(sys.stdin.read().encode('utf-8'), 9)).decode('ascii'))"

The above command will return eNpLyUwvSizIUHBXqPZIzcnJ17ULzy_KSanlAgB1EAjQ. We can then copy this value in the URL:

GET /graphviz/svg/eNpLyUwvSizIUHBXqPZIzcnJ17ULzy_KSanlAgB1EAjQ

And here’s the result:

graphviz hello world

You can also call Kroki with POST:

POST /
{
  "diagram_source": "digraph G {Hello->World}",
  "diagram_type": "graphviz",
  "output_format": "svg"
}

In this case, you don’t need to encode your diagram.

It’s also possible to send your diagram as plain text using the Content-Type header. The output format will be specified using the Accept header and the diagram source will be sent as the request body:

POST /graphviz
Accept: image/svg+xml
Content-Type: text/plain

digraph G {
  Hello->World
}

You can also define the output format in the URL if you don’t want to add an Accept header:

POST /graphviz/svg
Content-Type: text/plain

digraph G {
  Hello->World
}

The same concept applies when sending the diagram as JSON:

POST /graphviz/svg
{
  "diagram_source": "digraph G {Hello->World}"
}

Options

Some diagram libraries relies on options declared outside the diagram definition.
To do pass options to the underlying diagram library, you can declare them as query parameters, as attributes in the JSON body or as HTTP headers.

Query parameters

For GET requests, you can pass diagram options as query parameters:

GET /graphviz/svg/eNpLyUwvSizIUHBXqPZIzcnJ17ULzy_KSanlAgB1EAjQ?key=value

POST requests

When using POST you can declare options in the diagram_options:

POST /
{
  "diagram_source": "digraph G {Hello->World}",
  "diagram_type": "graphviz",
  "output_format": "svg",
  "diagram_options": {
    "key": "value"
  }
}

HTTP headers

Finally, you can pass options using HTTP headers prefixed by Kroki-Diagram-Options:

POST /graphviz
Accept: image/svg+xml
Content-Type: text/plain
Kroki-Diagram-Options-Key: value

digraph G {
  Hello->World
}

Kroki defines the precedence order as follows:

  1. JSON body

  2. HTTP header

  3. Query parameter

To find out what options are available, please read the Diagram Options page.

Next