Update a column

PATCH

/v1/boards/{id}/columns/{columnId}

const url = 'https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns/c6873aab-85de-4200-9afc-43470b21cf4c';
const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Channel","multiple":true,"options":[{"id":"9dc9bc29-97d0-48d0-afec-fdbc728d246d","name":"Meta"},{"id":"b2e7f6a1-3c48-4d95-a0e1-7f5c9d2b8a64","name":"TikTok"},{"id":"e8c41d97-52fa-4b3e-9d06-1a7b6f3c5e20","name":"YouTube"},{"name":"Pinterest"}],"config":{"character_limit":280,"wrap_text":true}}'
};

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

• Production

Rename a column, change how many values it holds, rewrite a tags column’s options, or adjust its type-specific config. Only the keys you include change. A column’s type is not patchable — cell values are encoded per type. The board’s system columns — the name, created-by and updated-by sub-types and the createdat / updatedat types, which are backed by fields on the row itself rather than by a cell — can’t be edited or archived (400). Carrying a sub_type isn’t itself disqualifying: start-date / due-date are ordinary columns.

Changing a board’s columns needs the same edit:board permission the app’s Edit fields panel 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

columnId

required

string format: uuid

Example

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

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 column’s label on the board. 1–255 characters, and unique on the board (case-insensitive) — a name another column already has is a 400, matching what the app refuses to save.

string

>= 1 characters <= 255 characters

Example

Channel

multiple

Whether each row holds several values in this column. Only tags, user and media columns can (400 on any other type). Changing it on a populated column rewrites every row’s stored value in the background, and multiple → single keeps only each cell’s first value.

boolean

Example

true

options

Rewrites the column’s option set, in display order. tags columns only. An entry with an id keeps that option (renaming it, and replacing its description if you send one); an entry without one adopts the existing option of the same name, or is added as new — so re-sending a name you already have keeps its id, and retrying is safe. Must list every option the column currently has: omitting one is a 400, not a removal, since removing an option clears that value from every row holding it. Listing the same id twice is rejected. At most 499 options.

Array<object>

object

id

Id of an existing option on this column to keep. Omit to add a new option. An id that isn’t an option of this column → 400.

string format: uuid

Example

9dc9bc29-97d0-48d0-afec-fdbc728d246d

name

required

The option’s label, as shown in the cell and its picker.

string

>= 1 characters <= 255 characters

Example

Meta

description

Replaces the option’s help text. Omit to leave whatever it already has — unlike name, an absent description is not a request to clear it; send "" for that.

string

<= 500 characters

Example

Facebook and Instagram placements

Example

[
  {
    "id": "9dc9bc29-97d0-48d0-afec-fdbc728d246d",
    "name": "Meta"
  },
  {
    "id": "b2e7f6a1-3c48-4d95-a0e1-7f5c9d2b8a64",
    "name": "TikTok"
  },
  {
    "id": "e8c41d97-52fa-4b3e-9d06-1a7b6f3c5e20",
    "name": "YouTube"
  },
  {
    "name": "Pinterest"
  }
]

config

Type-specific configuration, mirroring the config object a column read returns. Only the keys belonging to this column’s type are accepted — any other key is a 400 naming it, rather than a setting that silently did nothing:

• text → character_limit, uppercase, wrap_text, text_format
• richtext → character_limit
• number → unit, unit_position, decimal_places, number_format
• date → date_format
• media → default_to_library, folder_id, default_status
• mediacolumn → media_column_ids
• creativeid → naming_convention_id, media_column_ids, trigger_type, automation_id
• tags, checkbox, user, link, rating, color → no configuration

Keys you omit keep their stored value. folder_id must name a folder in the board’s own space, and every media_column_ids entry a media column on this same board.

object

character_limit

integer

nullable >= 1 <= 100000

Example

280

uppercase

boolean

Example

false

wrap_text

boolean

Example

true

text_format

string

nullable

Allowed values: capitalize uppercase lowercase titlecase

unit

string

nullable <= 10 characters

Example

$

unit_position

string

Allowed values: prefix suffix

decimal_places

integer

nullable <= 10

Example

2

number_format

string

nullable

Allowed values: bytes duration aspectRatio compact percentage

date_format

object

style

required

How the date value is displayed.

string

Allowed values: friendly iso local month week relative

show_year

boolean

Example

true

hide_current_year

boolean

Example

true

show_time

boolean

Example

false

default_to_library

boolean

Example

true

folder_id

string format: uuid

nullable

Example

80539d38-3a8e-48f8-929b-8c0e9a22ab43

default_status

string

nullable <= 255 characters

Example

In review

media_column_ids

Array<string>

Example

[
  "4f9b2d70-1c35-4a8e-96d3-b05e7a1c8f42"
]

naming_convention_id

string format: uuid

Example

4dbe5363-dad0-4bf7-aa75-18219b1b2229

trigger_type

string

Allowed values: new-row new-media automation

automation_id

string format: uuid

nullable

Example

f6cfbb93-796a-4908-8057-b1d6e10fb668

Example

{
  "character_limit": 280,
  "wrap_text": true
}

Responses

200

OK

Media typeapplication/json

object

data

required

object

id

required

string format: uuid

board_id

required

ID of the board this column belongs to.

string format: uuid

name

required

Human-readable column label.

string

type

required

Data type of this column. Dispatch on this when reading the column’s value on a row (Row.fields[].value) to know the JSON shape to expect (for a multi-value column — Row.fields[].multiple is true — it’s the type of each array element):

• number / rating → JSON number
• checkbox → JSON true / false
• date / updatedat → ISO 8601 string
• tags / user / media / relation / list → JSON string
• richtext → Markdown string
• mediacolumn → the referenced media attribute’s type (e.g. a user attribute stores user id strings)
• checklist / insights / metricsdata / externaldata / mediaattribute → JSON object
• everything else → JSON string

string

Allowed values: text media number tags checkbox user date color link rating richtext updatedat createdat relation mediacolumn externaldata creativeid checklist list insights mediaattribute metricsdata

sub_type

required

Optional refinement of type — present on system columns (e.g. name for the title column, created-by, due-date) that have a special role in the board. null for plain user-defined columns. The title column is identified by sub_type === "name" and its value is also hoisted to Row.title.

string

nullable

Allowed values: name created-by updated-by start-date due-date

multiple

required

When true, the column stores an array of values per row (e.g. multi-select). When false, a single value. For mediacolumn columns this reflects the mirrored media attribute’s cardinality.

boolean

order

required

Legacy sort position — don’t sort by this. No part of the product maintains it: it’s null on the large majority of columns and stale where it is set (it only survives being copied when a board is duplicated or transferred), so a board’s columns can’t be ordered by it. Column order and visibility are a property of a view instead: read a view’s visible_column_ids for the order a board is actually presented in. For a stable order, rely on the listing order of GET /v1/boards/{id}/columns (newest first), which is also the order each row’s fields array uses.

number

nullable

options

required

For tags columns — and mediacolumn columns whose mirrored media attribute is a tags field (media_attribute_type: "tags") — the selectable options in display order (each { id, name }). Such a cell stores option id(s) in Row.fields[].value; map them against this list, or read the resolved label(s) directly from Row.fields[].display_value. null for column types that have no options.

Array<object>

nullable

object

id

required

Stable option id — the value a tags cell stores in Row.fields[].value.

string

name

required

Human-readable option label shown in the UI.

string

media_attribute_id

required

For mediacolumn columns, the id of the media attribute definition this column mirrors. Attributes of the public field types (text, number, tags, checkbox, date, link, user) can be fetched via GET /v1/media-attributes/{id}, and the inline media_attribute_type, multiple, and options carry everything needed to interpret or write the cell. null for every other column type.

string format: uuid

nullable

media_attribute_type

required

For mediacolumn columns, the data type of the mirrored media attribute — the type that governs the cell’s value shape, writability, and multiple flag (the column’s own type stays "mediacolumn"). null for every other column type, or when the mirrored attribute no longer exists (the column is then read-only).

string

nullable

Allowed values: text number tags checkbox date link user

config

required

Any of:

object

object

character_limit

required

number

nullable

uppercase

required

boolean

wrap_text

required

boolean

text_format

required

string

nullable

Allowed values: capitalize uppercase lowercase titlecase

object

object

unit

required

string

nullable

unit_position

required

Whether unit renders before or after the number.

string

Allowed values: prefix suffix

decimal_places

required

number

nullable

number_format

required

string

nullable

Allowed values: bytes duration aspectRatio compact percentage

object

object

date_format

required

object

style

required

How the date/timestamp value is displayed.

string

Allowed values: friendly iso local month week relative

show_year

required

boolean

hide_current_year

required

With show_year on, still omit the year for dates in the current year.

boolean

show_time

boolean

object

object

character_limit

required

number

nullable

object

object

default_to_library

required

Whether media attached through this column is also added to the space’s media library (vs. staying board-only).

boolean

folder_id

required

string

nullable

default_status

required

string

nullable

object

object

media_column_ids

required

IDs of this board’s media columns whose attached media receive this attribute’s value when the cell is written.

Array<string>

object

object

allow_assignee

required

boolean

allow_due_date

required

boolean

items

required

The checklist’s fixed items, in display order.

Array<object>

object

id

required

string

text

required

string

order

required

number

object

object

allow_assignee

required

boolean

allow_due_date

required

boolean

allow_checkbox

required

boolean

object

object

naming_convention_id

required

string

nullable

media_column_ids

required

IDs of this board’s media columns this naming convention generates a filename for.

Array<string>

trigger_type

required

string

nullable

Allowed values: new-row new-media automation

automation_id

required

string

nullable

object

object

ad_account_id

required

string

nullable

external_id

required

string

nullable

metric

required

string

nullable

object

object

metric

required

string

currency

required

string

object

object

feature_id

required

string

nullable

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

Example

{
  "data": {
    "id": "87674a42-14d6-4ea3-abce-0507004eb2a0",
    "board_id": "24ce3d43-516c-4375-9d51-e9a2c8333683",
    "name": "Deliverable",
    "type": "text",
    "sub_type": "name",
    "multiple": false,
    "order": null,
    "options": null,
    "media_attribute_id": null,
    "media_attribute_type": "text",
    "config": {
      "character_limit": 280,
      "uppercase": false,
      "wrap_text": true,
      "text_format": "capitalize"
    },
    "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"
  }
}

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.