CutOptim Engine API — Python SDK

Cutting optimization over HTTPS: 2D panels, 1D linear, timber and true-shape nesting.
Deterministic plans, saw-ready cut sequences — standard library only.

Quickstart · API reference · Webhooks · Changelog · Get an API key

Why this SDK

• Typed from the contract. Request and response shapes are TypedDicts generated from the OpenAPI 3.1 document — mypy and your editor know every field.
• No dependencies. urllib, json and hmac from the standard library; Python 3.9+.
• Retries that never cost twice. Every optimize call carries an Idempotency-Key; a retried call returns the stored answer instead of a second charge.
• Async jobs without the boilerplate. wait_for_job() polls the max engine for you — or let a webhook tell you.
• Webhook verification built in. verify_webhook() checks the signature on the raw body, with the replay window and secret rotation handled.

Install

pip install cutoptim

A free test key (co_test_…, never billed) is enough to build the whole integration — create one on your dashboard.

Quickstart

import os
from cutoptim import CutOptim, is_job_accepted

client = CutOptim(api_key=os.environ["CUTOPTIM_KEY"])

plan = client.optimize_2d({
    "parts": [
        {"name": "Side", "w": 720, "h": 560, "qty": 2},
        {"name": "Shelf", "w": 764, "h": 540, "qty": 3, "rotatable": False},
    ],
    "stock": [{"w": 2800, "h": 2070, "price": 48}],
    "options": {"kerf": 4},
})

if not is_job_accepted(plan):
    print(f"{plan['metrics']['sheetCount']} sheet(s), {plan['metrics']['yieldPct']}% yield")
    for sheet in plan["sheets"]:
        for p in sheet["parts"]:
            print(p["name"], p["x"], p["y"], p["w"], p["h"], "rotated" if p["rotated"] else "")

The same input always returns the same plan — cache it, test against it, quote from it.

Every mode

# 1D linear — bars, profiles, tubes
bars = client.optimize_1d({"parts": [{"name": "Rail", "length": 1200, "qty": 6}], "stock": [{"length": 6000}]})
print(bars["metrics"]["rodCount"], bars["metrics"]["yieldPct"])

# Timber — lengths cut from beams of a given cross-section (sw × sh)
timber = client.optimize_wood({
    "parts": [{"name": "Joist", "sw": 45, "sh": 145, "length": 3600, "qty": 4}],
    "stock": [{"sw": 45, "sh": 145, "length": 4800}],
})

# True-shape nesting — polygons (or SVG/DXF sources) on sheets
nest = client.optimize_nest({
    "parts": [{"name": "Bracket", "polygon": [[0, 0], [120, 0], [120, 40], [40, 120], [0, 120]], "qty": 10}],
    "stock": [{"w": 1000, "h": 500}],
})
if not is_job_accepted(nest):
    print(nest["metrics"]["sheetCount"], nest["metrics"]["density"])

Check a request without spending a call — the validate endpoints need no key and give the same verdict:

CutOptim().validate_2d(request)  # {"valid": True, "warnings": [...]} or CutOptimError(400)

Async max jobs

"engine": "max" searches harder (seconds to a minute) and answers 202 with a job id instead of a plan:

accepted = client.optimize_2d({**request, "engine": "max"})
if is_job_accepted(accepted):
    job = client.wait_for_job(accepted["jobId"], timeout_s=300)  # polls GET /v1/jobs/{id}, no quota
    if job["status"] == "succeeded":
        print(job["result"])

Webhooks

Instead of polling, register an endpoint on your dashboard and receive a signed POST (job.succeeded / job.failed) when a max job finishes. Verify it on the raw body:

# Flask
from flask import Flask, request
from cutoptim import verify_webhook

@app.post("/cutoptim/webhook")
def cutoptim_webhook():
    if not verify_webhook(request.get_data(), request.headers.get("CutOptim-Signature"), WEBHOOK_SECRET):
        return "", 400
    event = request.get_json()   # deduplicate on event["id"] — delivery is at least once
    return "", 204               # answer within 10 s, then do the work

# FastAPI
from fastapi import FastAPI, Request, Response

@app.post("/cutoptim/webhook")
async def cutoptim_webhook(request: Request):
    raw = await request.body()
    if not verify_webhook(raw, request.headers.get("CutOptim-Signature"), WEBHOOK_SECRET):
        return Response(status_code=400)
    return Response(status_code=204)

During a secret rotation both secrets sign for 24 hours — pass both: verify_webhook(raw, header, [new_secret, old_secret]).

Retries and idempotency

Pass your own key to make retries safe across process restarts too:

client.optimize_nest(request, idempotency_key=f"order-{order_id}")

Within 24 hours the same key and request return the stored answer — not charged again, and a max job is not queued twice.

Errors

Any non-2xx answer raises CutOptimError:

from cutoptim import CutOptimError

try:
    client.optimize_2d(request)
except CutOptimError as e:
    print(e.status, e.code, e.details, e.retry_after)  # branch on e.code, never on the message

A network failure that outlasts the retries is raised as the underlying urllib.error.URLError. The full list is on the errors page.

Configuration

CutOptim(
    api_key="co_live_…",                   # not needed for health() and validate_*()
    base_url="https://api.cutoptim.com",   # default
    max_retries=2,                         # 429 / 503 / 409 in-progress / network errors
    timeout_s=30.0,                        # per request
)

API coverage

Versioning

The SDK follows semver. The API is v1 and only grows within it: a new field, endpoint or option arrives as a minor SDK release with the regenerated types; nothing you use today is removed or narrowed. See versioning and stability and the API changelog (also as RSS).

Support

• Questions and bugs: GitHub issues or support@cutoptim.com
• Limits and quotas: cutoptim.com/engine/reference/limits

This repository is published from the CutOptim monorepo; pull requests are welcome and applied upstream.

License

MIT © CutOptim