> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nestapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 1D nesting

> Optimise linear cutting of bar, tube, and profile stock.

1D (linear) nesting solves the **cutting-stock problem** for one-dimensional material: given
a set of required lengths and the stock lengths you have, work out how to cut them with the
least waste. Use it for bar, tube, extrusion, and profile.

Like every other nesting endpoint, 1D is **asynchronous**: you submit the request, get a
`RequestId` back immediately, and collect the cutting plan once the nest has run on a nester.
See the [nesting workflow](/guides/nesting-workflow) for the shared submit → poll → result
model, webhooks, SignalR, and delayed start.

## 1. Submit the request

`POST /v1/nesting/1D` accepts a **`Nesting1DRequest`** (wrapped as `Request`) and returns a
`RequestId`. The job is queued and runs on a nester — it is **not** computed inline in the
response. (Also served unversioned at `/nesting/1D` for existing callers.)

```bash theme={null}
curl https://api.nestapi.com/v1/nesting/1D \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Request": {
      "SourceLength": 6000,
      "SourceWidth": 0,
      "CutGap": 3,
      "SourceQuantity": 10,
      "ComputationTime": 10,
      "Lengths": [
        { "Quantity": 5, "Length": 1200 },
        { "Quantity": 2, "Length": 850 }
      ]
    },
    "ResultsWebhookUri": "https://your-app.example.com/hooks/nestapi",
    "AutomaticallyStartNesting": true
  }'
```

| Field                       | Meaning                                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `SourceLength`              | Length of one piece of stock.                                                                                     |
| `SourceWidth`               | Width of the stock. Use `0` for plain linear stock.                                                               |
| `CutGap`                    | Kerf allowed between adjacent placements.                                                                         |
| `SourceQuantity`            | How many pieces of stock are available.                                                                           |
| `ComputationTime`           | Seconds the optimiser may run. Capped by your plan.                                                               |
| `Lengths`                   | The required cuts, each `{ "Quantity": int, "Length": number }`.                                                  |
| `ResultsWebhookUri`         | Optional. Where the result is `POST`ed on completion, so you don't have to poll.                                  |
| `AutomaticallyStartNesting` | `true` (default) starts immediately; `false` waits for a delayed start (connect SignalR first for live progress). |

## 2. Wait for completion

Poll job status with the `RequestId` until it reports `Completed` — or supply a
`ResultsWebhookUri` above to be called instead:

```bash theme={null}
curl "https://api.nestapi.com/v1/nesting/status?RequestId=THE_REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The status values (`Queued`, `Running`, `Completed`, `Failed`) are shared with the 2D flow —
see [job status](/guides/nesting-workflow#job-status).

## 3. Fetch the cutting plan

Once status is `Completed`, `POST /v1/nesting/1D/result` with the `RequestId` to get a
**`Nesting1DApiResponse`**. `Status` reports how the nest itself went — `Success`, `Warning`,
or `Failure` — and `Result` carries the cutting plan. Each nest is one piece of stock:
`Multiplicity` is how many identical pieces are cut that way, and `PlacedX` is where a
placement starts along the bar.

```bash theme={null}
curl https://api.nestapi.com/v1/nesting/1D/result \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "RequestId": "THE_REQUEST_ID" }'
```

```json theme={null}
{
  "status": "Success",
  "result": {
    "numberOfUniqueNests": 2,
    "nests": [
      {
        "multiplicity": 3,
        "placedLengths": [
          { "quantity": 1, "length": 1200, "placedX": 0 },
          { "quantity": 1, "length": 1200, "placedX": 1203 }
        ]
      }
    ]
  }
}
```

If the optimiser ran but could not produce a plan, `Status` is `Failure` with the reason in
`StatusReport`. If you fetch **before** the nest has finished, you get `404` with a message to
keep polling `/nesting/status`.

## Errors

A rejected **submit** returns the standard `ResponseStatus` error object with the reason in
`Message`, and no `RequestId` — the request never entered the queue.

```json theme={null}
{
  "responseStatus": {
    "errorCode": "BadRequest",
    "message": "Nesting request is incomplete. Missing required section(s): Lengths.",
    "errors": []
  }
}
```

| Status | Meaning                                                                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Submit accepted (`RequestId` returned), or result fetched.                                                                                           |
| `400`  | Invalid request — check required fields.                                                                                                             |
| `401`  | API key missing or invalid.                                                                                                                          |
| `404`  | Result fetched before the nest completed — keep polling `/nesting/status`.                                                                           |
| `500`  | Rejected by account or plan policy — no allowance, lapsed subscription, or a limit such as `ComputationTime` exceeded. See `ResponseStatus.Message`. |

<Tip>
  See the **Nesting** section of the [API Reference](/api-reference) for the full
  `Nesting1DRequest` and `Nesting1DApiResponse` shapes.
</Tip>

## When to use it

* Cutting **linear** material (bar, tube, profile) rather than sheet.
* Minimising **offcut waste** across a batch of required lengths.