Connect to the EKX API

Use the EKX REST API to read project data, change a single-line diagram, run studies, and review or apply sizing proposals from your own scripts and agents.

> Note: To use EKX from Claude Code, Codex, or another MCP-capable agent, you do not need an API key. See Connect an AI agent to EKX.

Create an API key

1. Open Settings > API Keys.
2. Click Create Key.
3. Enter a name that identifies the script or agent that will use the key.
4. Select only the scopes it needs.
5. Click Create.
6. Copy the key and store it in your secret manager. EKX will not show it again.

> Warning: An API key acts as your user account. Do not paste it into source code, logs, chat messages, or project files. Revoke the key from Settings > API Keys if it may have been exposed.

The key retains your project permissions. A key cannot edit a project that you can only view. If you create it while working in an organization, it can access only projects in that organization.

Choose scopes

Create separate keys for separate tools. This makes a compromised key easier to revoke and limits what each tool can change. Scopes cannot be added to an existing key; create a new key when a tool needs more access.

Send your first request

Production requests use https://joinekx.com/api/v1. Send the key as a Bearer token:

curl "https://joinekx.com/api/v1/projects" \
  -H "Authorization: Bearer $EKX_API_KEY"

A successful response wraps its content in data and includes response metadata:

{
  "data": [],
  "meta": {
    "timestamp": "2026-08-30T12:00:00.000Z",
    "version": "1"
  }
}

An error uses a stable code and a readable message. Validation errors may also include details with the rejected path or value.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope: studies:run"
  }
}

Handle retries and limits

EKX limits authenticated API traffic to 100 requests per minute per user. A 429 response includes Retry-After; wait for that number of seconds before trying again.

Catalogue-build mutations, study runs, and sizing applies require an Idempotency-Key header. Generate a unique value for each intended operation, then reuse that value only when retrying the exact same request.

-H "Idempotency-Key: 6b20cfee-b995-43f3-8740-2f87c5893df2"

For 24 hours after completion, EKX returns the stored result when the same API key repeats the same request. Idempotency-Replayed: true identifies a replay. Reusing the value with a different request returns 409 IDEMPOTENCY_CONFLICT. If the original operation is still running, EKX returns 409 IDEMPOTENCY_IN_PROGRESS with Retry-After.

Project create, replace, patch, and archive requests do not use this replay contract. Do not assume that resending one of those requests after a lost response is safe. Read the project state first and decide whether the change still needs to run.

Managed SLD create, proposal, revision, and cancellation requests also require an Idempotency-Key, but retain their replay result for 30 days. See the managed-build guide before using an agent to construct an SLD.

Common response codes

Transformer imports accept transformerConstruction as dry_type, other_than_dry_type, or null. Leave it unknown when the source does not establish construction; cooling type is not sufficient. See project imports for omission and patch behavior.

Next steps

• Connect an AI agent to EKX
• Read and change project data
• Import a single-line diagram with an agent
• Run studies and apply sizing
• Manage your cable library