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:

  1. The server validates the proposed configuration.

  2. The server stops accepting new conversion requests.

  3. In-flight requests are given time to finish.

  4. The server starts replacement workers.

  5. 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.

  • null clears a nullable field such as default_theme or max_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
    }
    

  • 400 Bad Request –

    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
    }
    

  • 422 Unprocessable Entity –

    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"
            }
        ]
    }
    

  • 503 Service Unavailable –

    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"
    }
    

  • 504 Gateway Timeout –

    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
    }
    

  • 400 Bad Request –

    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"
    }
    

  • 422 Unprocessable Entity –

    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"
            }
        ]
    }
    

  • 503 Service Unavailable –

    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"
    }
    

  • 504 Gateway Timeout –

    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
    }
    

  • 400 Bad Request –

    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"
    }
    

  • 422 Unprocessable Entity –

    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"
            }
        ]
    }
    

  • 503 Service Unavailable –

    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"
    }
    

  • 504 Gateway Timeout –

    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
    }
    

  • 400 Bad Request –

    Malformed body

    Example response:

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

  • 503 Service Unavailable –

    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"
    ]
    

  • 400 Bad Request –

    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"
    }
    

  • 503 Service Unavailable –

    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"
    ]
    

  • 400 Bad Request –

    Malformed body or a path is not an existing directory

    Example response:

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

  • 503 Service Unavailable –

    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
            }
        ]
    }
    

  • 503 Service Unavailable –

    Worker diagnostics unavailable

    Example response:

    HTTP/1.1 503 Service Unavailable
    Content-Type: application/json
    
    {
        "error": "string"
    }