# Bulk Change

> Fleets API · Devices

```http
POST https://app.mk.io/api/v1/projects/{project_name}/fleet/bulk
```

Change several resources of one kind at once. `kind` says what is changed and `names` lists
the resources; the rest of the body is what a PATCH of one of them would contain.

For `device`, request the same software preload or switch on several devices. Each device is checked against the
same rules as updating a single device, so the result is the same as sending one PATCH per device. Only standalone
devices and HA workers are accepted; HA controllers and arbiters must be updated individually.

Resources that pass are updated together. If any cannot be updated the status is 422, the ones that could be
updated have still been updated, and `failed` lists the others with their errors. To learn more about devices, read [Device Concept](ref:fleet-api#device-concept).

RBAC Capability Required: `fleet.device.create`

## Authentication

- `Authorization` header — Bearer authentication of the form `Bearer <token>`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `project_name` | string | Yes | — |

## Request body

Content type: `application/json`

- `kind` · enum · **Required** — What the request changes. `devices` changes devices.
  - Allowed values: `devices`
- `names` · list of strings · **Required** — The names of the devices to change. Must be non-empty, without duplicates, and no longer than the maximum number of devices per request.
  - Array items (string):
- `spec` · object · **Required** — The software versions to request on every named device.
  - `desiredSoftwareVersion` · string · Optional · _<=255 characters_ — The version of software that each device should switch to. It must already be downloaded on the device.
  - `preloadSoftwareVersion` · string · Optional · _<=255 characters_ — A version of the software that each device should preload.

## Example request

```bash
curl -X POST "https://app.mk.io/api/v1/projects/{project_name}/fleet/bulk" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "devices",
  "names": [
    "beam-001",
    "beam-002"
  ],
  "spec": {
    "desiredSoftwareVersion": "1.0.0.1",
    "preloadSoftwareVersion": "1.0.0.1"
  }
}'
```

## Responses

### 200 — All the devices were updated

- `failed` · list of objects · **Required** — The devices that were not changed, each with its error.
  - Array items (object):
    - `error` · object · **Required** — The error that would be returned by a PATCH of this device.
      - `error` · object · **Required** — Pertinent information about the error
        - `code` · string · **Required** — The error code.
        - `detail` · string · **Required** — The error message.
        - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
          - `[any key]` · any — map of additional properties
      - `ref` · string · **Required** — A reference to the request that caused the error.
      - `status` · integer · **Required** — The HTTP status code
    - `name` · string · **Required** — The name of the device that was not changed.
- `updated` · list of strings · **Required** — The names of the devices that were changed.
  - Array items (string):

Example:

```json
{
  "failed": [
    {
      "error": {
        "error": {
          "code": "string",
          "detail": "string",
          "extraDetail": {
            "key": null
          }
        },
        "ref": "string",
        "status": 0
      },
      "name": "beam-002"
    }
  ],
  "updated": [
    "string"
  ]
}
```

### 400 — Bad Request

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 401 — Unauthorized

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 403 — Forbidden

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 404 — Not Found

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 422 — Some devices could not be updated. The others were updated.

- `failed` · list of objects · **Required** — The devices that were not changed, each with its error.
  - Array items (object):
    - `error` · object · **Required** — The error that would be returned by a PATCH of this device.
      - `error` · object · **Required** — Pertinent information about the error
        - `code` · string · **Required** — The error code.
        - `detail` · string · **Required** — The error message.
        - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
          - `[any key]` · any — map of additional properties
      - `ref` · string · **Required** — A reference to the request that caused the error.
      - `status` · integer · **Required** — The HTTP status code
    - `name` · string · **Required** — The name of the device that was not changed.
- `updated` · list of strings · **Required** — The names of the devices that were changed.
  - Array items (string):

Example:

```json
{
  "failed": [
    {
      "error": {
        "error": {
          "code": "string",
          "detail": "string",
          "extraDetail": {
            "key": null
          }
        },
        "ref": "string",
        "status": 0
      },
      "name": "beam-002"
    }
  ],
  "updated": [
    "string"
  ]
}
```

### 429 — Too Many Requests

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 500 — Internal Server Error

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

---

Source spec: `fleets-api` · operationId: `[post]_/api/v1/projects/{project_name}/fleet/bulk`