Skip to content
Stella ConnectDocs
Parts

Nest linear parts onto stock bars

POST{baseUrl}/v2.0/3d/parts/nesting/linear

Solves a 1D bin-packing problem: given a set of part cut-lengths and a set of raw-stock bar lengths, decides how many bars are needed and which parts land on each bar, minimizing waste. Applies saw allowances (chuck at bar start, kerf per cut) and a per-stock remnant policy that governs whether leftover pieces are returned to inventory or billed as scrap.

Notes

  • Response PartId values echo the caller-supplied Parts[].PartId from the request when provided, otherwise a server-generated id. The id is an opaque correlation token — nothing on the server resolves it against a stored part. StockId values are always server-generated.
  • TotalNestedLength / TotalNestedWeight are proportional shares of the total stock consumed, allocated by each part's summed length. They include kerf + chuck; they are not simply Length × TotalItemsNested.
  • StockLayoutResponse.Parts[].Quantity and NumberOfPartsPerUnit are per single bar; multiply by NumberOfUnits for the aggregate count.
Authx-api-key

application/json
Field
Type
Required
Description
parts[]object[]Yes

Cut requirements: one entry per distinct part length + quantity.

parts[].partIduuid | nullNo

Opaque caller-supplied correlation id, echoed on the corresponding Parts[].PartId and on every matching Stock[].Parts[].PartId in the response. Never resolved against any stored part — if you need the nester to derive cut length from an imported part, use the linear-part-lookup endpoint instead. If omitted (or Empty), the server generates one per row; duplicates across rows in the same request are rejected.

parts[].partNamestringNo

Free-form display name echoed back on the corresponding Parts[].Name in the response. Not interpreted by the nester.

parts[].lengthnumberNo

Length of one cut piece, expressed in LengthUnit.

parts[].lengthUnitstringNo

Length unit for Length (e.g. "Inch", "Millimeter").

parts[].quantityintegerNo

How many copies of this length are required.

productobjectYes

The material grade being cut. Supplies weight-per-length so the total weight of cut pieces and stock consumed can be reported.

product.namestringNo

Display name of the product (e.g. "HSS 2x2x1/4 A500-B").

product.weightPerLengthnumberNo

Weight of the product per unit of length. Combined with the layout's stock length to compute weight totals in the response.

product.weightPerLengthUnitstringNo

Unit for WeightPerLength (e.g. "PoundPerFoot").

stock[]object[]Yes

Available raw-stock bars: one entry per distinct stock length + quantity, each with its own remnant-keeping policy.

stock[].lengthnumberNo

Length of one stock bar, expressed in LengthUnit.

stock[].lengthUnitstringNo

Length unit for Length.

stock[].quantityinteger | nullNo

How many bars of this length are available. Null means unlimited.

stock[].remnantPolicyobjectNo

Rules for whether to keep the leftover piece from each bar (a "remnant") or discard it.

stock[].remnantPolicy.keepRemnantbooleanNo

If false, remnants are never kept — the entire bar counts as consumed. If true, remnants are kept only when they meet MinimumLength and/or MinimumWeight.

stock[].remnantPolicy.minimumLengthnumber | nullNo

Minimum remnant length worth keeping. Ignored when KeepRemnant is false or when null.

stock[].remnantPolicy.lengthUnitstringNo

Unit for MinimumLength.

stock[].remnantPolicy.minimumWeightnumber | nullNo

Minimum remnant weight worth keeping. Ignored when KeepRemnant is false or when null.

stock[].remnantPolicy.weightUnitstringNo

Unit for MinimumWeight.

optionsobjectNo

Machine allowances (chuck at bar start, kerf per cut). May be null; both allowances then default to 0.

options.chucknumber | nullNo

Chuck / grip allowance at the start of every stock bar — length that cannot be cut because it is held in the saw's chuck.

options.chuckUnitstringNo

Unit for Chuck.

options.kerfnumber | nullNo

Kerf allowance — width of material the saw blade removes on each cut.

options.kerfUnitstringNo

Unit for Kerf.

outputLengthUnitstringYes

Length unit to use for all length values in the response. Default: "Inch". Must be a recognised length-unit name.

Status
When
200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

500

An unexpected error occurred on the server.

Field
Type
Required
Description
dataobject | nullNo

Result of a linear-nesting calculation: which parts landed on which stock bars, and how much of each stock was consumed.

data.nestingIduuidNo

Server-generated identifier for this nesting result. Pass it to RenderLinearNest3D to render the layout as an image.

data.parts[]object[]No

Per-part summary: one entry per distinct requested part length.

data.parts[].partIduuidNo

Echo of the caller-supplied Parts[].PartId from the request when one was provided; otherwise a server-generated id. See remarks on LinearNestingOutputResponse.

data.parts[].namestringNo

Echo of the caller-supplied Parts[].PartName from the request. Null when the request did not supply one.

data.parts[].lengthnumberNo

The requested cut length, restated in the request's output length unit. Send a 30 mm part on an inch nest and this reads 1.1811, not 30.

data.parts[].lengthUnitstringNo

The request's output length unit — not the unit the part was submitted in. Matches LengthUnit.

data.parts[].quantityintegerNo

Echo of the requested quantity. Compare against TotalItemsNested to detect a shortfall when stock was exhausted before all pieces could be placed.

data.parts[].totalItemsNestedintegerNo

Actual number of pieces placed across all stock bars. Equals Quantity when stock was sufficient; less when it was not.

data.parts[].totalNestedLengthnumberNo

This part's proportional share of total stock length consumed — TotalStockLengthUsed × (this part's summed length / all parts' summed length). Includes kerf and chuck allocated to this part; not simply Length × TotalItemsNested.

data.parts[].totalNestedWeightnumberNo

This part's proportional share of total stock weight consumed (same length-ratio allocation as TotalNestedLength). Includes waste (kerf + chuck) attributed to this part.

data.parts[].totalTrueWeightnumberNo

Net material weight of the finished cut pieces for this part — Length × TotalItemsNested × WeightPerLength. Excludes all waste. Difference from TotalNestedWeight is the waste share attributed to this part.

data.stock[]object[]No

Per-stock-variant layout: one entry per distinct stock length. Each entry describes how one bar of that variant is cut, and how many bars were used.

data.stock[].stockIduuidNo

Server-generated identifier for this stock variant. The request DTO does not accept caller-supplied stock ids.

data.stock[].keepRemnantbooleanNo

Effective remnant decision for this layout: true when the leftover piece met the request's NestingRemnantPolicy thresholds and was kept; false when it was discarded (and the whole bar was billed as consumed).

data.stock[].numberOfPartsPerUnitintegerNo

Total number of parts placed on one bar of this variant. Same for every bar of the variant, since all use the same layout.

data.stock[].numberOfUnitsintegerNo

How many bars of this variant were consumed by the nesting.

data.stock[].totalStockLengthnumberNo

Total raw stock length allocated for this variant — UnitStockLength × NumberOfUnits. "What went in."

data.stock[].totalStockLengthUsednumberNo

Total consumed stock length. When KeepRemnant is true, this is (parts + chuck + one kerf) × NumberOfUnits and the remainder is returned to inventory. When false, this equals TotalStockLength (the whole bar is charged).

data.stock[].totalStockWeightnumberNo

Weight of TotalStockLength at the product's WeightPerLength.

data.stock[].totalStockWeightUsednumberNo

Weight of TotalStockLengthUsed at the product's WeightPerLength.

data.stock[].unitStockLengthnumberNo

Length of one raw bar of this variant.

data.stock[].unitStockLengthUsednumberNo

Consumed length of one bar. Same remnant conditional as TotalStockLengthUsed.

data.stock[].unitStockWeightnumberNo

Weight of one raw bar.

data.stock[].unitStockWeightUsednumberNo

Weight of the consumed portion of one bar.

data.stock[].lengthUnitstringNo

Length unit used for every length field on this layout and in Parts.

data.stock[].weightUnitstringNo

Weight unit used for every weight field on this layout.

data.stock[].parts[]object[]No

Parts placed on one bar of this variant. Quantity is per-bar; multiply by NumberOfUnits for the aggregate count.

data.stock[].parts[].partIduuidNo

The PartId this row corresponds to.

data.stock[].parts[].quantityintegerNo

Count of that part placed on a single bar of the owning stock variant. Multiply by the layout's NumberOfUnits for the aggregate count.

errors[]object[] | nullNo

One or more errors describing why the request failed. Absent (null) on success.

errors[].descriptionstring | nullNo

Human-readable explanation of the error. Intended for display to end users or logs. Wording is not stable and should not be branched on.

errors[].errorIdstring | nullNo

Machine-readable, stable error identifier. Consumers should branch on this value rather than on Description. See ConnectErrorIds for the catalog.

pagingobject | nullNo

Paging metadata for list endpoints. Absent on single-item responses.

paging.limitintegerNo
paging.startintegerNo
paging.totalintegerNo

Example 200 response
{
  "data": {
    "nestingId": "11e99bc8-e511-474a-b049-938734f567db",
    "parts": [
      {
        "partId": "08fcc2e5-7760-493b-b8f1-1ad26fcb0a9e",
        "name": "string",
        "length": 0.1,
        "lengthUnit": "string",
        "quantity": 0,
        "totalItemsNested": 0,
        "totalNestedLength": 0.1,
        "totalNestedWeight": 0.1,
        "totalTrueWeight": 0.1
      }
    ],
    "stock": [
      {
        "stockId": "a43dc3b0-820c-4762-b37b-45e91f17720c",
        "keepRemnant": true,
        "numberOfPartsPerUnit": 0,
        "numberOfUnits": 0,
        "totalStockLength": 0.1,
        "totalStockLengthUsed": 0.1,
        "totalStockWeight": 0.1,
        "totalStockWeightUsed": 0.1,
        "unitStockLength": 0.1,
        "unitStockLengthUsed": 0.1,
        "unitStockWeight": 0.1,
        "unitStockWeightUsed": 0.1,
        "lengthUnit": "string",
        "weightUnit": "string",
        "parts": [
          {
            "partId": "08fcc2e5-7760-493b-b8f1-1ad26fcb0a9e",
            "quantity": 0
          }
        ]
      }
    ]
  },
  "errors": [
    {
      "description": "string",
      "errorId": "string"
    }
  ],
  "paging": {
    "limit": 0,
    "start": 0,
    "total": 0
  }
}