Update a view

PATCH

/v1/boards/{id}/views/{viewId}

const url = 'https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/views/a8d4d188-91cb-429f-9fa9-b6b20b43600f';
const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Launch calendar","type":"grid","filters":[{"column_id":"c6873aab-85de-4200-9afc-43470b21cf4c","operator":"equals","value":"Meta"}],"visible_column_ids":["3298a55a-c00c-4438-9a92-661ae534c8a3","c6873aab-85de-4200-9afc-43470b21cf4c","993784a7-2dfc-4c80-b52b-0601abf0b58f","3b3fe259-8156-4c9d-967d-614c0eb60daa"],"position":1}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

• Production

Edit a board view. Only the properties you send change; omitting filters leaves the view’s saved conditions untouched, and omitting visible_column_ids leaves its column set alone.

Read filters_complete before sending back a filters array you read from the view: when it is false the view holds conditions the public vocabulary can’t express, and writing the approximation back would change which rows the view shows.

Creating and changing a board’s views needs the same edit:board permission the app’s view editor does, checked against the connected user; an organization-scoped API token isn’t restricted this way.

Required scope: boards:write. Rate-limit cost: 10. Honors an optional Idempotency-Key.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Example

24ce3d43-516c-4375-9d51-e9a2c8333683

viewId

required

string format: uuid

Example

a8d4d188-91cb-429f-9fa9-b6b20b43600f

Header Parameters

Idempotency-Key

string

<= 255 characters

Example

looker-sync-2027-03-04-0001

Client-generated key (≤255 chars) for safe retries. A retry with the same key replays the original response instead of re-applying the write; reusing a key with a different body → 400, an in-flight key → 409. Required on POST; optional on PATCH/DELETE. A UUID v4 is recommended — generate one per logical write and reuse it only for retries of that write.

Request Body^required

Media typeapplication/json

object

name

The view’s label on the board’s view bar. 1–255 characters. Unlike column names, view names need not be unique — the app allows duplicates.

string

>= 1 characters <= 255 characters

Example

Launch calendar

type

How the view presents the board’s rows.

string

Allowed values: grid board timeline cards

filters

Conditions a row must satisfy to appear in the view, in the same vocabulary as POST /v1/boards/{id}/rows/search — so a search you just ran can be saved as a view verbatim. Every entry must hold; a value array on an equals entry is any-of. [] clears the view’s filters. Two limits differ from search: is_empty / is_not_empty can’t be stored on a view (400), and not_equals takes a single value, because “none of these” has no stored form.

Array<object>

object

column_id

required

The column to filter on — a Column.id from GET /v1/boards/{id}/columns.

string format: uuid

Example

c6873aab-85de-4200-9afc-43470b21cf4c

operator

required

How the cell is compared to value:

• equals / not_equals — the cell holds (or doesn’t hold) the value. A multi-value cell matches on any of its values, so not_equals reads as “has none of these”. Strings are case-insensitive; date compares by calendar day.
• contains — case-insensitive substring of the cell’s text. Not on id-backed cells (tags, user, media, relation) — use equals (it accepts option names) or query.
• gt / gte / lt / lte — against a single number or ISO date.
• is_empty / is_not_empty — whether the cell holds anything. Takes no value, and the only operators available on structured cells (checklist, insights, metricsdata, externaldata, mediaattribute).

string

Allowed values: equals not_equals contains gt gte lt lte is_empty is_not_empty

value

Any of:

Array

Array

Any of:

string

string

number

number

boolean

boolean

object

object

key

additional properties

object

Any of:

string

string

number

number

boolean

boolean

object

object

key

additional properties

visible_column_ids

Column IDs the view shows, in display order — Column.id values from GET /v1/boards/{id}/columns. [] means the view declares no columns of its own and falls back to showing every column on the board, which is what a freshly created view does. A column the board doesn’t have is a 400, and so is naming the same column twice. Don’t send back a list you read from a view whose visible_columns_pinned is false: that set was synthesized from the board, and writing it pins it.

Array<string>

Example

[
  "3298a55a-c00c-4438-9a92-661ae534c8a3",
  "c6873aab-85de-4200-9afc-43470b21cf4c",
  "993784a7-2dfc-4c80-b52b-0601abf0b58f",
  "3b3fe259-8156-4c9d-967d-614c0eb60daa"
]

position

Sort position among the board’s views; lower renders first. Defaults to the end of the board’s views on create.

integer

<= 2147483647

Example

1

Responses

200

OK

Media typeapplication/json

object

data

required

object

id

required

string format: uuid

board_id

required

ID of the board this view belongs to.

string format: uuid

name

required

string

type

required

How the view presents the board’s rows (grid, board, timeline, cards). The rows feed applies the same filters and column projection regardless of type.

string

Allowed values: grid board timeline cards

position

required

The view’s sort position among its board’s views (lower renders first). null when unset.

number

nullable

filters

required

The view’s saved conditions, in the same vocabulary as POST /v1/boards/{id}/rows/search. A row must satisfy every entry; within an entry a value array is any-of. Pass this straight to the rows search to reproduce the view’s slice, or to POST/PATCH a view to save it. Empty when the view filters nothing. Check filters_complete before writing it back.

Array<object>

object

column_id

required

The column to filter on — a Column.id from GET /v1/boards/{id}/columns.

string format: uuid

operator

required

How the cell is compared to value:

• equals / not_equals — the cell holds (or doesn’t hold) the value. A multi-value cell matches on any of its values, so not_equals reads as “has none of these”. Strings are case-insensitive; date compares by calendar day.
• contains — case-insensitive substring of the cell’s text. Not on id-backed cells (tags, user, media, relation) — use equals (it accepts option names) or query.
• gt / gte / lt / lte — against a single number or ISO date.
• is_empty / is_not_empty — whether the cell holds anything. Takes no value, and the only operators available on structured cells (checklist, insights, metricsdata, externaldata, mediaattribute).

string

Allowed values: equals not_equals contains gt gte lt lte is_empty is_not_empty

value

Any of:

Array

Array

Any of:

string

string

number

number

boolean

boolean

object

object

key

additional properties

object

Any of:

string

string

number

number

boolean

boolean

object

object

key

additional properties

filters_complete

required

false when the view’s stored conditions can’t be expressed faithfully in the public filter vocabulary — a condition on a column that no longer exists, or two conditions on one column that the public AND semantics can’t reproduce. filters then describes the view only approximately, so PATCHing it back would change which rows the view shows. Re-state the filters you want instead of round-tripping them.

boolean

visible_column_ids

required

Column IDs this view shows, in display order — match against Column.id from GET /v1/boards/{id}/columns. This is the set GET /v1/boards/{id}/views/{viewId}/rows projects onto each row’s fields. Falls back to every column on the board when the view declares none — see visible_columns_pinned, and don’t write such a list back: it pins today’s board columns onto the view, so a column added later never appears in it. [] restores “follow the board”.

Array<string>

visible_columns_pinned

required

Whether visible_column_ids is the view’s own column set (true) or was synthesized from the board because the view declares none (false). Writing a synthesized list back pins it — the view stops following the board’s columns — so PATCH visible_column_ids only when you mean to choose the set, and send [] to go back to following the board.

boolean

organization_id

required

string format: uuid

space_id

required

string format: uuid

created_at

required

string format: date-time

updated_at

required

string format: date-time

html_url

required

Browser URL that opens this view on its board in the Focal web app. Hand this to users as a clickable link.

string

Example

{
  "data": {
    "id": "a8d4d188-91cb-429f-9fa9-b6b20b43600f",
    "board_id": "24ce3d43-516c-4375-9d51-e9a2c8333683",
    "name": "Launch calendar",
    "type": "grid",
    "position": 0,
    "filters": [
      {
        "column_id": "c6873aab-85de-4200-9afc-43470b21cf4c",
        "operator": "equals",
        "value": "Meta"
      }
    ],
    "filters_complete": true,
    "visible_column_ids": [
      "3298a55a-c00c-4438-9a92-661ae534c8a3",
      "c6873aab-85de-4200-9afc-43470b21cf4c",
      "993784a7-2dfc-4c80-b52b-0601abf0b58f",
      "3b3fe259-8156-4c9d-967d-614c0eb60daa"
    ],
    "visible_columns_pinned": true,
    "organization_id": "b46d9033-24b2-4441-87ad-2151088fde01",
    "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
    "created_at": "2027-03-04T10:15:00Z",
    "updated_at": "2027-03-06T14:42:00Z",
    "html_url": "https://app.focal.inc/spaces/6916bc3d-e1ab-425b-ac25-eefada01a9a2/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/a8d4d188-91cb-429f-9fa9-b6b20b43600f"
  }
}

400

The request was malformed (invalid cursor, unknown type, validation failure, etc.). error.code is bad_request.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body",
    "details": [
      {
        "field": "space_id",
        "issue": "Invalid UUID"
      }
    ]
  }
}

401

Missing, invalid, or disabled token. error.code is unauthenticated.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "unauthenticated",
    "message": "Bearer token is missing or invalid"
  }
}

403

The token doesn’t have the scope this endpoint requires. error.code is forbidden.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "forbidden",
    "message": "Token doesn't have the required scope"
  }
}

404

Resource doesn’t exist or is outside the token’s space allow-list. The two cases share a response shape so a restricted token can’t probe for the existence of out-of-scope spaces. error.code is not_found.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}

409

The request conflicts with the current state. Most commonly a concurrent request carrying the same Idempotency-Key is still in flight. error.code is conflict.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "conflict",
    "message": "A request with this Idempotency-Key is already being processed"
  }
}

429

Rate limit exceeded. error.code is rate_limited. Wait the number of seconds in the Retry-After header before retrying. Quotas are per-token; see the “Rate limiting” section at the top of this document.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 1000 units per 60s exceeded (this request cost 5)"
  }
}

Headers

Retry-After

integer

Example

12

Seconds to wait before retrying.