Catalogue-build API reference

Catalogue builds are the authoritative API for agent-driven protection-device imports. All JSON responses use the v1 API envelope. The server derives the organization from the bearer credential; request bodies cannot select or override it. Builds are also creator-private: another user's API key in the same organization cannot read, revise, or apply the build.

Opening a new PDF or native ETAP import does not depend on how many unfinished imports you have. You can keep earlier drafts while starting another import.

Routes and scopes

Every bearer-authenticated mutation requires Idempotency-Key. Create and upload-ticket responses store only a capability descriptor and derive the secret token when presented; GET never returns a token. Authentication happens before request-body parsing.

Create request modes

POST /api/v1/catalog-builds accepts these build controls beside intent and sources:

Curves-only mode also requires curveRequirement: "required". It preserves the target record's factual data, SKUs, compatibility, factual provenance, and saved curves unless a reviewed curve replacement permits replacing that curve. Existing curves do not satisfy the new-curve requirement.

States and reconnect behavior

created accepts uploads. processing and applying may be polled safely. blocked exposes the complete current issue document and accepted resolution types. applied, failed, canceled, and expired are terminal.

A build that hits a blocking issue with no allowed response, and has no other issue that offers one, cannot continue. EKX finishes it as failed, and safeFailure carries that issue's code and message. A package with only unsupported devices, sources without product facts, terminal provider failures, and too many pages for curves end a build this way.

One extraction examines at most 24 pages across all sources, and curves need every page examined. Curves are in scope when curveRequirement is required, when a source's contentHint is curves or both, or when EKX finds a time-current curve page while preparing the pages. A source set over 24 pages with curves in scope fails before extraction and is not charged. The failed build's safeFailure.code is TOLERANCE_SOURCE_COVERAGE_INCOMPLETE; it is not an upload error. Upload only the pages with the curves and settings.

Process returns HTTP 202 Accepted after saving processing ownership. PDF and provider work continues after the response, including if the client disconnects. Poll GET for progress. If allowedActions includes resume_processing, call process with the current expectedVersion and a new idempotency key. A server restart leaves the build resumable after its processing lease expires. Replaying an earlier accepted request returns its saved response; use GET for the latest state.

GET returns the optional user intent while detailed build content is retained. It becomes null when terminal content is purged after 30 days.

GET also returns targetCatalogId, curveRequirement, importMode, and curvesWaived. These are stored build decisions. Clients must not derive them from the intent, source hints, review state, or the presence of a curve worker job.

curveDiagnostics contains safe build-level telemetry: detectedGraphCount, reviewableTraceCount, curveOutcome, curvesWaived, and safeFailureCode. Detected graphs count document graphs found by processing. Reviewable traces count extracted traces that reached source-and-overlay review. Saved curves remain the separate applied-summary curveCount. These fields never contain source text, filenames, curve points, model output, or object keys. While curve work is pending, curveOutcome is processing. Pending work does not report missing curves or offer continue_without_curves. Missing-curve requirements are evaluated after processing settles. Status reads use saved image references; image retrieval and acceptance verify availability.

After a timeout or disconnect:

1. Call GET with catalog:read.
2. If the intended mutation is already reflected, continue from the returned version.
3. Otherwise retry the exact request with its original idempotency key.
4. For an unfinished expired upload, rotate the ticket with its current generation. Never reuse the

old capability after rotation.

Concurrent process or revision requests are fenced by currentVersion and an internal mutation generation. A stale version returns a conflict instead of overwriting newer decisions.

Issue and curve review contract

Each issue has a stable key, safe code, field path, message, evidence locators, allowed response types, and blocksApply. Submit only the minimum operations needed to answer current blocking issues. A later version can replace the issue set, so always use the newest issue key and version. If a submitted key is stale, duplicated, or no longer permits that response, EKX returns CATALOG_BUILD_REVISION_CONFLICT; reread the build before retrying with a new idempotency key.

For an issue path ending in .identity, provide_value must contain one object with manufacturer, modelNumber, and category. The issue evidence lists the supported category values.

For an invalid optional configuration fact, submit provide_value with null to omit that fact after review. You can include reason (1–300 characters) to explain a source discrepancy or a review decision. The saved record retains that explanation and the reviewed values with their source pages. Existing values are retained unless review explicitly replaces them; omitted facts are never replaced with guessed trip settings. Large summaries retain up to 200 entries, including curve warnings and an explicit omitted-detail count with the build ID when needed.

A new breaker requires an explicit configuration.tripMode: integrated, separate_trip_unit, or none. A missing value remains a blocking issue and cannot be resolved with null. Supplied configuration fields must match the selected device category; unsupported fields become review issues rather than unchecked catalogue data.

For a curves-only import, a manufacturer drawing may name a family rather than the full catalogue order number. An unambiguous source identity from the same manufacturer can offer associate_curve with source and target evidence. Verify applicability from the drawing and use the issue's Association item reference; this records the association without changing catalogue facts. The current overlay still requires a separate accept_curve. Association issues also offer redigitize so incomplete extraction can be corrected before association or approval. A native ETAP build names its exact target, optional SKUs, and applicability evidence when it is created, or creates its own series and SKUs from one base model (revisions may be mixed, each record from its own manifest), so its curves arrive associated and need only accept_curve or reject_curve. While a native curve awaits that decision, the build does not raise CURVES_REQUIRED; rejecting every curve raises it. A native build without a target uses the ordinary package identity matching, so it can raise POSSIBLE_IDENTITY_MATCH and fact conflicts against an existing series. Records it leaves out are listed in limitations.

A link to a curve hosted elsewhere is not a curve supplied in the PDF. When document processing successfully finds no graphs, optional imports report not_provided; required imports remain blocked for missing curves. Neither case is an extraction failure.

A required missing curve or final extraction failure can offer continue_without_curves. Submit it only against the current issue key. This build-wide waiver omits every new curve from the build, including accepted candidates, and preserves curves already saved on catalogue records. The same waiver is never a curve-worker draft operation. Polling and retries read the persisted waiver and do not recreate a failed-job blocker. Retry temporary failures while retry_processing remains available.

An accept_curve operation requires the current reviewFingerprint. Before acceptance, retrieve both the source and overlay image and show them to the engineer. Missing or stale images keep the curve blocked. Raw point arrays are never accepted in a revision.

Review copies may be resized for display; the stored canonical source remains unchanged. The plugin's get_catalog_curve_review tool returns both images inline once with a reviews array for candidates sharing that graph. Review every listed candidate against that image pair; you do not need to download the same pair again for each segment. Each accepted candidate still requires its own current fingerprint. Submit at most 20 resolution operations per call and read the current build before submitting another batch.

You can review more than 20 curve candidates, but a build can save at most 20 new curves across all its records, or 500 for a native ETAP build. If you accept more, CURVE_SAVE_LIMIT_EXCEEDED blocks saving and offers reject_curve for each accepted curve. Reject enough curves to bring the accepted set within the limit. Curves retained through keep_existing do not count toward it.

Correct graph calibration

When an issue offers correct_calibration, retrieve the current canonical source image and choose two visible tick marks on each axis. Use the outer graph ticks: these four positions also define the corrected plot bounds. Supply page-point coordinates, with the origin at the page's top left, x increasing rightward, and y increasing downward. For an unrotated 300-DPI canonical PNG, convert original image pixels to page points by multiplying by 72 / 300. Do not measure a resized preview. For a rotated source, map the displayed image back to the source page coordinates first. On a scan printed slightly askew, measure each x tick where its grid line meets the bottom of the plot and each y tick where its grid line meets the left side.

Send this operation inside the revision's operations array, using the current issue key, curveRef, and expectedVersion. The positions and values below are illustrative; measure your own source.

{
  "type": "correct_calibration",
  "issueKey": "<current issue key>",
  "curveRef": "<current curve reference>",
  "calibration": {
    "x_points": [
      { "position": 80, "value": 100, "label": "100" },
      { "position": 500, "value": 100000, "label": "100000" }
    ],
    "y_points": [
      { "position": 100, "value": 10000, "label": "10000" },
      { "position": 700, "value": 0.001, "label": "0.001" }
    ],
    "x_scale": "log10",
    "y_scale": "log10",
    "supplied_by_user": true
  }
}

Each axis requires exactly two points. X values must be positive and increase left to right; y values must be positive and decrease top to bottom. Each scale is log10 or linear. The supplied_by_user flag identifies an explicit correction instead of automatic calibration; it does not accept the resulting curve. Units and current basis still need source evidence.

After correction, follow resume_processing until work settles. Curve references and fingerprints can change during the rerun. Fetch the replacement source and overlay and resolve the new issue set before asking for curve acceptance.

Applied curve outcomes

Each new applied record summary includes curveOutcome and limitations. Older retained summaries may omit both fields. Clients must not invent record attribution when they are absent.

curveOutcome is one of not_expected, not_provided, imported, incomplete, skipped_after_failure, or not_imported. It describes what this build imported, not everything currently saved on the catalogue record. Package-level limitations remain in the applied summary for the final agent report; record-level limitations include only that record's constraints.

Safety and data lifecycle

Creating, uploading, processing, revising, reading, or canceling a catalogue build never mutates a project. Only successful package apply changes the organization-private catalogue, and it commits all series, SKUs, compatibility links, provenance, and accepted curves together.

Build activity extends a 30-day expiry. Build-owned source and overlay images are retained through active review even when ordinary intermediate artifacts age out. Terminal source and curve objects are deleted through exact-key cleanup claims or queues; content-addressed objects remain while referenced elsewhere. After 30 terminal days, detailed build content is purged while the terminal status and applied summary remain available as a safe tombstone. Organization offboarding removes all rows and objects under catalog-build/sources/orgs/{organizationId}/ and catalog-build/review/orgs/{organizationId}/.

Error codes

Route errors use the v1 envelope { "error": { "code", "message" } }. Validation errors can add details. Codes are stable; messages can change. A 429 or IDEMPOTENCY_IN_PROGRESS response includes Retry-After.

Authentication, access, and requests

Builds, processing, and apply

Curve review and revisions

Uploads

PUT /api/catalog-build-uploads/{sourceId} returns these codes, and they can appear as a source's safeErrorCode.

A failed upload can be retried with the same ticket while it is unexpired. After it expires, call refresh_catalog_import_upload (or the upload-ticket route) and retry with the new generation.

Native ETAP inspection

POST /api/v1/catalog-builds/etap/inspect returns these with status 400. Messages never quote the export's contents. With records, a failing record reports its code in its own result (ok: false), and the request returns 400 only when the manifest itself cannot be read.

Issue codes

Each issue has one of these code values. Resolve it only with the issue's allowed responses.

Failure codes

A failed, canceled, or expired build reports safeFailure.code, and curveDiagnostics can report safeFailureCode. Besides the provider and worker failure codes above, these can appear:

MCP tool errors

The EKX MCP tools return the route codes above in structuredContent.error.code, with httpStatus. They add these codes:

For the three retryable codes, the mutation may have completed. Read the build first, and retry with the same idempotency key only if the change is not reflected. When the MCP server itself rate-limits a request, it answers with HTTP 429, Retry-After, and a JSON-RPC error whose data contains code: "RATE_LIMITED" and retryAfterSeconds. A tool that needs a permission the connection lacks asks you to reconnect EKX; reconnecting requests every EKX permission.