---
title: "Change a sheet: cells (inputs and format keys, by row and column id), its layout (insert, delete, move, order, size, hide, freeze, merge, filter) or its title. Answers the write as it landed, the new rev and the stored cells it touched."
method: POST
path: "/documents/{id}/sheets/{sheetId}/writes"
tags: ["Sheets"]
---

# Change a sheet: cells (inputs and format keys, by row and column id), its layout (insert, delete, move, order, size, hide, freeze, merge, filter) or its title. Answers the write as it landed, the new rev and the stored cells it touched.

`POST /documents/{id}/sheets/{sheetId}/writes`

## Request

- Base URL: `https://www.livediagram.app/api`
- URL: `https://www.livediagram.app/api/documents/{id}/sheets/{sheetId}/writes`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Owner-Id`

## Path parameters

- `id` string, required
- `sheetId` string, required

## Query parameters

- `tabId` string

## Request body

- SheetWriteRequest
  - `unchecked` boolean
  - `undo` boolean
  - `wid` string
  - `write` union, required
    - object
      - `cells` CellChange[], required
        - `c` string, required
        - `f` FormatPatch
          - `b` unknown
          - `bb` unknown
          - `bg` unknown
          - `bl` unknown
          - `br` unknown
          - `bt` unknown
          - `cur` unknown
          - `dp` unknown
          - `fc` unknown
          - `ff` unknown
          - `fs` unknown
          - `ha` unknown
          - `i` unknown
          - `nc` unknown
          - `nf` unknown
          - `st` unknown
          - `u` unknown
          - `va` unknown
          - `wr` unknown
        - `i` union
          - object
            - `n` number, required
          - object
            - `s` string, required
          - object
            - `b` boolean, required
          - object
            - `f` StoredFormula, required
              - …
        - `r` string, required
      - `kind` 'cells', required
    - object
      - `cells` CellChange[]
        - `c` string, required
        - `f` FormatPatch
          - `b` unknown
          - `bb` unknown
          - `bg` unknown
          - `bl` unknown
          - `br` unknown
          - `bt` unknown
          - `cur` unknown
          - `dp` unknown
          - `fc` unknown
          - `ff` unknown
          - `fs` unknown
          - `ha` unknown
          - `i` unknown
          - `nc` unknown
          - `nf` unknown
          - `st` unknown
          - `u` unknown
          - `va` unknown
          - `wr` unknown
        - `i` union
          - object
            - `n` number, required
          - object
            - `s` string, required
          - object
            - `b` boolean, required
          - object
            - `f` StoredFormula, required
              - …
        - `r` string, required
      - `changes` LayoutChange[], required
        - union
          - object
            - `after` string, nullable, required
            - `ids` string[], required
            - `k` 'insertRows' | 'insertCols', required
          - object
            - `ids` string[], required
            - `k` 'deleteRows' | 'deleteCols', required
          - object
            - `after` string, nullable, required
            - `ids` string[], required
            - `k` 'moveRows' | 'moveCols', required
          - object
            - `ids` string[], required
            - `k` 'orderRows' | 'orderCols', required
          - object
            - `axis` 'r' | 'c', required
            - `ids` string[], required
            - `k` 'size', required
            - `px` number, nullable, required
          - object
            - `axis` 'r' | 'c', required
            - `hidden` boolean, required
            - `ids` string[], required
            - `k` 'hide', required
          - object
            - `cols` number
            - `k` 'freeze', required
            - `rows` number
          - object
            - `k` 'merge', required
            - `range` IdRange, required
              - …
          - object
            - `k` 'unmerge', required
            - `range` IdRange, required
              - …
          - object
            - `k` 'merges', required
            - `merges` IdRange[], required
              - …
          - object
            - `filter` SheetFilter, required
              - …
            - `k` 'filter', required
          - object
            - `col` string, required
            - `cond` FilterCondition, required
              - …
            - `k` 'filterCond', required
          - object
            - `colWidth` number, nullable
            - `k` 'options', required
            - `rowHeight` number, nullable
            - `setupPending` boolean
            - `showGrid` boolean
            - `showHeaders` boolean
          - object
            - `id` string, required
            - `k` 'cardTable', required
            - `table` CardTable, required
              - …
          - object
            - `k` 'name', required
            - `name` string, required
            - `range` IdRange, required
              - …
          - object
            - `id` string, required
            - `k` 'vrule', required
            - `rule` ValidationRule, required
              - …
          - object
            - `at` number
            - `id` string, required
            - `k` 'frule', required
            - `rule` FormatRule, required
              - …
          - object
            - `ids` string[], required
            - `k` 'fruleOrder', required
      - `kind` 'layout', required
    - object
      - `kind` 'title', required
      - `title` string, required

## Response `200`

Success.

- SheetWriteResponse
  - `applied` union, required
    - object
      - `cells` CellChange[], required
        - `c` string, required
        - `f` FormatPatch
          - `b` unknown
          - `bb` unknown
          - `bg` unknown
          - `bl` unknown
          - `br` unknown
          - `bt` unknown
          - `cur` unknown
          - `dp` unknown
          - `fc` unknown
          - `ff` unknown
          - `fs` unknown
          - `ha` unknown
          - `i` unknown
          - `nc` unknown
          - `nf` unknown
          - `st` unknown
          - `u` unknown
          - `va` unknown
          - `wr` unknown
        - `i` union
          - object
            - `n` number, required
          - object
            - `s` string, required
          - object
            - `b` boolean, required
          - object
            - `f` StoredFormula, required
              - …
        - `r` string, required
      - `kind` 'cells', required
    - object
      - `cells` CellChange[]
        - `c` string, required
        - `f` FormatPatch
          - `b` unknown
          - `bb` unknown
          - `bg` unknown
          - `bl` unknown
          - `br` unknown
          - `bt` unknown
          - `cur` unknown
          - `dp` unknown
          - `fc` unknown
          - `ff` unknown
          - `fs` unknown
          - `ha` unknown
          - `i` unknown
          - `nc` unknown
          - `nf` unknown
          - `st` unknown
          - `u` unknown
          - `va` unknown
          - `wr` unknown
        - `i` union
          - object
            - `n` number, required
          - object
            - `s` string, required
          - object
            - `b` boolean, required
          - object
            - `f` StoredFormula, required
              - …
        - `r` string, required
      - `changes` LayoutChange[], required
        - union
          - object
            - `after` string, nullable, required
            - `ids` string[], required
            - `k` 'insertRows' | 'insertCols', required
          - object
            - `ids` string[], required
            - `k` 'deleteRows' | 'deleteCols', required
          - object
            - `after` string, nullable, required
            - `ids` string[], required
            - `k` 'moveRows' | 'moveCols', required
          - object
            - `ids` string[], required
            - `k` 'orderRows' | 'orderCols', required
          - object
            - `axis` 'r' | 'c', required
            - `ids` string[], required
            - `k` 'size', required
            - `px` number, nullable, required
          - object
            - `axis` 'r' | 'c', required
            - `hidden` boolean, required
            - `ids` string[], required
            - `k` 'hide', required
          - object
            - `cols` number
            - `k` 'freeze', required
            - `rows` number
          - object
            - `k` 'merge', required
            - `range` IdRange, required
              - …
          - object
            - `k` 'unmerge', required
            - `range` IdRange, required
              - …
          - object
            - `k` 'merges', required
            - `merges` IdRange[], required
              - …
          - object
            - `filter` SheetFilter, required
              - …
            - `k` 'filter', required
          - object
            - `col` string, required
            - `cond` FilterCondition, required
              - …
            - `k` 'filterCond', required
          - object
            - `colWidth` number, nullable
            - `k` 'options', required
            - `rowHeight` number, nullable
            - `setupPending` boolean
            - `showGrid` boolean
            - `showHeaders` boolean
          - object
            - `id` string, required
            - `k` 'cardTable', required
            - `table` CardTable, required
              - …
          - object
            - `k` 'name', required
            - `name` string, required
            - `range` IdRange, required
              - …
          - object
            - `id` string, required
            - `k` 'vrule', required
            - `rule` ValidationRule, required
              - …
          - object
            - `at` number
            - `id` string, required
            - `k` 'frule', required
            - `rule` FormatRule, required
              - …
          - object
            - `ids` string[], required
            - `k` 'fruleOrder', required
      - `kind` 'layout', required
    - object
      - `kind` 'title', required
      - `title` string, required
  - `cells` SheetCellDto[], required
    - `c` string, required
    - `f` CellFormat
      - `b` true
      - `bb` Border
        - `c` string, required
        - `s` 'solid' | 'dashed' | 'dotted' | 'dash-dot' | 'long-dash' | 'dash-dot-dot', required
        - `w` 1 | 2 | 3, required
      - `bg` string
      - `bl` Border
        - `c` string, required
        - `s` 'solid' | 'dashed' | 'dotted' | 'dash-dot' | 'long-dash' | 'dash-dot-dot', required
        - `w` 1 | 2 | 3, required
      - `br` Border
        - `c` string, required
        - `s` 'solid' | 'dashed' | 'dotted' | 'dash-dot' | 'long-dash' | 'dash-dot-dot', required
        - `w` 1 | 2 | 3, required
      - `bt` Border
        - `c` string, required
        - `s` 'solid' | 'dashed' | 'dotted' | 'dash-dot' | 'long-dash' | 'dash-dot-dot', required
        - `w` 1 | 2 | 3, required
      - `cur` string
      - `dp` number
      - `fc` string
      - `ff` string
      - `fs` number
      - `ha` 'l' | 'c' | 'r'
      - `i` true
      - `nc` string
      - `nf` 'auto' | 'number' | 'percent' | 'currency' | 'accounting' | 'scientific' | 'date' | 'time' | 'datetime' | 'duration' | 'text' | 'custom'
      - `st` true
      - `u` true
      - `va` 't' | 'm' | 'b'
      - `wr` 'o' | 'w' | 'c'
    - `i` union
      - object
        - `n` number, required
      - object
        - `s` string, required
      - object
        - `b` boolean, required
      - object
        - `f` StoredFormula, required
          - `r` StoredRef[], required
            - `a` number
            - `c1` string
            - `c2` string
            - `open` 'r' | 'c'
            - `p` number[]
            - `r1` string
            - `r2` string
            - `s` string
            - `spill` true
            - `st` string
          - `t` string, required
    - `r` string, required
  - `rev` number, required

## Other responses

- `400`: Error.
- `401`: Error.
- `403`: Error.
- `404`: Error.
- `409`: Error.
- `410`: Error.
- `413`: Error.
- `429`: Rate limited. Back off and retry.

---

[API](https://skmtc.dev/livediagram/apis/livediagram-api.md) · [All operations](https://skmtc.dev/livediagram/apis/livediagram-api/llms.txt) · [OpenAPI document](https://skmtc.dev/livediagram/apis/livediagram-api/revisions/f286d27acfd2?raw)