--- title: "What changed between two designs, and what it did" method: POST path: "/v1/designs/compare" tags: ["Compare"] --- # What changed between two designs, and what it did `POST /v1/designs/compare` ## Request - Base URL: `https://electronics-architect.com` - URL: `https://electronics-architect.com/v1/designs/compare` - Auth: HTTP bearer Scope: `solve`. Each side is a design document, `{ design }`, `{ designId }` (a saved design visible to this key) or `{ templateId }` — mix them freely. Both are solved at `options.corner` (unmetered) and the response lists the document diff (`changes`), the movement in source power, load power, dissipation, efficiency and warning counts (`delta`), the converters whose loss moved (`stages`), every node whose operating point moved (`nodes`) and the warnings resolved and introduced. Pass `options.monteCarlo: { trials, seed }` for a `yield` block — two Monte Carlo runs with the same seed, metered as two runs; 402 QUOTA_EXHAUSTED applies then, and only then. Pro and Team only: a Free account is refused with 403 PLAN_REQUIRED (one sentence and the trial link). ## Request body - object - `a` union, required: The baseline: a design document, { design }, { designId } or { templateId }. - Design (unresolved $ref) - object - `design` Design (unresolved $ref) - `designId` string - `templateId` string - `b` union, required: The candidate, in the same forms. - Design (unresolved $ref) - object - `design` Design (unresolved $ref) - `designId` string - `templateId` string - `options` object - `corner` 'nom' | 'min' | 'max' | 'worst': Which tolerance corner to solve. `min`/`max` push every toleranced value to its extreme. `worst` moves each one the way that raises the draw and the heat (loads up, efficiencies down, a switcher's output up, an LDO's down) and holds the input at nominal; each sheet's `worstCase.held` lists what it held and why. - `ambientTemperature` number: Ambient in °C for the thermal estimates. Defaults to the design's own setting, else 25. - `monteCarlo` object: Add a yield comparison. Two metered runs. - `trials` integer - `seed` integer ## Response `200` The comparison. - CompareResponse - `a` CompareSide: One side of a comparison as solved. - `source` string: "design", "design:" or "template:". - `name` string, nullable - `designHash` string - `converged` boolean - `totalSourcePower` number, nullable - `totalLoadPower` number, nullable - `totalDissipation` number, nullable - `efficiency` number, nullable - `warnings` object - `total` integer - `critical` integer - `warning` integer - `caution` integer - `info` integer - `b` CompareSide: One side of a comparison as solved. - `source` string: "design", "design:" or "template:". - `name` string, nullable - `designHash` string - `converged` boolean - `totalSourcePower` number, nullable - `totalLoadPower` number, nullable - `totalDissipation` number, nullable - `efficiency` number, nullable - `warnings` object - `total` integer - `critical` integer - `warning` integer - `caution` integer - `info` integer - `changes` object: The document diff, layout ignored. - `nodes` object - `added` object[] - `id` string - `name` string - `type` string - `removed` object[] - `id` string - `name` string - `type` string - `changed` object[] - `connections` object - `added` object[] - `removed` object[] - `identical` boolean - `delta` object - `totalSourcePower` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `totalLoadPower` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `totalDissipation` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `efficiency` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `warnings` object - `nodes` object[]: Every node present in both whose voltage, current, power or junction temperature moved by more than 1e-9. - `id` string - `name` string - `type` string - `voltage` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `current` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `power` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `temperature` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `stages` object[]: Converters whose dissipation or efficiency moved. - `nodeId` string - `name` string - `type` string - `pdiss` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `eff` Delta: { a, b, delta } — delta is b − a, null when either side is missing. - `a` number, nullable - `b` number, nullable - `delta` number, nullable - `warnings` object - `resolved` object[] - `introduced` object[] - `yield` object: Only with options.monteCarlo: trials, thermalViolationRate, protectionTripRate, failedTrials, efficiencyMean, efficiencyP1, powerMean, powerP99 — each a Delta. - `meta` object - `schemaVersion` integer - `corner` string - `ambientTemperature` number, nullable - `metered` boolean - `feature` string - `monteCarlo` object - `elapsedMs` number - `release` string ## Other responses - `400`: VALIDATION_FAILED on either side, or a malformed side. - `401`: No key, a browser token instead of a key, an unknown key, or a revoked key (code KEY_REVOKED). - `402`: QUOTA_EXHAUSTED — only when `options.monteCarlo` is given. - `403`: The key lacks a required scope (INSUFFICIENT_SCOPE), or the call needs a plan the account does not have (PLAN_REQUIRED): on the Free plan, compare, exports, Monte Carlo jobs, AI synthesis, a design with more than one sheet, or a save, share or key past the Free limits; or a team key whose team is no longer paid for. - `404`: NOT_FOUND — a designId or templateId on either side. - `413`: PAYLOAD_TOO_LARGE. - `429`: RATE_LIMITED: the key's per-minute allowance is used up (or, before any key is recognised, too many requests from one address presented an unknown or revoked key). On the routes that solve inside the request (solve, verify, derating, compare, exports, ai/review, ai/synthesize) it can also be SOLVE_IN_PROGRESS: this account already has 3 calls of that kind running on the server that took the request (solves, AI reviews and syntheses are each counted separately). `Retry-After` is set either way; for SOLVE_IN_PROGRESS it is 2 s for solves and 30 s for AI reviews and syntheses. --- [API](https://skmtc.dev/electronics-architect/apis/electronics-architect-api.md) · [All operations](https://skmtc.dev/electronics-architect/apis/electronics-architect-api/llms.txt) · [OpenAPI document](https://skmtc.dev/electronics-architect/apis/electronics-architect-api/revisions/98066184ba67?raw)