Apply a templating plan

curl --request POST \
  --url https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating:apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "canonicalType": "AHU",
  "deviceIds": [
    "<string>"
  ],
  "requestId": "ahu-1-apply-2026-09-30"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    canonicalType: 'AHU',
    deviceIds: ['<string>'],
    requestId: 'ahu-1-apply-2026-09-30'
  })
};

fetch('https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating:apply', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating:apply"

payload = {
    "canonicalType": "AHU",
    "deviceIds": ["<string>"],
    "requestId": "ahu-1-apply-2026-09-30"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

$headers=@{}
$headers.Add("Authorization", "Bearer <token>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating:apply' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "canonicalType": "AHU",
  "deviceIds": [
    "<string>"
  ],
  "requestId": "ahu-1-apply-2026-09-30"
}'

{
  "validationReport": {
    "valid": false,
    "etag": "sha256:9f86d081...",
    "summary": {
      "mappings": 42,
      "matchedGroups": 41,
      "matchedPoints": 8120,
      "devicesAffected": 212,
      "errors": 1,
      "warnings": 2
    },
    "mappings": [
      {
        "index": 0,
        "groupKey": "pg1.Yz3kR1a2B3c4D5e6F7g8H9",
        "field": "dischargeAirTemp",
        "matchedPoints": 212,
        "status": "OK",
        "issues": [
          {
            "code": "FIELD_KIND_MISMATCH",
            "pointer": "/mappings/7/field",
            "message": "Field 'supplyFanRunCmd' requires a Bool/Str point; group kind is Number.",
            "details": {}
          }
        ]
      }
    ],
    "issues": [
      {
        "code": "FIELD_KIND_MISMATCH",
        "pointer": "/mappings/7/field",
        "message": "Field 'supplyFanRunCmd' requires a Bool/Str point; group kind is Number.",
        "details": {}
      }
    ],
    "unmappedGroups": [
      {
        "groupKey": "pg1.Qa91mN2o3P4q5R6s7T8u9V0",
        "name": "ZN-T",
        "pointsCount": 48
      }
    ]
  },
  "operation": {
    "name": "buildings/66f1a2b3c4d5e6f7a8b9c0d1/templating/operations/66f1a2b3c4d5e6f7a8b9c0d3",
    "done": false,
    "metadata": {
      "operation": "APPLY",
      "canonicalType": "AHU",
      "state": "RUNNING",
      "progress": 62.5,
      "createdAt": "2026-10-28T13:51:31+0000",
      "updatedAt": "2026-10-28T13:51:31+0000",
      "actorId": "66f1a2b3c4d5e6f7a8b9c0d4",
      "etag": "sha256:9f86d081...",
      "requestId": "5f8a1b2c-3d4e-4f5a-8b6c-7d8e9f0a1b2c"
    },
    "response": {
      "matchedPoints": 8120,
      "devicesAffected": 212,
      "notes": [
        "<string>"
      ]
    },
    "error": {
      "code": "13",
      "message": "<string>"
    }
  }
}

POST

https://api.kodelabs.com/kodeos

api

buildings

{buildingId}

templating:apply

Apply a templating plan

curl --request POST \
  --url https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating:apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "canonicalType": "AHU",
  "deviceIds": [
    "<string>"
  ],
  "requestId": "ahu-1-apply-2026-09-30"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    canonicalType: 'AHU',
    deviceIds: ['<string>'],
    requestId: 'ahu-1-apply-2026-09-30'
  })
};

fetch('https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating:apply', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating:apply"

payload = {
    "canonicalType": "AHU",
    "deviceIds": ["<string>"],
    "requestId": "ahu-1-apply-2026-09-30"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

$headers=@{}
$headers.Add("Authorization", "Bearer <token>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating:apply' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "canonicalType": "AHU",
  "deviceIds": [
    "<string>"
  ],
  "requestId": "ahu-1-apply-2026-09-30"
}'

{
  "validationReport": {
    "valid": false,
    "etag": "sha256:9f86d081...",
    "summary": {
      "mappings": 42,
      "matchedGroups": 41,
      "matchedPoints": 8120,
      "devicesAffected": 212,
      "errors": 1,
      "warnings": 2
    },
    "mappings": [
      {
        "index": 0,
        "groupKey": "pg1.Yz3kR1a2B3c4D5e6F7g8H9",
        "field": "dischargeAirTemp",
        "matchedPoints": 212,
        "status": "OK",
        "issues": [
          {
            "code": "FIELD_KIND_MISMATCH",
            "pointer": "/mappings/7/field",
            "message": "Field 'supplyFanRunCmd' requires a Bool/Str point; group kind is Number.",
            "details": {}
          }
        ]
      }
    ],
    "issues": [
      {
        "code": "FIELD_KIND_MISMATCH",
        "pointer": "/mappings/7/field",
        "message": "Field 'supplyFanRunCmd' requires a Bool/Str point; group kind is Number.",
        "details": {}
      }
    ],
    "unmappedGroups": [
      {
        "groupKey": "pg1.Qa91mN2o3P4q5R6s7T8u9V0",
        "name": "ZN-T",
        "pointsCount": 48
      }
    ]
  },
  "operation": {
    "name": "buildings/66f1a2b3c4d5e6f7a8b9c0d1/templating/operations/66f1a2b3c4d5e6f7a8b9c0d3",
    "done": false,
    "metadata": {
      "operation": "APPLY",
      "canonicalType": "AHU",
      "state": "RUNNING",
      "progress": 62.5,
      "createdAt": "2026-10-28T13:51:31+0000",
      "updatedAt": "2026-10-28T13:51:31+0000",
      "actorId": "66f1a2b3c4d5e6f7a8b9c0d4",
      "etag": "sha256:9f86d081...",
      "requestId": "5f8a1b2c-3d4e-4f5a-8b6c-7d8e9f0a1b2c"
    },
    "response": {
      "matchedPoints": 8120,
      "devicesAffected": 212,
      "notes": [
        "<string>"
      ]
    },
    "error": {
      "code": "13",
      "message": "<string>"
    }
  }
}

Applying a plan rewrites live data on every matched point: its name, display name, unit, ontology fields, and enum maps. It also sets the canonical type on the devices. There is no undo call. Clear a templating plan removes the ontology fields and restores the connector name and unit, but it does not restore other values. Always validate first, check summary.matchedPoints, and test on a non-critical device.

A plan has a canonicalType, the deviceIds it covers (1 to 2,000), and up to 1,000 mappings. Each mapping has:

match: The points to change. Send exactly one of groupKey, a tuple (name, kind, unitSymbol, writable, pointEnum), or pointIds.
field: The catalog field to apply, from List fields for a canonical type.
overrides: Optional changes to the field’s defaults, such as displayName, unit, precision, covTolerance, defaultInGraph, prefix, suffix, and dataInterval.
enumMapping: Optional enum maps for Bool and Str points. action is SET to replace the maps, UNSET to remove them, or KEEP to leave them as they are. KEEP is the default.

A point-level mapping (pointIds) takes precedence over a group mapping that covers the same point. A plan can cover at most 5,000 distinct point ids. Validate first With validateOnly set to true, the response holds validationReport and nothing is written. Read:

valid: true when no issue has ERROR severity.
summary: How many points and devices the apply would reach, with counts of errors and warnings.
mappings[]: The outcome of each mapping, in request order, with its own issues.
issues: Findings about the whole plan, such as devices that are already templated under another canonical type.
unmappedGroups: Groups in your device selection that no mapping covers.
etag: A fingerprint of the resolved plan.

Each issue has a code, a pointer to the part of your request it concerns, and a message. ERROR issues stop the apply. Warnings, such as NO_MATCH or ENUM_MAPPING_RECOMMENDED, do not. Start the run Send the same body with validateOnly removed (or false), a requestId of your choice, and the etag from the report. The response holds operation. Keep the last segment of operation.name as the operationId and poll Get a templating operation.

Only validateOnly: true makes a dry run. If you leave validateOnly out, the call starts a real run.
The requestId is unique per building. Sending the same requestId with the same body again returns the operation it already started. Sending it with a different body returns 400.
If the plan changed since you validated it, the etag no longer matches and the call returns 400. Validate again to get a new etag. Leave etag out to skip the check.
The API does not stop two runs from touching the same points. The last write wins.

Your service account needs the permission to manage device and point templating, including for a dry run.

Authorizations

Authorization

string

header

required

Paste an access token from Create an access token. Tokens expire, so request a new one if you receive 401.

Path Parameters

buildingId

string

required

Building identifier from List buildings.

Body

application/json

canonicalType

string

required

Canonical type this plan is scoped to.

Maximum string length: 255

Pattern: (?s)(?=.*[^\p{C}\p{Z}])[\P{Cc}\n\r\t]*

Example:

"AHU"

deviceIds

string[]

required

Explicit device ids to scope this plan to.

Required array length: 1 - 2000 elements

Maximum string length: 255

Pattern: [^\p{C}\p{Z}]{1,128}

requestId

string

required

Client-chosen idempotency key, unique per building. Repeating it with the same plan returns the existing operation; with a different plan it is rejected.

Maximum string length: 128

Pattern: [^\p{C}\p{Z}]{1,128}

Example:

"ahu-1-apply-2026-09-30"

mappings

object[]

The plan's mappings. Empty or omitted on :clear clears the whole device selection for this canonical type.

Maximum array length: 1000

Show child attributes

etag

string

Etag from a previous validation. If it no longer matches, the request fails with 400; validate again for a fresh etag. Omitted means no check.

Maximum string length: 128

Pattern: [^\p{C}\p{Z}]{1,128}

Example:

"sha256:9f86d0818..."

validateOnly

boolean

Dry run: true returns the validation report and writes nothing.

Example:

false

Response

The started operation in operation, or the validation report in validationReport when validateOnly is true. Exactly one of the two is present.

validationReport

object

Present only for validateOnly: true. The plan's validation report; nothing was written.

Show child attributes

operation

object

Present only when validateOnly is false. The started operation, or the existing one when the requestId is replayed with the same plan.

Show child attributes

Get started

Guides

API reference

Authorizations

Path Parameters

Body

Response