Admin Server API#
The optional admin API manages a running server. It can inspect and update render-time budgets, replace the converter configuration, manage font directories and the Google Fonts cache size, and report worker memory use.
Set VLC_ADMIN_API_KEY to require an admin bearer token, then enable the
admin API:
$ vl-convert serve \
> --admin-host 127.0.0.1 \
> --admin-port 3001
$ curl http://127.0.0.1:3001/admin/diagnostics/workers \
> -H "Authorization: Bearer $VLC_ADMIN_API_KEY"
The admin API requires a key when bound to a non-loopback TCP address. Set it
through VLC_ADMIN_API_KEY or --admin-api-key.
It can run without a key on loopback or a Unix domain socket, where network
access or filesystem permissions must restrict who can connect.
See Authentication.
A running server also serves this reference at /admin/api-doc/openapi.json
and an interactive Swagger UI at /admin/docs.
Live Configuration Changes#
GET /admin/config returns the active converter settings. PATCH
/admin/config changes selected fields. PUT /admin/config replaces the
complete converter configuration. DELETE /admin/config restores the
configuration the server started with. Font directories and the Google Fonts
cache size have their own endpoints because they apply to the whole process
rather than to one converter.
A configuration change follows this sequence:
The server validates the proposed configuration.
The server stops accepting new conversion requests.
In-flight requests are given time to finish.
The server starts replacement workers.
New requests begin using the replacement.
While this runs, /readyz returns 503 and new conversion requests
receive 503 with Retry-After: 5. If draining or worker start-up fails,
the previous configuration stays active. --reconfig-drain-timeout-secs
bounds the wait.
Sending values identical to the active configuration does not rebuild workers.
GET /admin/config/fonts/cache returns max_size_mb and the read-only
directory. PUT accepts only max_size_mb and returns both fields.
Pass null for max_size_mb to restore the default capacity.
Patch and Replacement Bodies#
A PATCH field has three states:
Omitted keeps the current value.
A JSON value sets the field.
nullclears a nullable field such asdefault_themeormax_v8_heap_size_mb.
null is rejected for required fields such as num_workers,
base_url, allowed_base_urls, and themes.
PUT is a full replacement. Every required field must be present and valid,
and nullable fields may be null. The field names match the JSONC converter
config file.
base_url accepts true for the Vega datasets default, false to reject
relative data URLs, or a URL or filesystem path. allowed_base_urls is a
list of Content Security Policy-style patterns, and an empty list blocks every
HTTP or HTTPS data and image URL and every filesystem path. Inline data:
URLs remain allowed.
Generated Endpoint Reference#
The reference below is generated from
vl-convert serve --dump-openapi=admin.
Admin#
- GET /admin/budget#
Return the active request-budget settings and state.
Example request:
GET /admin/budget HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Current budget status
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "active_ips": 1, "global_budget_ms": 1, "global_remaining_ms": 1, "hold_ms": 1, "per_ip_budget_ms": 1 }
- POST /admin/budget#
Update selected request-budget settings.
Example request:
POST /admin/budget HTTP/1.1 Host: example.com Content-Type: application/json { "global_budget_ms": 1, "hold_ms": 1, "per_ip_budget_ms": 1 }
- Status Codes:
200 OK –
Budget settings updated; response contains the current state
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "active_ips": 1, "global_budget_ms": 1, "global_remaining_ms": 1, "hold_ms": 1, "per_ip_budget_ms": 1 }
Invalid update body
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
- DELETE /admin/config#
Restore the converter configuration that the server started with.
- Status Codes:
200 OK –
Startup configuration restored
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "baseline": { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }, "effective": { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }, "generation": 1 }
Startup configuration failed validation
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "error": "string", "field_errors": [ { "code": "NON_NULLABLE", "message": "string", "path": "string" } ] }
Replacement workers could not start, or the server is shutting down
Example response:
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": "string" }
In-flight requests did not finish before the reconfiguration timeout
Example response:
HTTP/1.1 504 Gateway Timeout Content-Type: application/json { "error": "string", "in_flight": 1 }
- GET /admin/config#
Return the startup configuration, active configuration, and generation number.
Example request:
GET /admin/config HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Startup and active converter configuration, plus the current generation number
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "baseline": { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }, "effective": { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }, "generation": 1 }
- PATCH /admin/config#
Update selected fields in the active converter configuration.
Example request:
PATCH /admin/config HTTP/1.1 Host: example.com Content-Type: application/json { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }
- Status Codes:
200 OK –
Configuration updated
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "baseline": { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }, "effective": { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }, "generation": 1 }
Malformed body, unknown field, invalid null, or zero supplied for a positive field
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
Configuration validation failed
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "error": "string", "field_errors": [ { "code": "NON_NULLABLE", "message": "string", "path": "string" } ] }
Replacement workers could not start, or the server is shutting down
Example response:
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": "string" }
In-flight requests did not finish before the reconfiguration timeout
Example response:
HTTP/1.1 504 Gateway Timeout Content-Type: application/json { "error": "string", "in_flight": 1 }
- PUT /admin/config#
Replace the complete active converter configuration.
Example request:
PUT /admin/config HTTP/1.1 Host: example.com Content-Type: application/json { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }
- Status Codes:
200 OK –
Configuration replaced
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "baseline": { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }, "effective": { "allow_google_fonts": true, "allow_per_request_plugins": true, "allowed_base_urls": [ "string" ], "auto_google_fonts": true, "base_url": true, "default_format_locale": {}, "default_theme": "string", "default_time_format_locale": {}, "embed_local_fonts": true, "gc_after_conversion": true, "google_font_variant_threshold": 1, "google_fonts": [ {} ], "max_ephemeral_workers": 1, "max_v8_execution_time_secs": 1, "max_v8_heap_size_mb": 1, "missing_fonts": "string", "num_workers": 1, "per_request_plugin_import_domains": [ "string" ], "plugin_import_domains": [ "string" ], "subset_fonts": true, "themes": {}, "vega_plugins": [ "string" ] }, "generation": 1 }
Malformed body, missing or unknown field, invalid null, or zero supplied for a positive field
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
Configuration validation failed
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "error": "string", "field_errors": [ { "code": "NON_NULLABLE", "message": "string", "path": "string" } ] }
Replacement workers could not start, or the server is shutting down
Example response:
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": "string" }
In-flight requests did not finish before the reconfiguration timeout
Example response:
HTTP/1.1 504 Gateway Timeout Content-Type: application/json { "error": "string", "in_flight": 1 }
- GET /admin/config/fonts/cache#
Return the Google Fonts cache capacity and read-only directory.
Example request:
GET /admin/config/fonts/cache HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Google Fonts cache capacity and directory
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "directory": "string", "max_size_mb": 1 }
- PUT /admin/config/fonts/cache#
Set the Google Fonts cache capacity. `{“max_size_mb”: null}` restores the default capacity. The directory is read-only and cannot be set here.
Example request:
PUT /admin/config/fonts/cache HTTP/1.1 Host: example.com Content-Type: application/json { "max_size_mb": 1 }
- Status Codes:
200 OK –
Cache capacity updated
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "directory": "string", "max_size_mb": 1 }
Malformed body
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
Google Fonts cache capacity could not be updated
Example response:
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": "string" }
- GET /admin/config/fonts/directories#
Return the currently-registered font directories.
Example request:
GET /admin/config/fonts/directories HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Array of absolute filesystem paths
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ "string" ]
- POST /admin/config/fonts/directories#
Append a single font directory. Idempotent for already-registered paths.
Example request:
POST /admin/config/fonts/directories HTTP/1.1 Host: example.com Content-Type: application/json { "path": "string" }
- Status Codes:
200 OK –
Font directory registered, or already present
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ "string" ]
Path is missing, does not exist, or is not a directory
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
Font directory could not be registered; the previous list remains active
Example response:
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": "string" }
- PUT /admin/config/fonts/directories#
Replace the full font-directory list. Pass `{“paths”: []}` to clear.
Example request:
PUT /admin/config/fonts/directories HTTP/1.1 Host: example.com Content-Type: application/json { "paths": [ "string" ] }
- Status Codes:
200 OK –
Font directory list replaced
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ "string" ]
Malformed body or a path is not an existing directory
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
Font directories could not be updated; the previous list remains active
Example response:
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": "string" }
- GET /admin/diagnostics/workers#
Return JavaScript memory statistics for each conversion worker.
Example request:
GET /admin/diagnostics/workers HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Worker memory usage
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "generation": 1, "workers": [ { "external_memory": 1, "heap_size_limit": 1, "total_heap_size": 1, "used_heap_size": 1, "worker_index": 1 } ] }
Worker diagnostics unavailable
Example response:
HTTP/1.1 503 Service Unavailable Content-Type: application/json { "error": "string" }