> ## 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.

# Ingest device and point data

> Create devices and points on a KODE API data source, then send current and historical point values.

Send data from your system into KODE OS by registering devices on a KODE API data source and posting point values. KODE OS then treats your data like any other connected building data.

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

## Before you begin

You need:

* An access token. See the [quickstart](https://docs.kodelabs.com/products/kode-api/quickstart.md).
* A `buildingId` from [List buildings](https://docs.kodelabs.com/products/kode-api/api-reference/buildings/list-buildings.md).
* A data source with `apiType` set to `API_KODE` on that building. Ask your KODE project team to create one if it does not exist.

## Send device data

**1. Find your data source**

Call [List building data sources](https://docs.kodelabs.com/products/kode-api/api-reference/data-sources/list-building-data-sources.md) and note the `_id` of the data source whose `apiType` is `API_KODE`.

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

**2. Create devices and points**

Register each device with its points. Use stable identifiers from your system, because sending the same `id` again updates the existing device instead of creating a duplicate.

```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/batch" \
  --header "Authorization: Bearer ${KODE_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "devices": [
      {
        "id": "ahu-01",
        "name": "AHU-01",
        "points": [
          { "pointId": "supply-air-temp", "name": "Supply Air Temp", "kind": "Number", "unit": "°F" },
          { "pointId": "fan-status", "name": "Fan Status", "kind": "Bool" }
        ]
      }
    ]
  }'
```

The response reports how many devices and points were created or updated:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "deviceSize": 1, "pointsSize": 2 }
```

**3. Send current values**

Post values grouped by device. Set `timestamp` to the Unix epoch time of the measurement, or `0` to use the current time.

```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}/timeseries" \
  --header "Authorization: Bearer ${KODE_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "data": [
      {
        "deviceId": "ahu-01",
        "points": [
          { "id": "supply-air-temp", "value": 55.4, "timestamp": 1759840200, "status": "ok" },
          { "id": "fan-status", "value": true, "timestamp": 1759840200, "status": "ok" }
        ]
      }
    ]
  }'
```

**4. Confirm the values arrived**

Call [List latest point values](https://docs.kodelabs.com/products/kode-api/api-reference/timeseries/list-latest-point-values.md) with the KODE OS point identifiers returned by [List building points](https://docs.kodelabs.com/products/kode-api/api-reference/points/list-building-points.md).

## Choose a timeseries endpoint

| Endpoint | Use it when |
| - | - |
| [Send timeseries for a data source](https://docs.kodelabs.com/products/kode-api/api-reference/timeseries/send-timeseries-for-a-data-source.md) | You send values for many devices at once. |
| [Send timeseries for a device](https://docs.kodelabs.com/products/kode-api/api-reference/timeseries/send-timeseries-for-a-device.md) | You send values for one device at a time. |
| [Send historical values for a point](https://docs.kodelabs.com/products/kode-api/api-reference/timeseries/send-historical-values-for-a-point.md) | You backfill history for a single point. |

## Design for reliable ingestion

* Batch values to stay within the [rate limits](https://docs.kodelabs.com/products/kode-api/fundamentals.md#rate-limits). Five requests per second is the burst ceiling.
* Send the measurement time, not the time your service processed the value.
* Use `status` to report `fault`, `down`, or `no_value` instead of skipping a reading.
* Re-run device creation when your system adds points. Existing devices update in place.


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