Skip to main content
POST
Validate or apply a mass write
A real apply writes to live points through their connectors. There is no undo call. To release an override, send priority with the release option from the group fields, for example auto. Always validate first, check summary.points, and start with a small query.
A plan has a query and a list of writes. The query is the one you used in Discover mass write point groups. Each write lists groupKeys and actions. An action has an id, a field of the group, and a value. Every discovered group must be in exactly one write. Every action id must be a field of its groups. A value must fit the field dataType, and a SELECT field accepts only its options. Validate first With validateOnly set to true, the response holds validationReport and nothing is written. Read:
  • valid: true when the plan has no issue.
  • summary: How many points, groups, and writes the plan reaches, with counts of errors and warnings.
  • writes[]: The outcome of each write, in request order, with its own issues.
  • issues: Issues with the plan as a whole.
  • unmatchedGroups: Groups that no write covers.
  • etag: A fingerprint of the plan. It is present only when the plan is valid.
Each issue has a code, a pointer to the part of your request, and a message. The codes are NO_MATCHING_POINTS, UNKNOWN_GROUP, DUPLICATE_WRITE, WRITES_INCOMPLETE, and INVALID_ACTION. A validation lists every issue. A real apply stops with 400 on the first kind of issue. Start the write Send the same body without validateOnly, with 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, then poll Get a mass write operation.
  • The response is 200, not 202.
  • Sending the same requestId with the same body within 24 hours 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.
  • A building can have only one mass write running. A second apply returns 400 with “Another point mass write is running” until the first operation is finished. An operation finishes when you read it and every point has an outcome.
Your service account needs the permission to manage mass writes, including for a validation. Its role can also limit overrides. An override longer than the maximum duration returns 403. An override longer than the reason threshold without a reason returns 400. Names and reasons can have up to 255 characters, and notes up to 2,000.

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.

Body

application/json
​
query
object
required

Selects the points to write. Use the same query you used to discover the groups.

​
validateOnly
boolean

Set to true to validate the plan and write nothing. The default is false, which starts the write.

Example:

false

​
requestId
string

Your id for this write, up to 128 characters. Sending it again with the same body within 24 hours returns the operation it started.

Maximum string length: 128
Pattern: [^\p{C}\p{Z}]{1,128}
Example:

"2b7e9c1a-aaa-2026-10-14"

​
etag
string

The etag from a validation report. The call fails with 400 if the plan has changed since.

Maximum string length: 128
Pattern: [^\p{C}\p{Z}]{1,128}
Example:

"sha256:9f86d0818..."

​
name
string

Name of the operation, up to 255 characters.

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

"AAA"

​
reason
string

Why you are writing, up to 255 characters. A role can require a reason for longer overrides.

Maximum string length: 255
Pattern: (?s)(?=.*[^\p{C}\p{Z}])[\P{Cc}\n\r\t]*
​
notes
string

Free text, up to 2,000 characters.

Maximum string length: 2000
Pattern: (?s)(?=.*[^\p{C}\p{Z}])[\P{Cc}\n\r\t]*
​
writes
object[]

Each write sets actions on one or more groups. Every discovered group must be in exactly one write.

Maximum array length: 10000

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 when validateOnly is true.

​
operation
object

Present when the write started.