boards.update_settings

Change how one board's cards are filtered and ordered

Request: PATCH/api/v1/boards/{boardId}/settings
Scope required: boards:write
Effect: Changes data. Send an Idempotency-Key if you might retry it.
Acts on: Acts on the account’s own job search.
MCP tool: boards_update_settings
Environment: Live and sandbox alike.
Request body: JSON.

What it does

Changes the display settings of a single board: which status columns are hidden, how cards are sorted, how far back the time filter reaches, and whether stale applications are retired automatically. A field you leave out keeps its current value; sending an empty array for `hiddenStatuses` unhides every column. These settings are shared with the spreadsheet view, so narrowing the time filter here narrows it there too. The board’s own name and active flag are changed with `boards.update`.

Parameters

Parameters this endpoint accepts, where each one goes, and whether it is required
Name	Sent in	Requirement	Accepts
boardId	path	Required	string

Request body

autoRetire

object, optional

enabled: boolean, optional
status: one of: rejected, archived, optional
timeframe: one of: one_month, three_months, six_months, one_year, optional

hiddenStatuses

array of one of: saved, applied, interviewing, offer, rejected, accepted, archived, optional

sorts

array of one of: none, job_title_asc, job_title_desc, company_name_asc, company_name_desc, date_asc, date_desc, optional

timeFilter

one of: 7_days, 15_days, 1_month, 3_months, all, optional

Response

autoRetire

object, required

enabled: boolean, required
status: one of: rejected, archived, required
timeframe: one of: one_month, three_months, six_months, one_year, required

hiddenStatuses

array of one of: saved, applied, interviewing, offer, rejected, accepted, archived, required

sorts

array of one of: none, job_title_asc, job_title_desc, company_name_asc, company_name_desc, date_asc, date_desc, required

timeFilter

one of: 7_days, 15_days, 1_month, 3_months, all, required

Examples

Hide the archived column and sort newest first

Hide the archived column and sort newest first — request

curl -s -X PATCH https://www.jobapplicationtracking.com/api/v1/boards/brd_7/settings \
  -H "Authorization: Bearer $JAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "hiddenStatuses": [
    "archived"
  ],
  "sorts": [
    "date_desc"
  ]
}'

Hide the archived column and sort newest first — response

{
  "hiddenStatuses": [
    "archived"
  ],
  "sorts": [
    "date_desc"
  ],
  "timeFilter": "all",
  "autoRetire": {
    "enabled": false,
    "timeframe": "three_months",
    "status": "rejected"
  }
}