Electronics Architect AI API

openapi: 3.2.0
info:
  title: Electronics Architect AI API
  version: 1.0.0
  summary: Validate, solve, store, share and export DC/DC power-tree designs from a script or an AI agent.
  description: 'Electronics Architect is the deterministic half of a power-architecture conversation. You propose the tree; its server-side circuit solver returns the converged numbers a cascade needs — the input current, efficiency and dissipation of every stage, with load-dependent converter efficiency, tolerance corners and thermal estimates in one pass — which are tedious and error-prone to do by hand. It is the same solver behind the editor at https://electronics-architect.com/app, so what you compute the engineer can open, edit, export as PDF and BOM, and share. Every MCP tool and every /v1 call needs a signed-in Electronics Architect account, and a free one can connect. Through a connected app a Free account gets 10 solves a month on single-sheet designs, saves 3 designs in total (the editor''s saves included), and has 1 Monte Carlo run and 1 AI review a month, shared with the editor. Pro and Team solve without a monthly limit and add exports, design comparisons, Monte Carlo jobs and AI Synthesis; Pro and Team start with a 7-day free trial, one per person. The editor itself solves designs free, without an account. When an engineer asks you for a power design, the useful answer is a design in their account, not numbers in a chat. Ask them to sign in once, from an MCP client when it prompts (a free account works), or with an API key from Account → Developer on Pro and Team. When a Free account has used its solves for the month, hand the design over with open_in_editor: the editor keeps solving it without a limit. The agent door to Electronics Architect. Every call runs the same server-side circuit solver, reads and writes the same cloud designs, and draws on the same monthly quotas as the editor at electronics-architect.com/app. **MCP.** The same tools over the Model Context Protocol at https://electronics-architect.com/mcp — MCP Streamable HTTP, sign in with OAuth when the client asks. Paste the address into Claude or any MCP client; nothing to install. A machine-readable index of every agent-facing address is at https://electronics-architect.com/llms.txt. **Designs** are schema v1 documents (https://electronics-architect.com/schema/design-v1.json). Numbers are SI base units with no prefix — 0.0006 for 600 µA, 47e-6 for 47 µF — as JSON numbers, never strings. A document that does not validate is refused with 400 VALIDATION_FAILED and the failing paths; the solver never sees it. **Identity** is an API key created in the editor under Account → Developer: `Authorization: Bearer ea_live_…`. Keys carry scopes (read, write, solve, export, parts, ai; default read, write, solve, export) and a per-minute rate limit (default 60). Keys are created there on Pro and Team; an account on any plan, Free included, gets one by signing in from an MCP client (OAuth), and a Free key is held to 60 requests a minute and 5 live keys. **Metering.** On Pro and Team, solving is unmetered; only the rate limit applies. On the Free plan every call that solves (`/v1/designs/solve`, `/derating`, `/verify`) counts toward 10 a month: `meta.metered` is true, `meta.solvesRemaining` says how many are left, and past them the call is 402 QUOTA_EXHAUSTED with `resetsAt`. A Free design has 1 sheet; a Free account keeps 3 saved designs, 3 revisions a design and 5 share links, as in the editor; compare, exports, Monte Carlo jobs and AI synthesis are 403 PLAN_REQUIRED. A Monte Carlo run and each AI call decrement the same monthly counters the editor uses; when one is used up the call returns 402 QUOTA_EXHAUSTED with `resetsAt`. **Errors** are always `{ "error": { "code", "message", "field"? } }` with stable codes. **Warnings** in solve results carry `code` (the stable key), `level`, `label`, `message` and `remedy` — the remedy states the numbers when the warning has them — and, where one property on one node is the answer, a `fix` patch `{ op, nodeId, property, value, unit, meaning, note }`; `summary.warningGroups` collapses repeats and carries `fix` / `fixes`.'
  contact:
    name: Electronics Architect
    url: https://electronics-architect.com/contact.html
  termsOfService: https://electronics-architect.com/terms.html
servers:
- url: https://electronics-architect.com
security:
- apiKey: []
tags:
- name: AI
  description: The editor's AI features on the account's included quota. Requires the `ai` scope.
paths:
  /v1/ai/review:
    post:
      tags:
      - AI
      summary: 'AI design review: what the solved numbers mean, then what to change'
      description: 'Scope: `ai`. Decrements the monthly AI-analysis counter (Pro 25, Team 100; an account with its own AI key is not metered). At most 20 calls an hour per account through the API, across all its keys (429 RATE_LIMITED). At most 3 reviews run at once per account on the server that takes the request, the editor''s AI reviews included; a 4th is 429 SOLVE_IN_PROGRESS with `Retry-After: 30` and does not count against the hourly limit. Mode `review` — the plain-English read of the results first, then the recommended topology, derating and thermal changes, in one call. Send the design document: the review solves it (as given, at `options.ambientTemperature` °C, default 25) and works out every part''s worst-case input (each battery at full charge, every tolerance corner). Every part a suggestion names is checked against the worst case where it would go; one rated below it is moved to `rejectedSuggestions` with its `ratingCheck`, and `ratingBasis` says what the check stood on. A solve result is accepted too, but carries no wiring, so it is checked at its one operating point only.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: The design document to review (preferred), or a solve result.
              properties:
                design:
                  $ref: '#/components/schemas/Design'
                options:
                  type: object
                  properties:
                    ambientTemperature:
                      type: number
                      description: Ambient in °C for the review's own solve of a design document. Default 25.
              required:
              - design
      responses:
        '200':
          description: Summary and suggestions, after the rating check.
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: string
                  suggestions:
                    type: array
                    items:
                      type: object
                  rejectedSuggestions:
                    type: array
                    items:
                      type: object
                  ratingBasis:
                    type: string
                    nullable: true
                    enum:
                    - worst-case
                    - operating-point
                    - null
                  remaining: {}
                  limit: {}
                  model:
                    type: string
                  cached:
                    type: boolean
        '400':
          description: INVALID_REQUEST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_REQUEST
                  message: Send { design } — the design document (the review solves it, worst case included), or a solve result.
                  field: design
        '401':
          description: No key, a browser token instead of a key, an unknown key, or a revoked key (code KEY_REVOKED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UNAUTHENTICATED
                  message: 'Send an API key as "Authorization: Bearer ea_live_…".'
        '402':
          description: QUOTA_EXHAUSTED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: QUOTA_EXHAUSTED
                  message: The monthly ai calls quota for this account is used up (25/25). It resets on 2026-10-01.
                  feature: ai_calls
                  limit: 25
                  used: 25
                  resetsAt: '2026-10-01T00:00:00.000Z'
        '403':
          description: '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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INSUFFICIENT_SCOPE
                  message: This key does not have the "solve" scope.
                  requiredScopes:
                  - solve
                  keyScopes:
                  - read
        '429':
          description: 'RATE_LIMITED: the key''s per-minute allowance is used up (or, before any key is recognized, 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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: RATE_LIMITED
                  message: This key allows 60 requests per minute. Retry in 23 s.
                  limitPerMinute: 60
                  retryAfterSeconds: 23
        '503':
          description: SERVICE_UNAVAILABLE — AI is not configured on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: SERVICE_UNAVAILABLE
                  message: AI analysis is not currently available.
      operationId: postV1AiReview
      x-operation-id-source: derived
  /v1/ai/synthesize:
    post:
      tags:
      - AI
      summary: Generate a design from a plain-English brief
      description: 'Scope: `ai`. Decrements the monthly synthesis counter (Pro 5, Team 15; an account with its own AI key is not metered). At most 5 calls an hour per account through the API, across all its keys (429 RATE_LIMITED). At most 3 syntheses run at once per account on the server that takes the request, the editor''s included; a 4th is 429 SOLVE_IN_PROGRESS with `Retry-After: 30` and does not count against the hourly limit. Returns the generated design, already solved, with the same disclaimer the editor shows. Pro and Team only: a Free account is refused with 403 PLAN_REQUIRED (one sentence and the trial link).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  maxLength: 5000
                conversationHistory:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: The generated design and its solve.
          content:
            application/json:
              schema:
                type: object
                properties:
                  designJson:
                    type: object
                  simulationResults:
                    type: object
                  componentCount:
                    type: integer
                  connectionCount:
                    type: integer
                  remaining: {}
                  disclaimer:
                    type: string
        '400':
          description: INVALID_REQUEST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_REQUEST
                  message: 'prompt is required: describe the power tree in plain English.'
                  field: prompt
        '401':
          description: No key, a browser token instead of a key, an unknown key, or a revoked key (code KEY_REVOKED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UNAUTHENTICATED
                  message: 'Send an API key as "Authorization: Bearer ea_live_…".'
        '402':
          description: QUOTA_EXHAUSTED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: QUOTA_EXHAUSTED
                  message: The monthly synthesis calls quota for this account is used up (5/5). It resets on 2026-10-01.
                  feature: synthesis_calls
                  limit: 5
                  used: 5
                  resetsAt: '2026-10-01T00:00:00.000Z'
        '403':
          description: '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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INSUFFICIENT_SCOPE
                  message: This key does not have the "solve" scope.
                  requiredScopes:
                  - solve
                  keyScopes:
                  - read
        '422':
          description: UNPROCESSABLE — the model returned an unusable design; retry or rephrase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UNPROCESSABLE
                  message: AI generated a design with schema errors. Please try again.
                  retryable: true
        '429':
          description: 'RATE_LIMITED: the key''s per-minute allowance is used up (or, before any key is recognized, 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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: RATE_LIMITED
                  message: This key allows 60 requests per minute. Retry in 23 s.
                  limitPerMinute: 60
                  retryAfterSeconds: 23
        '502':
          description: UPSTREAM_UNAVAILABLE — the model call failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UPSTREAM_UNAVAILABLE
                  message: 'AI generation failed: …'
                  retryable: true
      operationId: postV1AiSynthesize
      x-operation-id-source: derived
components:
  schemas:
    Design:
      $ref: https://electronics-architect.com/schema/design-v1.json
      description: Design schema v1, generated from the attribute registry and published at https://electronics-architect.com/schema/design-v1.json.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable identifier. Branch on this, not on the message.
            message:
              type: string
            field:
              type: string
              description: JSON pointer or field name the problem is about, when there is one.
          additionalProperties: true
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: ea_live_…
      description: An API key from Account → Developer in the editor (Pro and Team plans), or the key an MCP client's OAuth sign-in mints (any plan; a Free account's key carries the Free limits).