{
  "markdown": "# SmartCut API\n\nSmartCut is a hosted cutting-optimisation (cutlist / nesting) API for sheet,\nlinear and roll stock. This repository holds the OpenAPI specification, runnable\nexamples and MCP configuration for integrating it into your own software.\n\n[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)\n[![OpenAPI 3.0](https://img.shields.io/badge/OpenAPI-3.0-green.svg)](openapi/v3.json)\n[![Docs](https://img.shields.io/badge/docs-smartcut.dev-informational.svg)](https://smartcut.dev/docs)\n\n## What it does\n\n- **Sheet optimisation** — guillotine (edge-to-edge, saw-cuttable) and efficiency\n  modes for plywood, MDF, glass, plastic and sheet metal.\n- **Linear (1D) optimisation** for timber, bar, pipe and extrusion.\n- **True-shape nesting** for irregular parts from DXF, for laser, plasma,\n  waterjet and CNC routing.\n- **Grain direction and per-part orientation locks**, so a part can be pinned to\n  the length or width of the grain, or left free to rotate.\n- **Edge banding, face finishes, blade kerf and stock trim** as first-class\n  inputs, not post-processing.\n- **Machine-ready exports** — PDF, CSV, DXF, SVG, and native saw formats\n  including PTX (Homag), Biesse XML and Mayer `.may`.\n- **Printable part labels** generated from the same result.\n\n## Quickstart\n\nGet a key at <https://smartcut.dev/account>, then:\n\n```bash\ncurl -X POST https://api.smartcut.dev/v3/calculate \\\n  -H \"Authorization: $SMARTCUT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d @examples/requests/guillotine.json\n```\n\nThat returns a job id. Poll until it is ready, then fetch the result:\n\n```bash\ncurl \"https://api.smartcut.dev/v3/result/ready?id=$JOB_ID\" -H \"Authorization: $SMARTCUT_API_KEY\"\ncurl \"https://api.smartcut.dev/v3/result?id=$JOB_ID\"       -H \"Authorization: $SMARTCUT_API_KEY\"\n```\n\nThe result carries one entry per stock piece, each listing the parts placed on\nit with their positions, the cuts needed to produce them, and the offcut left\nover. Complete runnable versions in four languages are in\n[`examples/`](examples/).\n\n## Authentication\n\nPass the raw API key in the `Authorization` header:\n\n```\nAuthorization: YOUR_API_KEY\n```\n\n**There is no `Bearer` prefix.** This is the single most common integration\nmistake — a `Bearer ` prefix returns 401.\n\n## Endpoints (v3)\n\n<!-- This table is generated from the OpenAPI specification on release.\n     Edits between the markers are overwritten. -->\n<!-- generated:endpoints -->\n| method | path | what it does | sync |\n|---|---|---|---|\n| POST | `/v3/calculate` | Submit calculation | async |\n| POST | `/v3/validate` | Validate inputs without calculating | sync |\n| POST | `/v3/model/analysis` | Analyse a 3D model into parts | sync |\n| GET | `/v3/result/ready` | Check if calculation is complete | sync |\n| GET | `/v3/result` | Retrieve calculation result | sync |\n| GET | `/v3/export/pdf` | Export result as PDF | sync |\n| GET | `/v3/export/csv` | Export result as CSV | sync |\n| GET | `/v3/export/ptx` | Export result as PTX | sync |\n| GET | `/v3/export/dxf` | Export result as DXF | sync |\n| GET | `/v3/export/svg` | Export result as SVG | sync |\n| GET | `/v3/export/mayer` | Export result as Mayer .may | sync |\n| GET | `/v3/export/biesse` | Export result as Biesse XML CutList | sync |\n| GET | `/v3/saws` | List saws and the export formats each offers | sync |\n| POST | `/v3/labels` | Generate printable part labels | sync |\n| POST | `/webhooks/result` | Calculation result delivery | — *your* endpoint |\n| GET | `/v3/calls` | Get API usage statistics | sync |\n<!-- /generated:endpoints -->\n\nFull reference: <https://smartcut.dev/api-docs/v3>\n\n## How the async model works\n\nOptimisation takes longer than a request should block for, so `/v3/calculate`\nreturns a job id immediately. You then either poll `/v3/result/ready` until it\nreports done, or register a webhook and let SmartCut POST to you when the result\nis available. Either way you fetch the payload from `/v3/result`.\n\nWebhook registration, signature verification and retry behaviour are documented\nat <https://smartcut.dev/docs/webhooks>.\n\n## MCP server\n\nSmartCut runs a hosted [Model Context Protocol](https://modelcontextprotocol.io)\nserver, so an agent can run optimisations directly with your existing API key.\n\n```\nPOST https://api.smartcut.dev/mcp\n```\n\nStreamable HTTP transport. Authentication is the same raw key in the\n`Authorization` header, **without** a `Bearer` prefix. Configuration for Claude\nDesktop and other clients is in [`mcp/`](mcp/).\n\nTools: `calculate`, `validate`, `status`, `result`, `cancel`, `usage`, `export`,\n`labels`, `list_cut_types` — plus `import_parts`, which is different from the\nrest: it pushes parts an agent has extracted (from a PDF or a photo of a cutting\nplan) into an open [Cutlist Evolution](https://cutlistevo.com) editor for the\nuser to confirm, rather than calling the optimisation API.\n\nThe `calculate` tool waits for the result in-call (about 25 seconds by default,\noverridable with `waitMs`) and falls back to returning a job id if the\noptimisation is still running, so an agent usually gets a layout in one call.\n\n## Generating a client\n\n**There is no official SDK, and that is deliberate.** The API is a JSON body and\none header, so `fetch` is already the client — and a generated client in your own\nidiom will fit your codebase better than a hand-written one would. Point any\ngenerator at the spec:\n\n```bash\nnpx openapi-typescript openapi/v3.json -o smartcut.d.ts\nnpx @hey-api/openapi-ts -i openapi/v3.json -o src/smartcut\nopenapi-generator-cli generate -i openapi/v3.json -g python -o ./smartcut-python\n```\n\n## Examples\n\n| language | file |\n|---|---|\n| curl | [`examples/curl/optimise.sh`](examples/curl/optimise.sh) |\n| Node | [`examples/node/optimise.mjs`](examples/node/optimise.mjs) |\n| Python | [`examples/python/optimise.py`](examples/python/optimise.py) |\n| PHP | [`examples/php/optimise.php`](examples/php/optimise.php) |\n\nEach reads a payload from [`examples/requests/`](examples/requests/), which is\ngenerated from the specification — so the examples cannot drift from the schema.\n\n## What this is, and is not\n\nSmartCut is a **hosted service with a subscription**, not a self-hosted library.\nIt suits quoting, order processing, e-commerce cut-to-size checkout and CAM\nhand-off, where you want optimisation quality and saw-format output without\nmaintaining a geometry engine. If you want an in-process bin-packer with no\nnetwork call and no account, this is the wrong tool and an open-source packing\nlibrary is the right one.\n\n## Links\n\n- Documentation — <https://smartcut.dev/docs>\n- Interactive API reference — <https://smartcut.dev/api-docs/v3>\n- Get an API key — <https://smartcut.dev/account>\n- Published benchmarks — <https://smartcut.dev/benchmarks>\n- WooCommerce plugin — <https://github.com/jgmedialtd/smartcut-wp-plugin>\n\n## Support\n\nIssues here are for the **specification and the examples** only. For API access,\nbilling, quota or integration support, use the contact form at\n<https://smartcut.dev/contact>. Specification files are generated and cannot be\nchanged by pull request — see [`openapi/README.md`](openapi/README.md).\n",
  "bytes": 7146,
  "sha": "41c3408961b2251561b29aa63725d9d5513e77fe170e5dfcdfde85e38953e812",
  "repo_slug": "jgmedialtd/smartcut-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_smartcut_cutlist_optimizer_4d5f0fea/readme"
}