API Documentation | 2D Cutting Optimization API

POST/api/optimize

Submit pieces and stock sheets to receive optimized cutting layouts with placement coordinates, efficiency metrics, and waste calculations.

Authentication

All API requests require an API key passed in the x-api-key header.

Keep your API key secure

Never expose your API key in client-side code. Use environment variables and server-side requests.

Header

x-api-key: sk_opt_2d_your_secret_key_here

Request Body

Send a JSON object containing pieces,stockSheets, andsettings.

pieces[] - Cut Pieces (max 1000)

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the piece
`label`	string	Yes	Display name for the piece
`width`	number	Yes	Width in your unit (mm recommended). Max: 100,000
`height`	number	Yes	Height in your unit. Max: 100,000
`quantity`	integer	Yes	Number of pieces needed. Min: 1
`canRotate`	boolean	Yes	Whether this piece can be rotated 90°
`material`	string	No	Optional material identifier
`priority`	integer	No	Optional priority (lower = higher priority)

stockSheets[] - Stock Sheets (max 100)

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the stock sheet
`name`	string	Yes	Display name for the sheet
`width`	number	Yes	Sheet width. Max: 100,000
`height`	number	Yes	Sheet height. Max: 100,000
`quantity`	integer	Yes	Available quantity. Min: 1
`grainDirection`	string	No	One of: horizontal, vertical, none
`material`	string	No	Optional material identifier
`cost`	number	No	Cost per sheet (for calculations)

settings - Optimization Settings

Field	Type	Required	Description
`bladeKerf`	number	Yes	Blade thickness in your unit. Range: 0-100
`allowRotation`	boolean	Yes	Global rotation setting
`padding`	number	Yes	Edge padding/margin. Range: 0-1000

Example Request Body

JSON

{
  "pieces": [
    {
      "id": "p1",
      "label": "Side Panel",
      "width": 600,
      "height": 400,
      "quantity": 4,
      "canRotate": true
    },
    {
      "id": "p2",
      "label": "Top Panel",
      "width": 800,
      "height": 300,
      "quantity": 2,
      "canRotate": false
    }
  ],
  "stockSheets": [
    {
      "id": "s1",
      "name": "Plywood 4x8",
      "width": 2440,
      "height": 1220,
      "quantity": 10
    }
  ],
  "settings": {
    "bladeKerf": 3,
    "allowRotation": true,
    "padding": 5
  }
}

Response

Successful requests return a JSON object with success: true and the optimization results in data.

Response Fields

layouts[] - Array of cutting layouts, one per used sheet
placements[] - Placed pieces with x, y coordinates
efficiency - Sheet utilization percentage
unplacedPieces[] - Pieces that couldn't fit
totalSheetsUsed - Number of stock sheets needed
overallEfficiency - Total material efficiency %
computeTimeMs - Algorithm execution time

Example Response

JSON

{
  "success": true,
  "data": {
    "layouts": [
      {
        "sheetIndex": 0,
        "stockSheet": { "id": "s1", "name": "Plywood 4x8", ... },
        "placements": [
          {
            "pieceId": "p1",
            "label": "Side Panel",
            "x": 5,
            "y": 5,
            "width": 600,
            "height": 400,
            "rotated": false,
            "sheetIndex": 0
          },
          ...
        ],
        "usedArea": 1680000,
        "wasteArea": 297680,
        "efficiency": 84.9
      }
    ],
    "unplacedPieces": [],
    "totalSheetsUsed": 1,
    "totalWaste": 297680,
    "overallEfficiency": 84.9,
    "computeTimeMs": 12
  }
}

Code Examples

cURL

bash

curl -X POST https://your-domain.com/api/optimize \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "pieces": [...],
    "stockSheets": [...],
    "settings": {...}
  }'

JavaScript / TypeScript

javascript

const response = await fetch('/api/optimize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.OPTIMIZER_API_KEY
  },
  body: JSON.stringify({
    pieces: [...],
    stockSheets: [...],
    settings: { bladeKerf: 3, allowRotation: true, padding: 5 }
  })
});

const result = await response.json();
console.log(result.data.layouts);

Python

python

import requests

response = requests.post(
    'https://your-domain.com/api/optimize',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here'
    },
    json={
        'pieces': [...],
        'stockSheets': [...],
        'settings': {'bladeKerf': 3, 'allowRotation': True, 'padding': 5}
    }
)

result = response.json()
print(result['data']['layouts'])

Error Handling

Error responses include an error message,code, and optionaldetails array.

Status	Code	Description	Fix
401	`MISSING_API_KEY`	No x-api-key header provided	Add x-api-key header to your request
401	`INVALID_API_KEY`	API key does not match	Check your API key is correct
400	`INVALID_JSON`	Request body is not valid JSON	Validate your JSON syntax
400	`VALIDATION_ERROR`	One or more fields failed validation	Check the details array for specific field errors
405	`METHOD_NOT_ALLOWED`	Wrong HTTP method used	Use POST method
500	`OPTIMIZATION_ERROR`	Algorithm execution failed	Check input data for edge cases
500	`SERVER_CONFIG_ERROR`	Server misconfiguration	Contact support

Example Error Response

JSON

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    "pieces[0].width: must be a positive number (max 100000)",
    "settings.bladeKerf: must be a number between 0 and 100"
  ]
}

Limits

1,000

Max pieces per request

100

Max stock sheets per request

100,000

Max dimension value (mm)

Ready to Integrate?

Start using the API today. Need help or have questions? Contact our support team.

Try the Optimizer Contact Support