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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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" ]
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" }
Theme not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
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" } ] } ]
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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 {}
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
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" } ] } ]
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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 {}
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
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
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": [] }
Invalid request
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
Conversion failed
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "error": "string" }