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

# Write to points

> Discover the fields a point accepts, then send single, batch, or mass point writes through the KODE API.

Point writes change values on building equipment, such as setpoints and overrides. Each point defines the fields it accepts, so you read those fields first and then build the write request from them.

Each linked endpoint can switch the sample between cURL, JavaScript, Python, and PowerShell, or send the request for you.

> [!WARNING]
>
> Point writes can command live equipment. Test with a non-critical point, and confirm that your service account has write permission only where it needs it.

## Before you begin

You need:

* An access token. See the [quickstart](https://docs.kodelabs.com/products/kode-api/quickstart.md).
* The `buildingId`, `datasourceId`, `deviceId`, and `pointId` of a writable point. Points with `writable` set to `true` in [List building points](https://docs.kodelabs.com/products/kode-api/api-reference/points/list-building-points.md) accept writes.

## Write to a point

**1. Get the write fields**

Call [List point write fields](https://docs.kodelabs.com/products/kode-api/api-reference/points/list-point-write-fields.md). Each item in the response is a field you can send.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.kodelabs.com/kodeos/api/v1/buildings/${BUILDING_ID}/integrations/datasources/${DATASOURCE_ID}/devices/${DEVICE_ID}/points/${POINT_ID}/fields" \
  --header "Authorization: Bearer ${KODE_ACCESS_TOKEN}"
```

For each field, read:

* `identifier`: The value to send as `id`.
* `options`: The allowed values. Send the option `_id`.
* `metadata.required`: `MANDATORY`, `OPTIONAL`, or `CONDITIONAL`.
* `metadata.filter`: For conditional fields, the values of other fields that make this field apply.

**2. Build the actions array**

Add one entry per field. For example, a typical override needs `priority`, `duration`, and `value`. The `value` and `duration` fields apply only when `priority` is `override`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "actions": [
    { "id": "priority", "value": "override" },
    { "id": "duration", "value": "3600000" },
    { "id": "value", "value": 72 }
  ],
  "notes": "Raised setpoint for after-hours event"
}
```

Duration options are in milliseconds. `-1` means permanent.

**3. Send the write**

Post the body to [Write to a point](https://docs.kodelabs.com/products/kode-api/api-reference/points/write-to-a-point.md):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.kodelabs.com/kodeos/api/v1/buildings/${BUILDING_ID}/integrations/datasources/${DATASOURCE_ID}/devices/${DEVICE_ID}/points/${POINT_ID}/write" \
  --header "Authorization: Bearer ${KODE_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data @write.json
```

The response returns the point priority array, so you can confirm the new value at the level you wrote.

**4. Release the override**

When the override is no longer needed, send a write with `priority` set to `release`. The equipment then returns to its normal control logic.

## Write to many points

To change several points on the same data source, use [Write to points in a batch](https://docs.kodelabs.com/products/kode-api/api-reference/points/write-to-points-in-a-batch.md). Each item contains the point `id` and its own `actions` array.

The response reports `successCount` and `failureCount`. Check `failureCount` before you treat the batch as complete, and do not retry the whole batch blindly.

### Write across devices and buildings

To write to points on many devices, or in many buildings, use the mass write operations. You describe the points with a query and check the plan before you write.

**1. Discover the groups**

Send a `query` with `buildingIds` and any filters to [Discover mass write point groups](https://docs.kodelabs.com/products/kode-api/api-reference/mass-write/discover-mass-write-point-groups.md). Each group has a `groupKey` and the fields a write to it can carry.

**2. Validate the plan**

Build `writes` so that every group is in exactly one write. Send the plan to [Validate or apply a mass write](https://docs.kodelabs.com/products/kode-api/api-reference/mass-write/validate-or-apply-a-mass-write.md) with `validateOnly` set to `true`. Fix the issues in the report, then note the `etag`.

**3. Start the write**

Send the same plan without `validateOnly`, with a `requestId` and the `etag`. Keep the last segment of `operation.name` as the `operationId`.

**4. Follow the operation**

Poll [Get a mass write operation](https://docs.kodelabs.com/products/kode-api/api-reference/mass-write/get-a-mass-write-operation.md) every `metadata.pollAfterSeconds` until `done` is `true`. Reading the operation is what finishes it. Then call [List mass write results](https://docs.kodelabs.com/products/kode-api/api-reference/mass-write/list-mass-write-results.md) for the outcome of each point. To send failed points again, call [Retry a mass write operation](https://docs.kodelabs.com/products/kode-api/api-reference/mass-write/retry-a-mass-write-operation.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.