Read and change project data through the API

The project endpoints expose the saved engineering model, analysis evidence, and atomic graph imports under /api/v1/projects.

Read project data

All read endpoints require projects:read and at least viewer access to the project.

The calculations endpoint requires exactly one result selector:

• GET /projects/{projectId}/calculations?study_run_id={studyRunId} reads results owned by one API or in-app study run.
• GET /projects/{projectId}/calculations?type=power_flow reads legacy results that are not attached to a study run. Add scenario_id={scenarioId} when needed.

Use limit from 1 to 500 and a nonnegative offset to page calculation rows.

Create a project and graph

POST /projects/import requires projects:write. It creates the project, its Base scenario, the submitted components, connections, settings, defaults, and sizing settings in one transaction.

curl "https://joinekx.com/api/v1/projects/import" \
  -X POST \
  -H "Authorization: Bearer $EKX_API_KEY" \
  -H "Content-Type: application/json" \
  --data @project.json

For new projects, agents should omit component positions and let EKX arrange the diagram. If any component omits both coordinates, EKX lays out the whole imported graph, including components with supplied positions. To preserve a prepared layout, supply both coordinates for every component. A partial, blank, or non-finite position is rejected.

A small project.json can look like this:

{
  "project": {
    "name": "Plant distribution",
    "codeBook": "NEC",
    "codeEditionYear": 2026
  },
  "components": [
    {
      "tempId": "utility",
      "type": "utility_feed",
      "properties": {
        "name": "UTILITY",
        "voltageKv": "13.8",
        "shortCircuitMva": "500"
      }
    },
    {
      "tempId": "service-bus",
      "type": "bus",
      "properties": {
        "name": "SERVICE BUS",
        "baseKv": "13.8"
      }
    }
  ],
  "connections": [
    {
      "tempId": "utility-to-bus",
      "sourceTempId": "utility",
      "targetTempId": "service-bus",
      "sourceHandleSide": "bottom",
      "targetHandleSide": "top"
    }
  ]
}

The response maps each temporary ID to its saved UUID:

{
  "data": {
    "ok": true,
    "projectId": "...",
    "componentIds": {
      "utility": "...",
      "service-bus": "..."
    },
    "connectionIds": {
      "utility-to-bus": "..."
    }
  },
  "meta": {
    "timestamp": "2026-08-30T12:00:00.000Z",
    "version": "1"
  }
}

Replace or patch a graph

CEC voltage-drop inputs are nullable component properties. Read and export preserve them:

Omitting a property from a patch preserves it; null clears it. Voltage-drop sizing starts each path at the sole grid supply or transformer secondary of a radial network; multiple supplies and unsupported topology remain unresolved. On a CEC project, a cable created with bondingMeans omitted or null, or whose series, installation or raceway changes, gets integral_cable when its series has an integral bonding conductor and null otherwise. Other declarations remain unconfirmed unless explicitly supplied. Send a motor current and its source together when confirming a nameplate value. Rating and supply-voltage changes preserve confirmed nameplate current. Replacing or clearing the current clears its confirmation unless the request supplies the matching source. The legacy calculated source denotes a table lookup, not a nameplate confirmation. These declarations do not automatically accept a sizing result.

A load requires activePowerMw, except a motor load that has a positive motorHorsepower or fullLoadAmps: studies and sizing take the motor's size from whichever of the three you send.

motorNameplateVoltage is optional on motor loads in create, replace, and patch imports. Omission on a patch preserves it; null selects automatic supply-following behavior. Reads and exports retain null for automatic mode and the entered kV value for a fixed override; they never save an assumed rating as an entered value. Automatic motor defaults in volts are 120→115, 208→200, 240→230, 480→460, 600→575, 2400→2300 and 4160→4000; other positive supplies remain unchanged. The motor panel displays volts. Create, replace, copy and restore retain the same null-versus-fixed distinction.

Both operations require projects:write and an editor or owner role.

PUT /projects/{projectId}/import replaces the existing components, connections, and component sizing settings. It also applies any project metadata, project settings, canvas state, or defaults included in the body. Use it only when the submitted components and connections describe the complete intended graph. Existing completed study evidence remains available but becomes stale.

Create and replace requests require a tempId for every component. Connections in those requests refer to the component temporary IDs. Saved connection IDs are supported only in patch requests.

A replace keeps the protection work of every component you submit with its saved id and the same type:

• Mounted trip units, relays, fuse parts and overload relays, with their settings, curve overrides and CT links, stay on that protection or motor control device.
• An installed catalogue curve profile stays when the catalogue still supports it. It is cleared when the catalogue no longer does, and marked for review when the device rating no longer matches it.
• Trip-unit pickups set as a share of the device rating follow a changed rating.
• Scenario values for that component stay.
• Saved TCCs keep their members that remain.

A replace removes the same work for every component it does not keep, as a delete would. A saved TCC is deleted when it had members and none of them remain; a saved TCC that had no members stays. To drop a device's mounted parts in a replace, submit the device without its id. When a kept device's new type or breaker frame cannot take its mounted parts, for example a breaker resubmitted as a fuse, the replace removes those parts and the response warnings array names that component. The rest of the replace still applies.

PATCH /projects/{projectId}/import changes only the submitted records. For components:

• Omit id and provide tempId to create a component.
• Provide id and the correct singular type to update a component.
• Provide id, type, and "op": "delete" to delete a component.

An update sends only what it changes. Each submitted property, and the position when sent, updates the saved record; every omitted property, including the name and position, keeps its current value. A required property such as the name or a bus's baseKv cannot be cleared: sending it as null or "" is rejected. A component created by PATCH or included in a replacement must include its position and required properties. Only the new-project POST import can omit positions to request automatic layout.

For transformers, transformerConstruction accepts "dry_type", "other_than_dry_type", or null. Create and replace leave construction unknown when omitted. Patch preserves an omitted value and clears it when you send null. Reads and exports return the saved value. Cooling type does not establish construction; supply it from the drawing, nameplate, or an engineer's confirmation. On a CEC 2024 project with a primary of 750 V or less, an unknown construction sizes protection to a rating both Rule 26-252 and Rule 26-254 permit.

For synchronous generators, statorResistancePu accepts finite nonnegative Ra in per unit on the rated kV/MVA base: "0.01" means 1%. Create and replace use generator defaults when Ra is omitted; the built-in default is blank. Null retains the legacy zero-resistance assumption. Patch preserves an omitted Ra and clears it with null; an explicit "0" remains distinct from blank. Reads, exports and scenario overrides preserve the entered per-unit value. Changing Ra marks short-circuit and arc flash studies stale.

Utility operating voltage

operatingVoltagePercent is the percent of nominal voltage the utility holds in power flow, from 80 to 120. It is optional on create and defaults to 100; a value outside the range is rejected with 400. Reads and exports return it. Changing it marks power flow stale; short-circuit and arc flash studies do not use it.

Utility fault cases

A utility can hold up to four fault cases, for example the maximum and minimum levels a utility letter gives. The utility's fault-level fields (shortCircuitMva, xrRatio, and so on for its inputMethod) are its first case. Three more fields describe the cases:

Each additional case is an object:

{
  "id": "6f1c2a4e-7d1b-4c55-9a52-0f6b3c1e2d77",
  "name": "Min",
  "studies": ["arc_flash"],
  "shortCircuitMva": "40",
  "xrRatio": "6"
}

• id is a UUID you choose. Keep it when you rename the case.
• name is required, 1 to 40 characters. Names must differ from each other and from the first case's name, ignoring case.
• studies lists the studies the case is included in, as for faultCaseStudies.
• The values use the first case's field names for the utility's input method: shortCircuitMva and xrRatio for mva; threePhaseFaultCurrent and faultCurrentXrRatio for fault_current; z1PuReal, z1PuImag, z0PuReal, and z0PuImag for per_unit. baseMva and singlePhaseFaultCurrent stay single. MVA, X/R, kA and z1PuImag must be above 0; z1PuReal, z0PuReal, and z0PuImag must be 0 or more. A value may be null until you have it.

Changing inputMethod through the API does not convert the added cases: send additionalFaultCases with values for the new method in the same request, or it is rejected. The Study tab converts them for you.

EKX does not compare the cases with each other. A key the input method does not use, an unknown key, a repeated id or name, or a fifth case rejects the whole request with 400 UTILITY_FEED_VALIDATION_FAILED naming the problem. Reads and exports return the three fields; a utility that never had cases returns one case in both studies. Changing faultCaseStudies or additionalFaultCases marks short-circuit and arc flash studies stale; changing faultCaseName does not.

A short-circuit run evaluates every case included in short circuit and reports the highest current at each location, naming its case; see Studies and sizing. An arc flash run evaluates every case included in arc flash and reports, per bus, the case with the highest incident energy; see Studies and sizing.

Connections follow the same pattern. A connection update or delete uses its saved id. Submit both endpoints and handle sides when updating a connection. New records may refer to components created in the same request through sourceTempId and targetTempId.

A connection's properties.operatingStatus is closed (the default) or open; an open connection carries no current in any study, in sizing, or in TCC ordering. Any other value is refused with 400. The former isNormallyOpen property is refused with 400 as well: send operatingStatus: "open" for a tie that is open in the base design, and a scenario override for a tie that is open only in one operating case.

Component payload types are bus, cable, transformer, generator, load, capacitor_bank, utility_feed, protection_device, and motor_control_device. Positions may use position: { "x": ..., "y": ... }. Connection sides may use top, bottom, left, right, primary, secondary, or tertiary where the component supports them.

Capacitor banks

A capacitor bank uses type capacitor_bank in create, replace, and patch imports. Like other components, a bank created by PATCH or included in a replacement needs a position.

Capacitor banks are no longer a load type. A load sent with loadType capacitor_bank is refused with 400 and the message: "Capacitor banks are their own component type. Send type "capacitor_bank" instead of a load with loadType "capacitor_bank"."

Each request may contain at most 500 components, 1,000 connections, 64 default records, and 1,000 sizing-setting records. The complete JSON body may not exceed 2 MiB.

Mount trip units and set their dials

A breaker's electronic trip unit is a mounted part. Create, replace, and patch imports accept an optional mountedTripUnits array to mount one and set its dials:

{
  "mountedTripUnits": [
    {
      "protectionDeviceTempId": "cb-001",
      "tripUnit": { "catalogId": "45aadb83-...", "skuId": "98c64ced-..." },
      "nativeSettings": {
        "longTimePickup": { "kind": "discrete", "id": "long_time.pickup_9" },
        "longTimeBand": { "kind": "discrete", "id": "long_time.band_6" },
        "shortTime": {
          "pickup": { "kind": "discrete", "id": "short_time.pickup_4" },
          "band": { "kind": "discrete", "id": "short_time.band_6" },
          "i2t": "IN"
        },
        "instantaneous": { "kind": "discrete", "id": "instantaneous.pickup_0" }
      }
    }
  ]
}

• Name the breaker with protectionDeviceTempId (a breaker in the same request) or protectionDeviceId (a saved breaker).
• A breaker that already carries the named trip unit keeps it; a different mounted trip unit is replaced.
• When a request gives an LV breaker a new or different frame, and exactly one catalogue trip unit fits that frame, EKX mounts it with the frame. A breaker whose frame is unchanged keeps its trip unit, or the absence of one. mountedTripUnits entries apply after this default.
• nativeSettings applies to trip units whose curves EKX generates from their ETAP record, such as the Siemens 3VA ETU 350 and ETU 856. Each dial names a position from the record (kind: "discrete" with its option id) or, for a trip unit with fine steps, a value (kind: "continuous": pickups in multiples of the rating plug or frame, delays in seconds). Omit it to keep the trip unit's current dials; send null for the slowest combination the record offers.
• A combination the trip unit does not offer, or nativeSettings for a trip unit without an ETAP record, rejects the whole request with a VALIDATION_ERROR naming the entry.

Exports return each trip unit's dials as nativeSettings in its trip unit settings.

Send project settings

Create, replace, and patch imports accept an optional settings object with three fields:

• projectSettings: study and project options, using the field names that GET /projects/{projectId}/settings returns.
• canvasState: the saved canvas view, using the field names that the same read returns.
• tccLabelPreferences: TCC label choices, described in TCC label preferences.

Place project settings inside settings.projectSettings, not directly under settings:

{
  "settings": {
    "projectSettings": {
      "arcFlashPreFaultVoltagePercent": 105,
      "arcFlashTwoSecondCap": true
    }
  }
}

Each request saves only the fields you send; omitted fields keep their saved values. A field EKX does not recognize, under settings or inside projectSettings or canvasState, rejects the whole request with a VALIDATION_ERROR whose details name the field. A project export also contains settings.displayConfig; leave it out of an import.

Engineering rules still apply

API graph changes follow the same rules as changes made in the editor. EKX validates component names and required fields, project access, references, handle use, voltage zones, catalog selections, cleanup, and plan limits before it commits.

A successful import may normalize derived values or return a warnings array. A failed rule returns an error and rolls back the complete request. Imports do not run calculations. In a project whose autoSizingMode is apply, the default for a new project, EKX sizes the project after the import commits, as it does after an edit in the editor: blank cables get a size, and equipment you did not rate gets the rating sizing selects. Values you send are manual and stay as sent. To keep every value as sent, set autoSizingMode to suggest or off in settings.projectSettings. If that sizing cannot finish, the import still succeeds and warnings says why.

Changing a fixed thermal-magnetic breaker's rated current selects the matching part in its series. A mounted fixed release belonging to that assembled part follows the replacement, including its fixed pickup; selecting another part directly does the same. Reads and exports return the replacement and its settings.

A cable created or replaced without cableVariantId, or with null, keeps a blank conductor size in its catalogue series; EKX does not pick one. When the cable's circuit voltage is above that series' rating, the series moves to one rated for it, as it does for a sized cable, and the size stays blank. A patch that omits cableVariantId keeps the saved size, and null clears it. Reads and exports return null for a blank size. In an apply project the sizing that follows the import gives it a size. Otherwise every study that needs the cable's impedance refuses with INCOMPLETE_ENGINEERING_INPUT and names the cable. A cable of length 0 has no impedance at any size, so load flow, short circuit and arc flash run without one; its loading stays unavailable until it has a size. Send a conductor size, from the built-in catalogue or a series you add through the cable library, or size the cable with the sizing preview and apply endpoints in Studies and sizing. Sizing only sizes a cable in automatic mode. On a blank cable, selectedCableSeriesId and parallelRuns name no size, so the cable stays automatic: sizing picks its size in that series and, while automatic parallel runs are on (the default), its run count too. A cableVariantId, or a sizingSettings entry of manual or locked, takes a cable out of sizing. A manual or locked cable with a blank size blocks the protection it would limit until you send a size.

A fuse with a catalogId and skuId gets that fuse part mounted, as picking it in the editor does: its settings, the part's rating and interrupting rating on the device, and the part's catalogue curves when it has exactly one set. A patch or replace that names a different part swaps the mounted fuse; one that resends the saved part keeps the mounted fuse, including a part changed in the editor since. A part that is archived, belongs to another category, or is not in the named catalogue entry fails the request at properties.catalogId.

A patch marks completed studies stale when a submitted component changes any saved value other than its name, description, canvas position or rotation, or a cable's display length unit; resending a component unchanged, or changing only those, leaves them current. Any created or deleted component, and any submitted connection, marks them stale. A sizing setting that changes a component's sizing mode or overrides marks sizing stale.

> Important: A project export contains more information than an import accepts. Do not send the export response back unchanged. Build the import body from its project, component, connection, default, sizing-setting, and settings data, and omit study history, calculation evidence, protection internals, and TCC records. Keep each component's id in a replace so its protection and saved TCCs stay.

Keep every exported sizingSettings entry, including its sizingMode (auto, manual, or locked) and authored overrides. Omission lets the import choose new modes from the submitted ratings and can change an automatic component to manual. Remove only sizingInputEvidence from each entry's overrides before sending it; it records server confirmation of the old inputs and cannot authorize a new import. The writer records confirmation from the imported inputs again.

const sizingSettings = exported.sizingSettings.map(({ overrides, ...setting }) => ({
  ...setting,
  overrides: Object.fromEntries(
    Object.entries(overrides ?? {}).filter(([key]) => key !== "sizingInputEvidence")
  ),
}));

Use the resulting entries unchanged for a replacement. For a new project, replace each componentId with componentTempId referring to that component's submitted tempId. The same conversion applies when patching exported sizing settings. Never submit acceptance records, coordinated-group hashes, or sizing results as overrides: these are server-owned evidence.

A transformer export preserves both xrRatio and loadLossesKw. Send both unchanged: when they agree within the stored decimal precision, create, replace and patch retain the pair. Editing losses alone derives X/R; editing X/R alone derives losses. If both change and disagree, losses determine X/R.

Exports report an installed catalogue curve profile as curveProfileKey with a curveProfileStatus, as component reads do; they do not include the catalogue curve IDs behind it.

Create and change scenarios

A scenario is an operating case of the drawing: it changes switching, in-service status and operating values without changing the base design. Equipment values such as ratings, impedances and cable lengths belong to the base design. The scenario endpoints require projects:write and editor access to the project. A viewer key can read scenarios but not change them.

Create a scenario with a name, and optionally a description. A new scenario starts equal to the base design. Names must be unique in the project. You cannot delete the Base scenario. Adding, deleting or wiring components changes the drawing for every scenario.

Override writes take a list of components. Each componentType is the singular type: bus, cable, transformer, generator, load, capacitor_bank, utility_feed, protection_device, motor_control_device, or connection. The request saves every component or none.

A connection override names a wire by its connection ID and sets only operatingStatus, open or closed, so a tie drawn as a plain wire can be open in one scenario and closed in another. A protection device's operatingState does the same for a breaker, fuse or switch.

{
  "components": [
    {
      "componentId": "...",
      "componentType": "utility_feed",
      "overrides": { "z1PuReal": "0.1499", "z1PuImag": "0.4611", "z0PuReal": "0.531", "z0PuImag": "0.6112" }
    }
  ]
}

PATCH and PUT return all of the scenario's override records, in the same form as the read endpoint.

Each value must meet the rules for the base component. A field that a scenario cannot change, or a value out of range, rejects the whole request with 400 and names the problem; an equipment field answers with the code SCENARIO_FIELD_NOT_OPERATING and the field in details.path. A scenario can change these fields:

For a utility feed, a scenario can change voltageKv, operatingVoltagePercent, inService, inputMethod, and the source values for each method:

A scenario can also set faultCaseName, faultCaseStudies, and additionalFaultCases. It replaces additionalFaultCases as a whole list, and EKX stores the list with the input method its values are for: if you send the list without inputMethod, the scenario's current input method is stored with it. Removing additionalFaultCases from a scenario removes that stored inputMethod too; removing inputMethod alone while the scenario keeps its cases is rejected. A list whose keys do not match the scenario's input method, or whose case is named like the scenario's first case, is rejected.

The studies read only the values for the scenario's input method, after overrides. To study a fault current on a utility entered in per unit, also set inputMethod to fault_current in the scenario; if the utility has added fault cases, send additionalFaultCases with fault-current values in the same request. baseMva and z1PuImag must be above 0, and the other per-unit and ohm values must be 0 or more. A scenario can also set singlePhaseFaultCurrent, r1Ohms, x1Ohms, r0Ohms, and x0Ohms, which are stored, but no study reads them.

To run a study for a scenario, send its ID as scenario_id to the study endpoints in Studies and sizing. A change to a scenario's values marks the completed studies of that scenario stale.

Archive a project

DELETE /projects/{projectId} requires projects:write and project ownership. It archives the project instead of permanently deleting its records.

Related topics

• Connect to the EKX API
• Import a single-line diagram with an agent
• Run studies and apply sizing

TCC label preferences

Project reads and full exports include settings.tccLabelPreferences: the project's explicit label choices by breaker, fuse, and relay. Inherited organization/system defaults and personal preferences are excluded.

The existing create, replace, and patch import endpoints accept the same optional field:

{
  "settings": {
    "tccLabelPreferences": {
      "breaker": { "manufacturer": true, "frameSize": true, "functions": true },
      "fuse": { "fuseClass": true }
    }
  }
}

This example is the settings portion of an import payload. Omit the field to preserve existing choices. Supply a map to replace all project TCC choices, or {} to reset them to inherited values. A field omitted from a supplied map inherits; false explicitly hides it. Unsupported device types, fields, and non-boolean values are rejected. Do not place these choices inside projectSettings.

These choices affect presentation. They do not change protection functions, applied settings, curves, or study results. Graph imports that omit the field leave label choices unchanged.