Electronics Architect Designs API

openapi: 3.2.0
info:
  title: Electronics Architect Designs 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: Designs
  description: Cloud designs — the same rows "Save to Cloud" writes, so agent output appears in My Designs / Team Designs.
paths:
  /v1/designs:
    get:
      tags:
      - Designs
      summary: List designs visible to this key
      description: 'Scope: `read`. A personal key lists the account''s personal designs; a team key lists the team''s.'
      responses:
        '200':
          description: Newest first, up to 500.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignList'
        '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_…".'
        '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
      operationId: getV1Designs
      x-operation-id-source: derived
    post:
      tags:
      - Designs
      summary: Create a cloud design
      description: 'Scope: `write`. The design must validate. Send an `Idempotency-Key` header to make retries safe: the first response is replayed for 24 hours (`Idempotent-Replayed: true`). Creation through the API stops once the account''s personal designs (or a team key''s team) number 2000, counting designs saved from the editor too (409 DESIGN_LIMIT_REACHED), and design writes — create, update, delete, share — are limited to 30 a minute per account across all its keys.'
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - design
              properties:
                name:
                  type: string
                  maxLength: 200
                design:
                  $ref: '#/components/schemas/Design'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignCreated'
        '400':
          description: VALIDATION_FAILED or INVALID_REQUEST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_REQUEST
                  message: name is required (1 to 200 characters).
                  field: name
        '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_…".'
        '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
        '409':
          description: DESIGN_LIMIT_REACHED — the account (or team) already holds 2000 designs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: DESIGN_LIMIT_REACHED
                  message: This account already holds 2000 designs, the most the API will create. Delete designs you no longer need (DELETE /v1/designs/{id}) or update an existing one.
                  limit: 2000
        '413':
          description: PAYLOAD_TOO_LARGE — over 500 KB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: PAYLOAD_TOO_LARGE
                  message: Design data too large. Maximum size is 500 KB.
                  field: design
        '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
      operationId: postV1Designs
      x-operation-id-source: derived
  /v1/designs/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Designs
      summary: Read a design
      description: 'Scope: `read`.'
      responses:
        '200':
          description: The design document and its metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignRecord'
        '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_…".'
        '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
        '404':
          description: NOT_FOUND — no such design visible to this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: No design with that id is visible to this key.
        '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
      operationId: getV1DesignsById
      x-operation-id-source: derived
    put:
      tags:
      - Designs
      summary: Replace a design (keeps history)
      description: 'Scope: `write`. The previous state is snapshotted into the revision history with the key''s label as the author ("via key nightly-optimizer"), exactly as a save in the editor snapshots the state it replaces.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - design
              properties:
                name:
                  type: string
                  maxLength: 200
                design:
                  $ref: '#/components/schemas/Design'
                message:
                  type: string
                  maxLength: 500
                  description: A note describing the design you are SENDING. It is stored with this state and travels with it into the revision history when a later save replaces it; it does not label the state you are replacing.
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignUpdated'
        '400':
          description: VALIDATION_FAILED or INVALID_REQUEST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: VALIDATION_FAILED
                  message: …
        '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_…".'
        '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
        '404':
          description: NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: No design with that id is visible to this key.
        '413':
          description: PAYLOAD_TOO_LARGE.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: PAYLOAD_TOO_LARGE
                  message: Design data too large. Maximum size is 500 KB.
        '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
      operationId: putV1DesignsById
      x-operation-id-source: derived
    delete:
      tags:
      - Designs
      summary: Delete a design
      description: 'Scope: `write`.'
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  deleted:
                    type: boolean
        '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_…".'
        '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
        '404':
          description: NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: No design with that id is visible to this key.
        '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
      operationId: deleteV1DesignsById
      x-operation-id-source: derived
  /v1/designs/{id}/share:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      tags:
      - Designs
      summary: Create or update the public share link
      description: 'Scope: `write`. The same expiring link the editor''s Share dialog makes; one public link per design, updated in place. Changing its permission to `edit` or `clone` issues a new link and retires the old one, so a view-only link already printed on an export never gains more access.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                permissions:
                  type: string
                  enum:
                  - view
                  - edit
                  - clone
                  default: view
                expiresInDays:
                  type: integer
                  enum:
                  - 1
                  - 7
                  - 30
                  - 90
                  description: Omit or null for a link that never expires.
      responses:
        '200':
          description: The link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
        '400':
          description: INVALID_REQUEST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_REQUEST
                  message: expiresInDays must be one of 1, 7, 30, 90, or omitted for a link that does not expire.
                  field: expiresInDays
        '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_…".'
        '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
        '404':
          description: NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: No design with that id is visible to this key.
        '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
      operationId: postV1DesignsByIdShare
      x-operation-id-source: derived
components:
  schemas:
    DesignRecord:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        design:
          $ref: '#/components/schemas/Design'
        message:
          type: string
          nullable: true
          description: The note describing the design in THIS response. A revision row carries the note for the state in it, so the live design keeps its own here; a design saved once has a message and no revisions.
        revisions:
          type: integer
          description: How many earlier states this design has replaced.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    DesignSummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    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
    DesignList:
      type: object
      properties:
        designs:
          type: array
          items:
            $ref: '#/components/schemas/DesignSummary'
        scope:
          type: object
    DesignUpdated:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: integer
          description: 'The live design''s version after this update: a new design is 1 and every update adds 1. The state it replaced is kept as revision version − 1.'
        updatedAt:
          type: string
          format: date-time
        revisionAuthor:
          type: string
        editorUrl:
          type: string
          description: The deep link that opens this design on the canvas (`/app?design=<id>`), where the change is flagged as this key's and the previous state is one click away.
    ShareLink:
      type: object
      properties:
        shareId:
          type: string
        url:
          type: string
        permissions:
          type: string
        expiresInDays:
          type:
          - integer
          - 'null'
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
    DesignCreated:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: integer
        createdAt:
          type: string
          format: date-time
        editorUrl:
          type: string
          description: The deep link that opens THIS design on the canvas (`/app?design=<id>`). Hand this to the person; the editor shows them which key made it.
  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).