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 | | POST | /v3/model/analysis | Analyse a 3D model into parts | 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 | 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 | sync | | GET | /v3/export/biesse | Export result as Biesse XML CutList | sync | | GET | /v3/saws | List saws and the export formats each offers | 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.