Server API#

This reference is generated from the version 2 executable with vl-convert serve --dump-openapi=public. A running server also serves the same document at /api-doc/openapi.json and an interactive Swagger UI at /docs. Both require the server API key when one is set. Start with Quick Start for a complete request.

This page documents the HTTP API. Rust applications that embed the server can use the vl-convert-server crate reference for the routing, socket binding, and lifecycle APIs.

Vega and Vega-Lite conversion endpoints accept JSON request bodies shaped like {"spec": <spec>, ...overrides}. Overrides use the same names as the Python and Rust options, such as scale, ppi, theme, format_locale, width, and height. Unknown request fields are rejected.

SVG conversion endpoints take the markup in an svg string field. Binary results are returned directly in the response body. SVG, HTML, URL, and JSON results use their corresponding text or JSON content type. Successful render, compilation, HTML, and scenegraph responses carry Vega’s diagnostic messages in the X-VLC-Logs header. URL and font-inspection responses do not include this header.

The Admin Server API uses a separate port or Unix socket and credential, so it has its own reference.

Bundling#

GET /bundling/bundle#

Return a browser bundle containing Vega, Vega-Lite, and Vega Embed.

Query Parameters:
  • vl_version (['string', 'null']) – Vega-Lite version for the bundle (default “6.4”).

Example request:

GET /bundling/bundle HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK – Bundled JavaScript

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Bundling failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /bundling/bundle-snippet#

Bundle an application snippet with compatible visualization dependencies.

Example request:

POST /bundling/bundle-snippet HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "snippet": "string",
    "vl_version": "string"
}
Status Codes:
  • 200 OK – Bundled JavaScript snippet

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Bundling failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

Health#

GET /healthz#

Report whether the server process is running.

Example request:

GET /healthz HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    Health check

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "status": "ok"
    }
    

GET /infoz#

Return server and bundled visualization-library version information.

Example request:

GET /infoz HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    Server info

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "local_tz": "America/New_York",
        "vega_embed_version": "7.2.0",
        "vega_themes_version": "3.0.0",
        "vega_version": "6.4.0",
        "vegalite_versions": [
            "5.8",
            "5.14",
            "5.15",
            "5.16",
            "5.17",
            "5.20",
            "5.21",
            "6.1",
            "6.4"
        ],
        "version": "2.0.0-rc7"
    }
    

GET /readyz#

Report whether the converter can accept requests.

Example request:

GET /readyz HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    Ready

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "status": "ready"
    }
    

  • 503 Service Unavailable –

    Not ready

    Example response:

    HTTP/1.1 503 Service Unavailable
    Content-Type: application/json
    
    {
        "status": "not ready"
    }
    

SVG#

POST /svg/jpeg#

Convert an SVG document to a JPEG image.

Example request:

POST /svg/jpeg HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "quality": 1,
    "scale": 1.0,
    "svg": "string"
}
Status Codes:
  • 200 OK – JPEG image

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /svg/pdf#

Convert an SVG document to a PDF document.

Example request:

POST /svg/pdf HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "svg": "string"
}
Status Codes:
  • 200 OK – PDF document

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /svg/png#

Convert an SVG document to a PNG image.

Example request:

POST /svg/png HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "ppi": 1.0,
    "scale": 1.0,
    "svg": "string"
}
Status Codes:
  • 200 OK – PNG image

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

Themes#

GET /themes#

List the available Vega themes.

Example request:

GET /themes HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    List of theme names

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        "dark",
        "excel",
        "fivethirtyeight"
    ]
    

  • 500 Internal Server Error –

    Internal error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /themes/{name}#

Return one Vega theme configuration.

Parameters:
  • name (string) – Theme name

Example request:

GET /themes/{name} HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    Theme configuration object

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "axis": {
            "labelFont": "Inter",
            "titleFont": "Inter"
        },
        "background": "white"
    }
    

  • 404 Not Found –

    Theme not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

Vega#

POST /vega/fonts#

Return the fonts that VlConvert resolves for a Vega specification.

Example request:

POST /vega/fonts HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "time_format_locale": {},
    "vega_plugin": "string",
    "width": 1.0,
    "include_font_face": true
}
Status Codes:
  • 200 OK –

    Font information

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "import_rule": "@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400');",
            "link_tag": "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css2?family=Inter:wght@400\">",
            "name": "Inter",
            "source": {
                "font_id": "inter",
                "type": "google"
            },
            "url": "https://fonts.googleapis.com/css2?family=Inter:wght@400",
            "variants": [
                {
                    "font_face": null,
                    "style": "normal",
                    "weight": "400"
                }
            ]
        }
    ]
    

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Font analysis failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vega/html#

Convert a Vega specification to an interactive HTML page.

Example request:

POST /vega/html HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "time_format_locale": {},
    "vega_plugin": "string",
    "width": 1.0,
    "bundle": true,
    "renderer": "string"
}
Status Codes:
  • 200 OK – HTML page

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vega/jpeg#

Convert a Vega specification to a JPEG image.

Example request:

POST /vega/jpeg HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "time_format_locale": {},
    "vega_plugin": "string",
    "width": 1.0,
    "quality": 1,
    "scale": 1.0
}
Status Codes:
  • 200 OK – JPEG image

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vega/pdf#

Convert a Vega specification to a PDF document.

Example request:

POST /vega/pdf HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "time_format_locale": {},
    "vega_plugin": "string",
    "width": 1.0
}
Status Codes:
  • 200 OK – PDF document

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vega/png#

Convert a Vega specification to a PNG image.

Example request:

POST /vega/png HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "time_format_locale": {},
    "vega_plugin": "string",
    "width": 1.0,
    "ppi": 1.0,
    "scale": 1.0
}
Status Codes:
  • 200 OK – PNG image

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vega/scenegraph#

Evaluate a Vega specification and return its scenegraph.

Example request:

POST /vega/scenegraph HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "time_format_locale": {},
    "vega_plugin": "string",
    "width": 1.0
}
Status Codes:
  • 200 OK –

    Scenegraph (set Accept: application/msgpack for binary format)

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {}
    

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vega/svg#

Convert a Vega specification to an SVG document.

Example request:

POST /vega/svg HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "time_format_locale": {},
    "vega_plugin": "string",
    "width": 1.0,
    "bundle": true
}
Status Codes:
  • 200 OK – SVG markup

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vega/url#

Create a Vega Editor URL for a Vega specification.

Example request:

POST /vega/url HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "fullscreen": true,
    "spec": {}
}
Status Codes:
  • 200 OK – Vega Editor URL

  • 422 Unprocessable Entity –

    URL generation failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

Vega-Lite#

POST /vegalite/fonts#

Return the fonts that VlConvert resolves for a Vega-Lite specification.

Example request:

POST /vegalite/fonts HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "theme": "string",
    "time_format_locale": {},
    "vega_plugin": "string",
    "vl_version": "string",
    "width": 1.0,
    "include_font_face": true
}
Status Codes:
  • 200 OK –

    Font information

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "import_rule": "@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400');",
            "link_tag": "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css2?family=Inter:wght@400\">",
            "name": "Inter",
            "source": {
                "font_id": "inter",
                "type": "google"
            },
            "url": "https://fonts.googleapis.com/css2?family=Inter:wght@400",
            "variants": [
                {
                    "font_face": null,
                    "style": "normal",
                    "weight": "400"
                }
            ]
        }
    ]
    

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Font analysis failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vegalite/html#

Convert a Vega-Lite specification to an interactive HTML page.

Example request:

POST /vegalite/html HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "theme": "string",
    "time_format_locale": {},
    "vega_plugin": "string",
    "vl_version": "string",
    "width": 1.0,
    "bundle": true,
    "renderer": "string"
}
Status Codes:
  • 200 OK – HTML page

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vegalite/jpeg#

Convert a Vega-Lite specification to a JPEG image.

Example request:

POST /vegalite/jpeg HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "theme": "string",
    "time_format_locale": {},
    "vega_plugin": "string",
    "vl_version": "string",
    "width": 1.0,
    "quality": 1,
    "scale": 1.0
}
Status Codes:
  • 200 OK – JPEG image

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vegalite/pdf#

Convert a Vega-Lite specification to a PDF document.

Example request:

POST /vegalite/pdf HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "theme": "string",
    "time_format_locale": {},
    "vega_plugin": "string",
    "vl_version": "string",
    "width": 1.0
}
Status Codes:
  • 200 OK – PDF document

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vegalite/png#

Convert a Vega-Lite specification to a PNG image.

Example request:

POST /vegalite/png HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "theme": "string",
    "time_format_locale": {},
    "vega_plugin": "string",
    "vl_version": "string",
    "width": 1.0,
    "ppi": 1.0,
    "scale": 1.0
}
Status Codes:
  • 200 OK – PNG image

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vegalite/scenegraph#

Compile and evaluate a Vega-Lite specification, then return its scenegraph.

Example request:

POST /vegalite/scenegraph HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "theme": "string",
    "time_format_locale": {},
    "vega_plugin": "string",
    "vl_version": "string",
    "width": 1.0
}
Status Codes:
  • 200 OK –

    Scenegraph (set Accept: application/msgpack for binary format)

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {}
    

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vegalite/svg#

Convert a Vega-Lite specification to an SVG document.

Example request:

POST /vegalite/svg HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "theme": "string",
    "time_format_locale": {},
    "vega_plugin": "string",
    "vl_version": "string",
    "width": 1.0,
    "bundle": true
}
Status Codes:
  • 200 OK – SVG markup

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vegalite/url#

Create a Vega Editor URL for a Vega-Lite specification.

Example request:

POST /vegalite/url HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "fullscreen": true,
    "spec": {}
}
Status Codes:
  • 200 OK – Vega Editor URL

  • 422 Unprocessable Entity –

    URL generation failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vegalite/vega#

Compile a Vega-Lite specification to Vega.

Example request:

POST /vegalite/vega HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "background": "string",
    "config": {},
    "format_locale": {},
    "google_fonts": [
        "string"
    ],
    "height": 1.0,
    "spec": {},
    "theme": "string",
    "time_format_locale": {},
    "vega_plugin": "string",
    "vl_version": "string",
    "width": 1.0
}
Status Codes:
  • 200 OK –

    Vega specification

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "$schema": "https://vega.github.io/schema/vega/v6.json",
        "marks": []
    }
    

  • 400 Bad Request –

    Invalid request

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Conversion failed

    Example response:

    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/json
    
    {
        "error": "string"
    }