# Add defects by time (https://docs.pulsarml.com/v1/api-reference/shifts/post-shifts-defects)

Add defective units of a SKU to the shift that machine `machineId` was running at `time`, including
shifts that have already ended. Use it when you know the machine and roughly when the defects were
found, but not the shift id.

**How defects add up.** Unlike operators, defects have no timeline and no order. Each call adds a
new defects production log of `quantity` units of the SKU, covering the whole shift, and the
shift's Quality and OEE count it in the background. Calls never replace earlier ones:

* Sending `quantity: 2` and then `quantity: 3` records 5 defects.
* Sending the same request twice records the defects twice, so retry only requests that failed.
* To undo a call, delete the log it returned with `DELETE /v1/production-logs/{id}`. To see what a
  shift already has, list its logs with `POST /v1/production-logs/filters`.

Defects are not attributed to any operator, and they can be added to past shifts, including ones
whose production was reviewed. The SKU is given by `id` or by `name`; an unknown name creates a new
SKU, so check the spelling.

Errors:

* `400`: no shift matches, the shift has not started yet, or the shift does not have enough
  production of that SKU to hold the defects.
* `404`: `sku.id` is not one of your SKUs.

## `POST /v1/shifts/defects`

Base URLs:
- `https://draco.prod.pulsarml.com` — Production
- `https://draco.dev.pulsarml.com` — Development (sandbox)

Authentication: send your API key in the `x-api-key` header.

### Request body (`application/json`, required)

Type: object (`AddDefectsToMachineShiftRequestV1`)

- `sku` (object, required) — The SKU the defective units are of.
  - `id` (string, optional, nullable, min length 1, e.g. `"9ce2c6b4-a1f4-4bf2-b5c8-10436d1018cc"`) — The SKU's `id`, as returned by `/v1/skus`. An id that is not one of your SKUs is rejected.
  - `name` (string, optional, nullable, min length 1, e.g. `"SKU-1042"`) — The SKU's name, matched exactly. A name that matches none of your SKUs creates a new SKU with that name, as production logs do.
- `quantity` (integer, optional, default `1`, >= 1, e.g. `3`) — How many defective units to add. Defaults to 1.
- `machineId` (integer, required, e.g. `12`) — The id of the machine, as returned by `GET /v1/machines`.
- `time` (string (date-time), required, e.g. `"2026-10-12T10:00:00Z"`) — Any moment inside the shift, for example when the defects were found. It selects the machine's shift running at that moment; the defects are not tied to this time. A time without a UTC offset is read as UTC.

### Responses

#### 200 — The defects production log that was created

Type: object (`ShiftDefectsDtoV1`)

- `id` (string, required, e.g. `"5b0f6a52-3c1e-4d5b-9f0e-8a7c6d5e4f3a"`) — The id of the defects production log that was created. Pass it to `DELETE /v1/production-logs/{id}` to undo the call.
- `shiftId` (integer, required, e.g. `48213`) — The shift the defects were added to.
- `machineId` (integer, required, e.g. `12`) — The machine the shift belongs to.
- `quantity` (integer, required, e.g. `3`) — How many defective units were added.
- `start` (string (date-time), required, e.g. `"2026-10-12T06:00:00Z"`) — The start of the shift. Defects always cover the whole shift.
- `end` (string (date-time), required, e.g. `"2026-10-12T14:00:00Z"`) — The end of the shift.

#### 422 — Validation Error

Type: object (`HTTPValidationError`)

- `detail` (array of object, optional)
  - `loc` (array of string | integer, required)
  - `msg` (string, required)
  - `type` (string, required)
  - `input` (any, optional)
  - `ctx` (object, optional)

### Example request

```bash
curl -X POST 'https://draco.prod.pulsarml.com/v1/shifts/defects' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sku": {
      "id": "9ce2c6b4-a1f4-4bf2-b5c8-10436d1018cc",
      "name": "SKU-1042"
    },
    "quantity": 3,
    "machineId": 12,
    "time": "2026-10-12T10:00:00Z"
  }'
```