# Act on every board record a filter matches

Export, move, copy, update, archive or delete EVERY record on a custom board that matches a filter — or the records named in `ids` instead of a filter — in one call — the grid's own filter, so what the grid lists for it is exactly what is acted on. Reach for it on any 'everyone with…' or 'all the … that…' ask instead of reading rows and acting one at a time. Body: {filter: {q, filters, groupId, sort, dir}, action, target?, cells?, dryRun?}. `filters` maps a column — its id (get_boards_id answers them) or its label — to the values to keep: Status column `c1` holding hot → `{"filters": {"c1": ["hot"]}}`; a select takes its value or its label, '' is a blank cell, several values are OR and several columns AND; a computed column (formula, lookup, a record's `documents`: missing, requested or complete) filters like a stored one — `{"filters": {"Documents": ["missing"]}}` is every record still owed a paper; `q` searches every cell; no filter is the whole board. `export` writes a CSV of the matches in the words the grid draws (names, labels — never ids) and answers `file: {id, name, url}`: give the person that link. `move` and `copy` take `target: {boardId}` or `{key}` (a page key such as leads) and carry each cell into the target's column of the same name and kind; a move takes a record whole or leaves it where it is, and between two boards keeps its id and history. `update` takes `cells: {column name or id: value}` and sets it on every match. `archive` retires them; `delete` is permanent. Send `dryRun: true` FIRST for move, update, archive and delete: it writes nothing and answers how many match, the first names in `preview` and a move's column `plan` — tell the person, then make the real call. Answers {action, matched, affected, skipped: [{rowId or column, reason}], preview?, plan?, file?}: `affected` is how many changed and every skipped record says why. Above 5000 matches it is refused — narrow the filter. Read on the board exports; every other action needs write on it and on the target. The pack-page twin is `post_definitions_key_rows_act`.

Access class: `board:read`.

## Endpoint

`POST /v1/boards/{id}/rows/act`

## Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| id | path | string | Yes |

## Request body

Content type: `application/json`.

```json
{
  "action": "string",
  "assignee": "string",
  "cells": {},
  "dryRun": true,
  "filter": {
    "dir": "string",
    "filters": {},
    "groupId": "",
    "q": "string",
    "sort": "string"
  },
  "ids": [
    "string"
  ],
  "note": "string",
  "role": "string",
  "status": "string",
  "target": {
    "boardId": "",
    "key": "string"
  }
}
```

## Responses

### 201

the action's answer

Content type: `application/json`.

```json
{
  "data": {
    "action": "string",
    "affected": 1.5,
    "dryRun": true,
    "file": {
      "id": "",
      "name": "string",
      "url": "string"
    },
    "matched": 1.5,
    "plan": {
      "mappings": [
        "string"
      ],
      "unmapped": [
        "string"
      ],
      "warnings": [
        "string"
      ]
    },
    "preview": [
      "string"
    ],
    "skipped": [
      "string"
    ]
  }
}
```

### default

a refusal: `{"error": "<what a person needs to read>"}`. 401 no credential, 402 the plan does not include this, 403 the seat does not, 404 the thing does not exist or is not yours to see.

Content type: `application/json`.

```json
{
  "error": "string"
}
```
