SmartCut API

SmartCut is a hosted cutting-optimisation (cutlist / nesting) API for sheet, linear and roll stock. This repository holds the OpenAPI specification, runnable examples and MCP configuration for integrating it into your own software.

What it does

• Sheet optimisation — guillotine (edge-to-edge, saw-cuttable) and efficiency modes for plywood, MDF, glass, plastic and sheet metal.
• Linear (1D) optimisation for timber, bar, pipe and extrusion.
• True-shape nesting for irregular parts from DXF, for laser, plasma, waterjet and CNC routing.
• Grain direction and per-part orientation locks, so a part can be pinned to the length or width of the grain, or left free to rotate.
• Edge banding, face finishes, blade kerf and stock trim as first-class inputs, not post-processing.
• Machine-ready exports — PDF, CSV, DXF, SVG, and native saw formats including PTX (Homag), Biesse XML and Mayer .may.
• Printable part labels generated from the same result.

Quickstart

Get a key at https://smartcut.dev/account, then:

curl -X POST https://api.smartcut.dev/v3/calculate \
  -H "Authorization: $SMARTCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d @examples/requests/guillotine.json

That returns a job id. Poll until it is ready, then fetch the result:

curl "https://api.smartcut.dev/v3/result/ready?id=$JOB_ID" -H "Authorization: $SMARTCUT_API_KEY"
curl "https://api.smartcut.dev/v3/result?id=$JOB_ID"       -H "Authorization: $SMARTCUT_API_KEY"

The result carries one entry per stock piece, each listing the parts placed on it with their positions, the cuts needed to produce them, and the offcut left over. Complete runnable versions in four languages are in examples/.

Authentication

Pass the raw API key in the Authorization header:

Authorization: YOUR_API_KEY

There is no Bearer prefix. This is the single most common integration mistake — a Bearer prefix returns 401.

Endpoints (v3)

<!-- This table is generated from the OpenAPI specification on release. Edits between the markers are overwritten. --> <!-- generated:endpoints -->

method	path	what it does	sync
POST	/v3/calculate	Submit calculation	async
POST	/v3/validate	Validate inputs without calculating	sync
GET	/v3/result/ready	Check if calculation is complete	sync
GET	/v3/result	Retrieve calculation result	sync
GET	/v3/export/pdf	Export result as PDF	sync
GET	/v3/export/csv	Export result as CSV	sync
GET	/v3/export/ptx	Export result as PTX (beam saw format)	sync
GET	/v3/export/dxf	Export result as DXF	sync
GET	/v3/export/svg	Export result as SVG	sync
GET	/v3/export/mayer	Export result as Mayer .may (Beta)	sync
GET	/v3/export/biesse	Export result as Biesse XML CutList (Beta)	sync
GET	/v3/saws	List saws + export formats offered	sync
GET	/v3/spec	Optimisation spec — selectable models + saws + their gating	sync
POST	/v3/labels	Generate printable part labels	sync
POST	/webhooks/result	Calculation result delivery	— your endpoint
GET	/v3/calls	Get API usage statistics	sync
<!-- /generated:endpoints -->

Full reference: https://smartcut.dev/api-docs/v3

How the async model works

Optimisation takes longer than a request should block for, so /v3/calculate returns a job id immediately. You then either poll /v3/result/ready until it reports done, or register a webhook and let SmartCut POST to you when the result is available. Either way you fetch the payload from /v3/result.

Webhook registration, signature verification and retry behaviour are documented at https://smartcut.dev/docs/webhooks.

MCP server

SmartCut runs a hosted Model Context Protocol server, so an agent can run optimisations directly with your existing API key.

POST https://api.smartcut.dev/mcp

Streamable HTTP transport. Authentication is the same raw key in the Authorization header, without a Bearer prefix. Configuration for Claude Desktop and other clients is in mcp/.

Tools: calculate, validate, status, result, cancel, usage, export, labels, list_cut_types — plus import_parts, which is different from the rest: it pushes parts an agent has extracted (from a PDF or a photo of a cutting plan) into an open Cutlist Evolution editor for the user to confirm, rather than calling the optimisation API.

The calculate tool waits for the result in-call (about 25 seconds by default, overridable with waitMs) and falls back to returning a job id if the optimisation is still running, so an agent usually gets a layout in one call.

Generating a client

There is no official SDK, and that is deliberate. The API is a JSON body and one header, so fetch is already the client — and a generated client in your own idiom will fit your codebase better than a hand-written one would. Point any generator at the spec:

npx openapi-typescript openapi/v3.json -o smartcut.d.ts
npx @hey-api/openapi-ts -i openapi/v3.json -o src/smartcut
openapi-generator-cli generate -i openapi/v3.json -g python -o ./smartcut-python

Examples

language	file
curl	examples/curl/optimise.sh
Node	examples/node/optimise.mjs
Python	examples/python/optimise.py
PHP	examples/php/optimise.php

Each reads a payload from examples/requests/, which is generated from the specification — so the examples cannot drift from the schema.

What this is, and is not

SmartCut is a hosted service with a subscription, not a self-hosted library. It suits quoting, order processing, e-commerce cut-to-size checkout and CAM hand-off, where you want optimisation quality and saw-format output without maintaining a geometry engine. If you want an in-process bin-packer with no network call and no account, this is the wrong tool and an open-source packing library is the right one.

Links

• Documentation — https://smartcut.dev/docs
• Interactive API reference — https://smartcut.dev/api-docs/v3
• Get an API key — https://smartcut.dev/account
• Published benchmarks — https://smartcut.dev/benchmarks
• WooCommerce plugin — https://github.com/jgmedialtd/smartcut-wp-plugin

Support

Issues here are for the specification and the examples only. For API access, billing, quota or integration support, use the contact form at https://smartcut.dev/contact. Specification files are generated and cannot be changed by pull request — see openapi/README.md.