Update a row

PATCH

/v1/boards/{id}/rows/{rowId}

const url = 'https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/rows/6eee0a1d-ef35-45ee-b1c9-b95f1f54d652';
const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"title":"Hero video – 4:5 cut","position":2,"parent_id":"5d1a7c34-9b2e-4f60-8a15-2c7e90b1d4f8","fields":[{"column_id":"3298a55a-c00c-4438-9a92-661ae534c8a3","value":"In review"},{"column_id":"c6873aab-85de-4200-9afc-43470b21cf4c","value":["Meta","TikTok"]},{"column_id":"993784a7-2dfc-4c80-b52b-0601abf0b58f","value":"2027-03-15"}]}'
};

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

• Production

Update a row’s cell values (fields), title, position, and/or parent_id. Only the columns/fields you include change; only text, number, tags, checkbox, date, link, richtext, media, and user columns are writable, plus mediacolumn columns mirroring a text, number, tags, checkbox, date, link, or user media attribute — such cells take the attribute’s value shape and cardinality (see Column.media_attribute_type / Column.multiple) (richtext takes a Markdown string or a Tiptap doc; media takes media ids from the board’s space — upload new files via POST /v1/media/uploads first; user and user-backed mediacolumn cells take user ids of the board’s space members, see GET /v1/users?space_id=… — a mediacolumn write also pushes the value to the media attached to the row’s media columns). Setting parent_id moves the row under another row on the board (its child rows follow); null moves it to the top level. Moving a row under itself or one of its descendants is rejected.

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

rowId

required

string format: uuid

Example

6eee0a1d-ef35-45ee-b1c9-b95f1f54d652

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

title

Row title. This IS the write path for the board’s display-name column (the one with sub_type: "name", usually labelled Name) — that column is rejected as a cell, whatever its type. null clears it.

string

nullable <= 255 characters

Example

Hero video – 4:5 cut

position

Sort position (lower renders first). May be fractional.

number

nullable

Example

2

parent_id

Id of another row on the same board to nest this row under, making it a child row; null (the default on create) places the row at the board’s top level. On update, changing parent_id MOVES the row — its own child rows follow it. A row can’t be its own parent or move under one of its descendants (400). Siblings order by position.

string format: uuid

nullable

Example

5d1a7c34-9b2e-4f60-8a15-2c7e90b1d4f8

fields

Cell values to set — one entry per column. A column must clear two independent gates. Role: five columns hold their value on the row itself and are rejected whatever their type — the display-name column (sub_type: "name"), set via title instead, plus the created-by / updated-by sub_types and the createdat / updatedat types, which aren’t writable at all. Carrying a sub_type isn’t itself disqualifying: start-date / due-date are ordinary cells. Type: must be one of the writable types listed under value.

Array<object>

object

column_id

required

Column to set — Column.id from GET /v1/boards/{id}/columns.

string format: uuid

Example

3298a55a-c00c-4438-9a92-661ae534c8a3

value

required

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

Example

[
  {
    "column_id": "3298a55a-c00c-4438-9a92-661ae534c8a3",
    "value": "In review"
  },
  {
    "column_id": "c6873aab-85de-4200-9afc-43470b21cf4c",
    "value": [
      "Meta",
      "TikTok"
    ]
  },
  {
    "column_id": "993784a7-2dfc-4c80-b52b-0601abf0b58f",
    "value": "2027-03-15"
  }
]

Responses

200

OK

Media typeapplication/json

object

data

required

object

id

required

string format: uuid

board_id

required

string format: uuid

parent_id

required

Parent row id when this row is nested under another row; null for top-level rows.

string format: uuid

nullable

title

required

Convenience hoist of the title column’s value (the row’s display name). The same value also appears as a fields entry.

string

nullable

position

required

Row’s sort position within its board, lower values render first. Hoisted from the internal order field so clients can sort without an extra /columns call. May be fractional.

number

nullable

fields

required

Self-describing column values for this row — one entry per column, in the column’s display order. A multi-value column carries an array value; a single-value column a scalar. A column with no stored value is still listed, with an empty value ([] / null); archived columns and orphan storage keys are omitted.

Array<object>

object

column_id

required

Stable UUID of the column this value belongs to. Match against Column.id from GET /v1/boards/{id}/columns.

string format: uuid

column_name

required

Human-readable column label, mirrors what users see in the UI.

string

type

required

The kind of column this value belongs to. Combined with multiple, tells you the JSON type of value (for a multi-value column 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

multiple

required

Whether this column holds multiple values. When true, value is an array (one element per stored value); when false, value is a single scalar. For mediacolumn columns this reflects the referenced media attribute’s own setting.

boolean

value

required

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

display_value

required

Any of:

string

string

Array<string>

Array<string>

organization_id

required

string format: uuid

space_id

required

string format: uuid

archived

required

true when the row has been archived. List endpoints exclude archived rows by default, so this is always false for rows returned by GET /v1/boards/{id}/rows. Kept on the schema so clients know the field exists.

boolean

created_at

required

string format: date-time

updated_at

required

string format: date-time

html_url

required

Browser URL that opens this row as a detail panel over its board in the Focal web app. Hand this to users as a clickable link to the exact row.

string

Example

{
  "data": {
    "id": "6eee0a1d-ef35-45ee-b1c9-b95f1f54d652",
    "board_id": "24ce3d43-516c-4375-9d51-e9a2c8333683",
    "parent_id": "5d1a7c34-9b2e-4f60-8a15-2c7e90b1d4f8",
    "title": "Hero video – 4:5 cut",
    "position": 2,
    "fields": [
      {
        "column_id": "3298a55a-c00c-4438-9a92-661ae534c8a3",
        "column_name": "Status",
        "type": "text",
        "multiple": false,
        "value": "In review",
        "display_value": "In review"
      },
      {
        "column_id": "c6873aab-85de-4200-9afc-43470b21cf4c",
        "column_name": "Channel",
        "type": "tags",
        "multiple": true,
        "value": [
          "9dc9bc29-97d0-48d0-afec-fdbc728d246d",
          "b2e7f6a1-3c48-4d95-a0e1-7f5c9d2b8a64"
        ],
        "display_value": [
          "Meta",
          "TikTok"
        ]
      },
      {
        "column_id": "993784a7-2dfc-4c80-b52b-0601abf0b58f",
        "column_name": "Launch date",
        "type": "date",
        "multiple": false,
        "value": "2027-03-15",
        "display_value": "2027-03-15"
      }
    ],
    "organization_id": "b46d9033-24b2-4441-87ad-2151088fde01",
    "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
    "archived": false,
    "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?panel=row_6eee0a1d-ef35-45ee-b1c9-b95f1f54d652"
  }
}

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.