---
title: "Render a wiring diagram as SVG or PNG"
method: POST
path: "/api/diagram/generate"
tags: ["generators"]
---

# Render a wiring diagram as SVG or PNG

`POST /api/diagram/generate`

## Request

- Base URL: `https://voltplan.app`
- URL: `https://voltplan.app/api/diagram/generate`
- Auth: none declared

Public, CORS-open endpoint; 30 requests per minute per client IP. The client IP is the first `X-Forwarded-For` entry, else `X-Real-IP`, else one shared `unknown` bucket; counters are kept in memory per server instance and per route. Flat mode renders `loads`, `batteries` and `chargers`. When `circuits` is non-empty the flat lists are ignored and one labelled panel per circuit is rendered, with `links` drawn as connectors; links whose `from`/`to` resolve to no circuit or to the same circuit are dropped. A power source is added automatically for each charger based on its `sourceType`, and fuses/protection components are added when batteries and loads exist. `Accept: image/png` returns PNG, anything else SVG; when PNG conversion fails the SVG is returned instead. Component icons from `iconUrl` are fetched server-side and embedded as data URIs. No external API is called.

## Request body

- DiagramGenerateRequest: Wiring diagram to render: either flat component lists or `circuits` with `links`.
  - `systemName` string, required: System name; required by validation, not drawn.
  - `source` 'cable' | 'voltplan': Branding variant of the footer bar.
  - `loads` DiagramLoad[]
    - `name` string, required
    - `power` number, required: Rated power in W.
    - `voltage` number, required: Supply voltage in V (DC).
    - `current` number, required: Current in A; accepted, the diagram derives currents from power and voltage.
    - `iconUrl` string: URL of an icon image drawn on the component; fetched server-side and embedded as a data URI.
  - `batteries` DiagramBattery[]
    - `name` string, required
    - `voltage` number, required: Nominal voltage in V.
    - `capacityAh` number, required: Capacity in Ah; accepted, sizing uses energyWh.
    - `energyWh` number, required: Stored energy in Wh.
    - `iconUrl` string: URL of an icon image drawn on the component; fetched server-side and embedded as a data URI.
  - `chargers` DiagramCharger[]
    - `name` string, required
    - `inputVoltage` number, required: Input voltage in V.
    - `outputVoltage` number, required: Battery-side output voltage in V (DC).
    - `power` number, required: Output power in W.
    - `sourceType` 'shore' | 'solar' | 'wind' | 'generator' | 'alternator': Power source added upstream of the charger; `shore` and `generator` make the charger input AC, the others DC.
    - `iconUrl` string: URL of an icon image drawn on the component; fetched server-side and embedded as a data URI.
  - `circuits` DiagramCircuit[]: Multi-circuit mode: when non-empty, the top-level loads/batteries/chargers are ignored.
    - `name` string, required: Circuit name; referenced by link `from`/`to`.
    - `loads` DiagramLoad[]
      - `name` string, required
      - `power` number, required: Rated power in W.
      - `voltage` number, required: Supply voltage in V (DC).
      - `current` number, required: Current in A; accepted, the diagram derives currents from power and voltage.
      - `iconUrl` string: URL of an icon image drawn on the component; fetched server-side and embedded as a data URI.
    - `batteries` DiagramBattery[]
      - `name` string, required
      - `voltage` number, required: Nominal voltage in V.
      - `capacityAh` number, required: Capacity in Ah; accepted, sizing uses energyWh.
      - `energyWh` number, required: Stored energy in Wh.
      - `iconUrl` string: URL of an icon image drawn on the component; fetched server-side and embedded as a data URI.
    - `chargers` DiagramCharger[]
      - `name` string, required
      - `inputVoltage` number, required: Input voltage in V.
      - `outputVoltage` number, required: Battery-side output voltage in V (DC).
      - `power` number, required: Output power in W.
      - `sourceType` 'shore' | 'solar' | 'wind' | 'generator' | 'alternator': Power source added upstream of the charger; `shore` and `generator` make the charger input AC, the others DC.
      - `iconUrl` string: URL of an icon image drawn on the component; fetched server-side and embedded as a data URI.
  - `links` DiagramCircuitLink[]: Only used with `circuits`.
    - `from` union, required: Circuit name or zero-based index into `circuits`.
      - string
      - integer
    - `to` union, required: Circuit name or zero-based index into `circuits`.
      - string
      - integer
    - `kind` 'dcdc' | 'vsr' | 'isolator', required: DC-DC charger, voltage-sensitive relay, or battery isolator.
    - `spec` BridgeSpec, required: Electrical rating of a link or bridge device.
      - `inputVoltage` number, required: Input voltage in V.
      - `outputVoltage` number, required: Output voltage in V.
      - `power` number, required: Power in W.

## Response `200`

Rendered diagram. SVG by default; PNG when the Accept header contains image/png and conversion succeeds.

## Other responses

- `400`: Body is not an object, systemName is not a string, loads/batteries/chargers/links is not an array, or circuits is not an array of objects with a string name. Nested items are not validated.
- `429`: More than 30 requests within 60 seconds from this client IP.
- `500`: Rendering failed, or the request body was not valid JSON: a generic fallback SVG ("Diagram generation failed").

---

[API](https://skmtc.dev/voltplan/apis/voltplan-api.md) · [All operations](https://skmtc.dev/voltplan/apis/voltplan-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voltplan/apis/voltplan-api/revisions/575b86a7af92?raw)