Manage your cable library through the API

Add your organization's own cable series and their sizes, with the resistance and reactance values your study uses, so a project can select them. These are the same series you add on the Cable Editor page. Built-in cable series are listed and readable but cannot be changed.

Access requirements

Operation	API scope	Organization role
List and read series	`catalog:read`	Any active member
Create, update, and archive series and sizes	`catalog:write`	Owner or admin

The library belongs to an organization, so use an API key created while you work in that organization. A key with no organization returns 403 ORGANIZATION_REQUIRED. A series from another organization answers 404, as if it did not exist.

Routes

Route	Scope	Result
`GET /cable-series`	`catalog:read`	Your organization's active series and the built-in series, without sizes.
`POST /cable-series`	`catalog:write`	Create a series, with up to 100 sizes in `variants`. Returns `201` with the sizes.
`GET /cable-series/{seriesId}`	`catalog:read`	One series with its active sizes in `cableVariants`, smallest conductor first.
`PATCH /cable-series/{seriesId}`	`catalog:write`	Change the fields you send.
`DELETE /cable-series/{seriesId}`	`catalog:write`	Archive the series.
`POST /cable-series/{seriesId}/variants`	`catalog:write`	Add one size. Returns `201`.
`PATCH /cable-series/{seriesId}/variants/{variantId}`	`catalog:write`	Change the fields you send.
`DELETE /cable-series/{seriesId}/variants/{variantId}`	`catalog:write`	Archive the size.

Request bodies are limited to 256 KiB. These requests do not use Idempotency-Key. If a create request loses its response, list the series before you send it again; a second create with the same name returns 409 CABLE_SERIES_NAME_TAKEN.

Create a series with its sizes

curl "https://joinekx.com/api/v1/cable-series" \
  -X POST \
  -H "Authorization: Bearer $EKX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mfgName": "ETAP 1/C Cu 600 V",
    "mfgMaxCableTempRatingCelsius": 75,
    "ratedVoltageKv": 0.6,
    "numberOfConductors": 1,
    "variants": [
      { "conductorSize": "1/0", "resistancePerKm": 0.393701, "reactancePerKm": 0.180446, "resistanceTemperatureC": 75 },
      { "conductorSize": "300", "resistancePerKm": 0.147638, "reactancePerKm": 0.167323, "resistanceTemperatureC": 75 }
    ]
  }'

The response contains the series id and each size's id. To use a size in a project, send its id as the cable's cableVariantId and the series id as selectedCableSeriesId; see project data.

Numbers may be sent as JSON numbers or numeric strings. Responses return decimal values as strings, exactly as stored.

Series fields

Field	Required on create	Value
`mfgName`	Yes	The name shown in cable lists. It must be unique among the series you have created, including archived ones.
`mfgMaxCableTempRatingCelsius`	Yes	Maximum conductor temperature, °C, above 0.
`ratedVoltageKv`	Yes	Rated voltage, kV, above 0.
`numberOfConductors`	Yes	Conductors per cable, a whole number.
`conductorMaterial`	No	`CU` (default) or `AL`.
`insulationType`	No	Insulation, such as `XLPE` (default), `EPR`, or `PVC`.
`numberOfGroundConductors`	No	A whole number, or `null`.
`armoured`, `armouredType`	No	`true` or `false` (default), and the armour material, such as `AL` (default) or `STEEL`.
`integralBonding`	No	`true` when the cable carries its own bonding path, so no separate bonding conductor is installed. Default `false`.
`seriesName`, `specNumber`, `manufacturer`, `description`	No	Text up to 500 characters, or `null`.
`certifications`	No	A list of certification codes.

Size fields

Field	Required on create	Value
`conductorSize`	Yes	`14` to `4/0` AWG, or `250` to `2000` kcmil. EKX sets the unit from the size.
`resistancePerKm`, `reactancePerKm`	No	Ω per km of conductor, above 0. Divide an Ω per 1000 ft value by 0.3048.
`resistanceTemperatureC`	No	The temperature of `resistancePerKm`, 0 to 250 °C.
`capacitancePerKm`	No	µF per km, above 0.
`ratedAmperage90`, `manufacturer90degAmpacity`	No	Amperes, above 0.
`impedanceDataSource`	No	`user_entered`, `manufacturer_catalog`, `nec_chapter_9`, `system_default`, or `unknown`. EKX records it as the source of both resistance and reactance.
`impedanceSourceQuality`, `resistanceSourceQuality`, `reactanceSourceQuality`, `ampacitySourceQuality`	No	`manufacturer_catalog_exact`, `manufacturer_catalog_substitute`, `published_reference_table`, `generic_engineering_fallback`, `user_entered`, or `unknown`.
`groundConductorSize`, `numberOfGroundConductors`	No	A ground conductor size from the same list, and a whole number; or `null`.
`partNumber`, `description`	No	Text up to 500 characters, or `null`.

Send null to clear an optional field. A field EKX does not accept, such as organizationId or isActive, returns 400 VALIDATION_ERROR.

Archive a series or size

DELETE archives rather than deletes. An archived series or size disappears from cable library lists and reads and cannot be changed. A cable that already uses it keeps its values, so existing projects calculate as before. An archived series keeps its name.

Error codes

Status	Code	Meaning
`400`	`VALIDATION_ERROR`	A field is missing, unknown, or out of range. `message` and `details.path` name the first one, such as `variants.1.resistancePerKm`; `details.value` lists every problem.
`400`	`INVALID_JSON`	The body is not a JSON object.
`400`	`INVALID_CABLE_SERIES_ID`, `INVALID_CABLE_VARIANT_ID`	The ID in the path is not a valid ID.
`403`	`FORBIDDEN`	The key lacks the scope, or your role is not owner or admin.
`403`	`ORGANIZATION_REQUIRED`	The key does not belong to an organization.
`403`	`CABLE_SERIES_READ_ONLY`	The series is built in. Create your own series instead.
`404`	`NOT_FOUND`	The series or size does not exist, is archived, or belongs to another organization.
`409`	`CABLE_SERIES_NAME_TAKEN`	You already created a series with this name.
`413`	`REQUEST_TOO_LARGE`	The body exceeds 256 KiB.