API Reference

SmartCut is a hosted cutting-optimization API for sheet, linear and roll materials. You send a list of parts and the stock you can buy, and it returns a cutting pattern with diagrams, labels and machine-ready files.

The specification, runnable examples in four languages and the MCP configuration all live in the public repository at github.com/jgmedialtd/smartcut-api.

Prefer an LLM client?

The same v3 API is available over the Model Context Protocol. Submit jobs, fetch layouts and generate exports from Claude, Cursor or your own agent, using the same API key.

Quick start

Get an API key from your account, then submit a job. Pass the key raw in the Authorization header. There is no Bearer prefix, and adding one returns 401. It is the commonest integration mistake by a distance.

curl -X POST https://api.smartcut.dev/v3/calculate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "saw": { "cutType": "guillotine", "cutPreference": "l", "bladeWidth": 3, "stockType": "sheet" },
    "stock": [ { "l": 2400, "w": 1200, "t": 18, "material": "Plywood", "grain": "l" } ],
    "parts": [ { "l": 400, "w": 300, "t": 18, "material": "Plywood", "q": 5 } ]
  }'

That responds with a job id:

{ "jobId": 12345 }

Optimization takes longer than a request should block for, so it runs asynchronously. Poll until the result exists, then fetch it:

# 200 = ready, 404 = not finished yet, 410 = expired and gone.
# This endpoint answers with a STATUS CODE and no body.
curl -i "https://api.smartcut.dev/v3/result/ready?id=12345" -H "Authorization: YOUR_API_KEY"

curl "https://api.smartcut.dev/v3/result?id=12345" -H "Authorization: YOUR_API_KEY"

In production you would usually register a webhook instead and skip polling entirely.

The result carries one entry per stock piece, listing the parts placed on it with their positions, the cuts needed to produce them, and the offcut left over. The export endpoints turn that same result into PDF, CSV, DXF, SVG or a native saw file.

Complete runnable versions in curl, Node, Python and PHP are in the examples directory.

There is no SDK, by design

The API is a JSON body and one header, so fetch is already the client, and a client generated in your own idiom will fit your codebase better than one we hand-wrote. Point any generator at the specification:

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

Interactive reference

V3 is current. Build against it.

V3 reference →

V2 is maintained and receives no new features.

V2 reference →

V1 is deprecated and kept only for integrations that already use it. Do not start new work against it.

V1 reference →

The saw object has its own explorer: every field with its allowed values and defaults, which saw states each one applies to, the stock-type × cut-type matrix, the rules that resolve contradictory settings instead of rejecting them, and the recognised saw profiles. Paste a saw into it and it shows exactly what the API would run.

Saw settings explorer →