Integration API

The CUTL Integration API lets your own software work with CUTL directly: submit a DXF, STEP or PDF drawing and read back the geometry and a full price, read your projects with their quoted prices, fetch a project's nesting with sheet images and machine DXF files, and check your coin balance. Prices come from the same engine the app uses. Writing projects, webhooks and multiple tokens are still in design (see the preview section at the end of this page).

Authentication

Every request carries your integration token in a header:

X-Auth-Token: <token>

• Each account holds one integration token. Generate it in the app on the Integration tab of your account settings (the same action is exposed as PUT /v2/security/user/key).
• Generating a new token immediately invalidates the previous one. Every integration still using the old token starts failing with 401 at that moment, so rotate deliberately and update all consumers straight after regenerating.
• The token grants full account access and does not expire on its own.

Coin billing

There is no free sandbox: the API runs against production, and every calculation debits real coins from your team balance at the same rates as the app (about 100 coins per part calculation). When the balance is too low, the request is rejected up front rather than run and charged. Plan integration tests sparingly, watch your balance in the app's billing area or with GET /v2/integration/balance, and see Coins & billing for rates and top-ups.

What is live

Responses come as JSON by default; send Accept: application/xml if your system prefers XML.

API reference

Every live endpoint with its parameters and full response schema. Click Authorize and paste your integration token to try the read-only (GET) requests against your own account. Submitting a calculation is left to your own code, because each one costs coins.

The sections below explain how the endpoints behave in practice.

Calculate a single drawing

Submit one drawing as base64, then poll the result by id. CUTL detects the file type from the content, not the file name. DXF and STEP files can be up to 2 MB, PDF drawings up to 20 MB. Pricing is returned only when both materialId and cuttingModeId are supplied; geometry is always returned. The optional units field (for example MILLIMETERS or INCHES) tells CUTL what unit the drawing is really in, which fixes a drawing whose unit was detected wrongly.

# Submit, returns 202
DXF_B64=$(base64 -i part.dxf | tr -d '\n')
curl -sS -X POST "$BASE/v2/integration/calculations" \
  -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -d "{\"fileName\":\"part.dxf\",\"fileBase64\":\"$DXF_B64\",\"materialId\":\"7e1...\",\"cuttingModeId\":\"4a8...\",\"units\":\"MILLIMETERS\"}"

# Poll, returns 200
curl -sS "$BASE/v2/integration/calculations/<calcId>" -H "X-Auth-Token: $TOKEN"

Once status is COMPLETED the geometry fields are populated; the pricing and weight fields appear only when a material and cutting mode were supplied. validationResult carries the parser's checks and warnings (for example overlapping or unclosed contours). A failed parse reports FAILED with a failureReason and an errorCode such as ERROR_READ_DXF, STEP_ASSEMBLY or INSUFFICIENT_BALANCE; a missing or stale token returns 401.

PDF drawings

A PDF is not priced in one go. CUTL extracts the cut contours into candidate parts, and the completed poll returns them in pdfCandidates. Each candidate has a dxfUrl (a cut-contour DXF), the page it came from, a confidence value and the detected scale, with needsScaleConfirm set when the true size is not confirmed. Several candidates can be different views of the same physical part, so check the low-confidence ones. To price a candidate, download its DXF and submit it as a new calculation with your material, cutting mode and units.

Check your balance

curl -sS "$BASE/v2/integration/balance" -H "X-Auth-Token: $TOKEN"

balance is the spendable total, bonus coins included, and is the number CUTL checks before it accepts work. It can go below zero, because some operations bill per item after an up-front check. bonusBalance is the part of the total made up of bonus coins, which are spent first. When a charge takes the balance below lowBalanceThreshold, the team's administrators get one email; nothing stops working at that level.

Reading the balance before you submit a batch is the easy way to avoid having work refused for lack of coins (402 with error code C00034).

Read projects

# List projects, newest first, 10 per page by default
curl -sS "$BASE/v2/integration/projects?updatedFrom=2026-09-01&page=0&size=20" -H "X-Auth-Token: $TOKEN"

# One project in full
curl -sS "$BASE/v2/integration/projects/<projectId>" -H "X-Auth-Token: $TOKEN"

The list takes optional date filters (createdFrom, createdTo, updatedFrom, updatedTo) plus page and size. Without filters you get the team's projects, most recently updated first. A date window may span at most one month; a longer one is refused with 400. Each entry carries the project's id, name, code, customer and organisation, and its prices: price and clientPrice (the total the customer is quoted, after markup), with the tax figures alongside.

A single project adds the detail behind the quote:

• projectParts: every part with its count, material, cutting mode, operations, size, cut length, cutting time and prices (pre-markup and client), plus a base64 thumbnail in image.
• materialSummary: one row per material with its cut area and totals.
• nestingSheets: one row per physical nested sheet, as costed on the quote (material, sheet size, weight, cost and utilisation).
• Quote details such as currency, validUntil, paymentTerm and deliveryCost.

Fetch a project's nesting

curl -sS "$BASE/v2/integration/projects/<projectId>/nesting?format=CYPCUT" -H "X-Auth-Token: $TOKEN"

This reads the nesting behind a project's quote; it does not run a new one. Choose the DXF flavour with format: STANDARD_DXF (the default), CYPCUT or RDWORKS. The first call starts the DXF export and image render and answers PENDING; keep polling until the status is READY. PARTIAL means some materials are ready and others failed, and FAILED means all failed.

There is one entry in nests per material. Sheets with an identical layout are collapsed into one entry with a count, so twenty identical sheets come back as one entry with count 20. partId matches the part id from the project endpoint, so you can join the two.

Refresh a file link

Some responses contain stored file URLs. To get a fresh signed link for one of them, send it to POST /v2/integration/data-assets/signed-url with a body of {"url": "<stored url>"}. The response gives the signed url and its expiresAt time. You can only sign files that belong to your own team.

Preview: writes, webhooks and more

Reading is live today (see above). The planned additions are about writing and automation:

• Creating and changing projects, parts, quick calculations and nesting jobs through the API, with drawings uploaded as base64 and results carrying the same figures the in-app panels show.
• Dictionary CRUD for materials, equipment, cutting modes and customers, so integrations can manage reference data instead of mirroring it.
• Webhooks: results pushed to your system (HMAC-signed, at-least-once delivery with retries) instead of polling.
• Conventions on the roadmap: RFC 7807 problem+json errors, idempotency keys on mutating calls, per-token rate limits, and an explicit major-version deprecation policy.
• Multi-token management (listing, revocation, per-token audit) replacing today's single regenerating token.

Next, see Coins & billing to understand what each calculation costs and how to keep your balance topped up.