POST
/api/optimizeSubmit 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. Generate your API key from the User Portal → API Keys section.
Get Your API Key
Sign in and go to Dashboard → API Keys to create and manage your API keys. Each key includes 100 requests/month with automatic usage tracking.
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_hereRequest 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 sheetplacements[]- Placed pieces with x, y coordinatesefficiency- Sheet utilization percentageunplacedPieces[]- Pieces that couldn't fittotalSheetsUsed- Number of stock sheets neededoverallEfficiency- 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 |
| 401 | INACTIVE_API_KEY | API key has been deactivated | Re-enable the key in the user portal |
| 429 | RATE_LIMIT_EXCEEDED | Monthly credit limit exceeded (200 credits/month, 2 per call) | Wait for monthly credit reset on the 1st of each month |
| 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"
]
}Ready to Integrate?
Start using the API today. Need help or have questions? Contact our support team.