Skip to content
Stella ConnectDocs
Parts

Nest linear parts by PartId onto stock bars

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

Same 1D bin-packing solve as the standard linear-nesting endpoint, but each part is identified by PartId (a previously imported part) instead of by an explicit length. Each part is classified inline and uses the resulting cut length. Applies saw allowances (chuck, kerf) and a per-stock remnant policy.

Parts[].PartId in the response echoes the caller-supplied part ids (unlike the standard nesting endpoint where ids are server-generated).

Authx-api-key

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

Cut requirements identified by PartId + quantity. Each id must resolve to an imported part; the part is classified inline (no prior call to the classification endpoint is required). Parts that cannot be classified as linear cause the whole request to fail.

parts[].partIduuidNo

Identifier of an imported part to include in the nesting. Classification is performed inline — the part need not have been classified beforehand, but it must be classifiable as linear.

parts[].quantityintegerNo

How many copies of this part 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.

outputTimeUnitstringYes

Reserved. Currently ignored — the response always uses "Minute".

outputWeightUnitstringYes

Reserved. Currently ignored — the response always uses "Pound".

Status
When
200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

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
  }
}