Automate boards

Boards group files with custom properties — statuses, people, dates, tags — independent of where the files live in your libraries. Scopes needed: boards:write to create the board, add files and set values, and boards:read to query it back. Adding a file to a board additionally requires the key creator's own edit role on that file's library or folder — see the note on file access below.

1. Create a board with a status property

default_property_type: "status" seeds one status property with the three default options To Do, In Progress, Done — so you don't need a second call just to get started.

curl -X POST https://us.api.brault.app/v1/boards \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-5555-4c1a-9c1e-board-create" \
  -d '{"name": "Client Reviews", "default_property_type": "status"}'

{
  "object": "board",
  "id": "<board_id>",
  "name": "Client Reviews",
  "color": "#E2E8EE",
  "emoji": null,
  "logo_url": null,
  "pinned": false,
  "my_access": "manage",
  "created_at": "2026-09-06T10:00:00.000Z",
  "updated_at": "2026-09-06T10:00:00.000Z",
  "created_by_id": "<user_id>",
  "properties": [
    {
      "object": "property",
      "id": "<status_property_id>",
      "scope": "board",
      "board_id": "<board_id>",
      "name": "Status",
      "type": "status",
      "selection_mode": null,
      "options": [
        { "object": "option", "id": "<todo_option_id>", "label": "To Do", "color": "#E2E8EE", "hidden": false, "position": 0 },
        { "object": "option", "id": "<in_progress_option_id>", "label": "In Progress", "color": "#FFF1C7", "hidden": false, "position": 1 },
        { "object": "option", "id": "<done_option_id>", "label": "Done", "color": "#CCF3D0", "hidden": false, "position": 2 }
      ],
      "position": 0,
      "created_at": "2026-09-06T10:00:00.000Z",
      "updated_at": "2026-09-06T10:00:00.000Z"
    }
  ]
}

Keep properties[0].id (<status_property_id> above) and the option ids — you'll need them next.

2. Add files to the board

curl -X POST https://us.api.brault.app/v1/boards/<board_id>/files \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-6666-4c1a-9c1e-board-add-files" \
  -d '{"file_ids": ["<file_id_1>", "<file_id_2>"]}'

{
  "object": "board_files_batch",
  "board_id": "<board_id>",
  "results": [
    { "file_id": "<file_id_1>", "status": "added" },
    { "file_id": "<file_id_2>", "status": "added" }
  ]
}

If any id in file_ids is one your key can't reach, the whole batch fails before anything is added — there's no partial "added some, skipped one" outcome for a bad id. Re-sending the same ids is always safe: an id already on the board answers already_in_board rather than erroring.

3. Set a value

curl -X PUT https://us.api.brault.app/v1/boards/<board_id>/files/<file_id_1>/properties/<status_property_id> \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": {"option_id": "<in_progress_option_id>"}}'

This returns the updated board_file — the file, this board's values for it, and when it was added.

4. Query the board by that value

Filtering uses the same JSON grammar as GET /v1/files?filter=… (see Conventions for pagination and the Boards reference for the full operator table):

curl -X POST https://us.api.brault.app/v1/boards/<board_id>/query \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "property": "<status_property_id>", "status": { "equals": "<in_progress_option_id>" } },
    "sort": "added_at",
    "order": "desc"
  }'

This is a read that uses POST because filter is a JSON document, not something that fits cleanly in a query string — sending an Idempotency-Key on it is harmless and just replays the same page.

A note on file access

Viewing a board is a read-through: if your key's creator can view the board, they see every file on it — including ones from libraries they hold no role in. Writing is narrower — adding, removing or setting a value for a file additionally requires the creator's role on that file's own library or folder to include the matching edit right. A board that aggregates files from libraries the creator can't edit is read-only for those specific files through the API, the same as it is in the web app.