> ## 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. # Discover mass write point groups > Finds the writable points that match a query and groups them. Each group has a `groupKey` and the fields a write to it can carry. Nothing is changed. A group holds writable points of the same kind, connector type, field, and unit or enum values. Use the groups to build the `writes` of a plan for [Validate or apply a mass write](https://docs.kodelabs.com/products/kode-api/api-reference/mass-write/validate-or-apply-a-mass-write.md). The body holds a `query`. Only `buildingIds` is required. Every other member is a filter. A point must match every filter you send. A filter you leave out, or send as an empty list, does not restrict the result. > [!WARNING] > > KODE API ignores a key it does not know, so a misspelled filter does not narrow the query. It widens it. Check `points` in the response before you write. > [!NOTE] > > Only writable points are grouped. A query can match at most 30,000 points. A building outside your account returns `400`, the same as a building that does not exist. `scope` is `PORTFOLIO` when matched points are in more than one building. `buildings` and `points` count across all pages. KODE API ignores `q`, `asc`, and `dsc`. Groups come in a fixed order. ## OpenAPI ````yaml /openapi/kode-api.yaml post /api/v1/mass-write/point-groups/query openapi: 3.1.0 info: title: KODE API version: 1.0.0 summary: Programmatic access to KODE OS resources and operations. description: > Use the KODE API to work with buildings, data sources, connectors, devices, points, virtual devices, timeseries data, schedules, the ontology, templating, mass writes, spaces, space assignments, tenants, meters, users, actions, and AssetOps work orders. license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.kodelabs.com/kodeos description: KODE API security: - bearerAuth: [] tags: - name: Authentication description: OAuth 2.0 discovery, token, and revocation endpoints. - name: Buildings description: Buildings and their areas. - name: Data sources description: Data sources connected to a building. - name: Devices description: Devices and their points. - name: Points description: Point queries and point writes. - name: Timeseries description: Current and historical point values. - name: Actions description: Actions exposed by building data sources. - name: Work orders description: AssetOps work orders, lookups, comments, and attachments. - name: Connectors description: KODE API connectors and the devices and points ingested through them. - name: Schedules description: Schedules discovered on building data sources. - name: Templating description: Apply ontology templates to groups of points. - name: Virtual devices description: Virtual devices that group points from other devices. - name: Ontology description: Canonical types, fields, units, and connections of the KODE ontology. - name: Users description: Users of the organization and their app access. - name: Mass write description: Write values to many points across buildings, and follow each run. - name: Spaces description: Levels and space units of a building, and the meters located in them. - name: Space assignments description: Assign tenants to leasable spaces of a building for a period. - name: Tenants description: Tenants of a building, the people or companies that lease its spaces. - name: Meters description: >- Meters of a building, their space assignments, parent and child links, and readings. paths: /api/v1/mass-write/point-groups/query: post: tags: - Mass write summary: Discover mass write point groups description: >- Finds the writable points that match a query and groups them. Each group has a `groupKey` and the fields a write to it can carry. Nothing is changed. operationId: discoverMassWritePointGroups parameters: - name: limit in: query schema: type: integer format: int32 maximum: 200 minimum: 1 default: 50 description: Number of items per page, from `1` to `200`. The default is `50`. - name: page in: query schema: type: integer format: int32 minimum: 1 default: 1 description: Page number to return. The first page is `1`. requestBody: content: application/json: schema: $ref: '#/components/schemas/PointMassWriteGroupsQueryBody' required: true responses: '200': description: A page of point groups. content: application/json: schema: $ref: '#/components/schemas/PointMassWriteGroupsPublic' '400': description: >- The body or a query parameter is not valid. For example, `query` or `query.buildingIds` is missing or empty, an id is blank or longer than 128 characters, `kinds` holds a value other than `Number`, `Bool`, or `Str`, `limit` is above `200`, a building is not one of yours, or the query matches more than 30,000 points. '401': $ref: '#/components/responses/Unauthorized' '403': description: >- The service account lacks permission to read mass writes, or has no assigned building. '429': $ref: '#/components/responses/TooManyRequests' '503': description: KODE could not load the write fields of the groups. Try again later. components: schemas: PointMassWriteGroupsQueryBody: type: object required: - query properties: query: $ref: '#/components/schemas/PointMassWriteQueryPublic' description: Selects the points to group. type: object PointMassWriteGroupsPublic: type: object properties: data: type: array items: $ref: '#/components/schemas/PointMassWriteGroupPublic' page: type: integer format: int32 limit: type: integer format: int32 pageCount: type: integer format: int32 itemCount: type: integer format: int32 scope: description: >- `PORTFOLIO` when the matched points are in more than one building. Otherwise `BUILDING`. type: string buildings: description: Number of buildings with matched points. type: integer format: int32 examples: - 1 points: description: Number of points matched across all pages. type: integer format: int64 examples: - 300 PointMassWriteQueryPublic: type: object required: - buildingIds properties: buildingIds: description: >- Buildings to search. From 1 to 1,000 ids, each up to 128 characters with no spaces. Required. type: array items: type: string pattern: '[^\p{C}\p{Z}]{1,128}' maxLength: 128 maxItems: 1000 minItems: 1 canonicalTypes: description: Keep points on devices of these canonical types. type: array items: type: string maxLength: 255 pattern: (?s)(?=.*[^\p{C}\p{Z}])[\P{Cc}\n\r\t]* examples: - - VAV maxItems: 100 kinds: description: >- Keep points of these kinds. Use `Number`, `Bool`, or `Str`. The values are case-sensitive. type: array items: type: string pattern: Number|Bool|Str examples: - - Number maxItems: 3 fields: description: Keep points that have one of these ontology fields. type: array items: type: string maxLength: 255 pattern: (?s)(?=.*[^\p{C}\p{Z}])[\P{Cc}\n\r\t]* examples: - - Space Temp Setpoint maxItems: 500 connectorTypes: description: Keep points from these connector types, for example `API_JACE`. type: array items: type: string maxLength: 255 pattern: (?s)(?=.*[^\p{C}\p{Z}])[\P{Cc}\n\r\t]* examples: - - API_JACE maxItems: 100 areaIds: description: Keep points in these areas. type: array items: type: string pattern: '[^\p{C}\p{Z}]{1,128}' maxLength: 128 maxItems: 1000 deviceIds: description: Keep points on these devices. type: array items: type: string pattern: '[^\p{C}\p{Z}]{1,128}' maxLength: 128 maxItems: 2000 nameContains: description: >- Keep points whose name contains this text. The match is not case-sensitive. type: string examples: - Zone pattern: (?s)(?=.*[^\p{C}\p{Z}])[\P{Cc}\n\r\t]* maxLength: 255 excludePointIds: description: Leave out these points. type: array items: type: string pattern: '[^\p{C}\p{Z}]{1,128}' maxLength: 128 maxItems: 5000 PointMassWriteGroupPublic: type: object properties: groupKey: description: >- Key of the group. Use it in `writes[].groupKeys`. The key is stable for the same points. type: string examples: - mw1.Yz3kR1a2B3c4D5e6F7g8H9 kind: description: 'Kind of the points in the group: `Number`, `Bool`, or `Str`.' type: string examples: - Number connectorType: description: Connector type of the points, for example `API_JACE`. type: string examples: - API_JACE field: description: Ontology field of the points, when they have one. type: string examples: - Space Temp Setpoint templated: description: Whether the points in the group are templated. type: boolean unit: $ref: '#/components/schemas/PointMassWriteUnitPublic' description: Unit of the points. Set for `Number` groups. type: object pointEnum: description: Values of the points. Set for `Bool` and `Str` groups. type: array items: type: string examples: - - 'False' - 'True' points: description: Number of points in the group. type: integer format: int32 examples: - 16 fields: description: Fields a write to this group can carry. type: array items: $ref: '#/components/schemas/PointMassWriteFieldPublic' PointMassWriteUnitPublic: type: object properties: id: type: string examples: - fahrenheit symbol: type: string examples: - °F PointMassWriteFieldPublic: type: object properties: id: description: Action id. Use it as `actions[].id`. type: string examples: - priority name: description: Display name of the field. type: string examples: - Priority dataType: $ref: '#/components/schemas/MassWriteFieldType' description: >- Type of the value: `NUMBER`, `DURATION_MS` (milliseconds), or `STRING`. type: string examples: - STRING inputType: $ref: '#/components/schemas/MassWriteFieldInput' description: >- `SELECT` means the value must be one of `options`. `TEXT` means any text. type: string required: description: Whether a write to the group must carry this field. type: boolean requiredWhen: $ref: '#/components/schemas/RequiredWhen' description: Conditions under which the field becomes required. type: object options: description: Allowed values when `inputType` is `SELECT`. type: array items: $ref: '#/components/schemas/Option' unit: description: Unit symbol of the value. type: string examples: - °F MassWriteFieldType: type: string enum: - NUMBER - DURATION_MS - STRING MassWriteFieldInput: type: string enum: - SELECT - TEXT RequiredWhen: type: object properties: match: $ref: '#/components/schemas/Match' description: 'ALL: every condition holds; ANY: at least one does.' type: string examples: - ALL conditions: type: array items: $ref: '#/components/schemas/Condition' Option: type: object properties: id: type: string description: Value to send. examples: - override name: type: string description: Display name. examples: - Override Match: type: string enum: - ALL - ANY Condition: type: object properties: fieldId: type: string description: Id of the action the condition reads. examples: - priority operator: $ref: '#/components/schemas/Operator1' description: >- IN: the action's value is one of values; EQUAL / NOT_EQUAL: compared with the first value; EXISTS: the action is given. ANY ignores NOT_EQUAL conditions. type: string examples: - IN values: type: array items: type: string examples: - - override - set Operator1: type: string enum: - IN - EQUAL - NOT_EQUAL - EXISTS responses: Unauthorized: description: The access token is missing, invalid, or expired. Request a new token. TooManyRequests: description: >- A rate-limit window is exhausted. Wait, then retry with increasing delays. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Paste an access token from [Create an access token](/products/kode-api/api-reference/authentication/create-an-access-token). Tokens expire, so request a new one if you receive `401`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.