---
title: "Estimate a device's electrical specs from a free-text description (AI)"
method: POST
path: "/api/loads/estimate"
tags: ["generators"]
---

# Estimate a device's electrical specs from a free-text description (AI)

`POST /api/loads/estimate`

## Request

- Base URL: `https://voltplan.app`
- URL: `https://voltplan.app/api/loads/estimate`
- Auth: none declared

Used by the wireframe editor's add-load dialog. Calls the external OpenRouter chat-completions API (https://openrouter.ai) with the model configured server-side in `OPENROUTER_LOAD_ASSISTANT_MODEL`; 20 s timeout. 20 requests per hour 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. No CORS headers.

## Request body

- LoadEstimateRequest
  - `description` string, required: Free-text description; the length is checked after trimming.

## Response `200`

Parsed estimate.

- LoadEstimate: AI estimate of a load (mirrors `LoadEstimate` in src/lib/loadAssistantPrompt.ts).
  - `name` string, required
  - `watt` number, required: Nominal running power in W.
  - `wattMin` number: Lower bound of the plausible running power in W.
  - `wattMax` number: Upper bound of the plausible running power in W.
  - `category` 'resistive' | 'electronics' | 'fridge' | 'motor' | 'pump'
  - `note` string
  - `dutyCycle` number: Percent of switched-on time the compressor/motor actually draws power.
  - `utilizationFactor` number: Percent of a day the device is switched on.

## Other responses

- `400`: Body is not valid JSON, or description (trimmed) is missing, not a string, or outside 2–300 characters.
- `422`: The model did not recognize the description as a device (empty name or watt ≤ 0).
- `429`: More than 20 requests within one hour from this client IP.
- `502`: No model configured, OpenRouter failed or timed out, or its reply contained no parseable JSON object.

---

[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)