Create a column

POST

/v1/boards/{id}/columns

const url = 'https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Channel","type":"text","media_attribute_id":"846196ad-9fa2-40a8-8938-655a962220e1","multiple":true,"options":[{"name":"Meta","description":"Facebook and Instagram placements"},{"name":"TikTok"},{"name":"YouTube"}],"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

Add a column to a board. The new column is appended to every one of the board’s views, so it shows up where a column added from the app would; write values into it with POST /v1/boards/{id}/rows or PATCH /v1/boards/{id}/rows/{rowId}.

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. An Idempotency-Key header is required.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Example

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

Header Parameters

Idempotency-Key

required

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

required

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

type

required

The kind of column to create. Cannot be changed afterwards — cell values are encoded per type — so add a new column rather than retyping one.

Two types need more than a name:

• mediacolumn mirrors a media attribute onto the board. It requires media_attribute_id and at least one entry in config.media_column_ids; a value written into the cell lands on the media attached in those columns, and an edit made on the asset shows up here — which is what makes the value filterable in the media library, unlike a plain column.
• creativeid auto-generates an ID for attached media. It requires config.naming_convention_id (a Creative ID pattern from the board’s space) and at least one entry in config.media_column_ids. A board holds at most one.

The types a column read can report but this can’t create are the system columns backed by a field on the row itself (createdat, updatedat, and the name / created-by / updated-by sub-types) and relation, insights, metricsdata, externaldata, mediaattribute, checklist, list; add those in the app.

string

Allowed values: text number tags checkbox date link richtext user rating color media mediacolumn creativeid

media_attribute_id

The media attribute a mediacolumn column mirrors — a MediaAttribute.id in the board’s own space, from GET /v1/media-attributes. Required for that type and rejected on every other one. Not patchable afterwards: the cell’s stored value is encoded for the attribute’s type, so repointing the column would strand it.

string format: uuid

Example

846196ad-9fa2-40a8-8938-655a962220e1

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

Initial options, in display order. tags columns only (400 on any other type); each option’s id is generated and returned on the created column. At most 499 options.

Array<object>

object

name

required

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

string

>= 1 characters <= 255 characters

Example

Meta

description

Help text shown next to the option when picking a value. At most 500 characters; send an empty string to clear it.

string

<= 500 characters

Example

Facebook and Instagram placements

Example

[
  {
    "name": "Meta",
    "description": "Facebook and Instagram placements"
  },
  {
    "name": "TikTok"
  },
  {
    "name": "YouTube"
  }
]

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

201

Created

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.