---
title: "Change one tab with a changeset: ordered edit operations or one replace, applied atomically, shown live to everyone with the tab open, credited to you and revertable. Pass the base you read (rev and element fingerprints) to refuse a write over a change made since. A whole-tab replace on a tab id the document lacks creates that tab."
method: POST
path: "/documents/{id}/tabs/{tabId}/changesets"
tags: ["Changesets"]
---

# Change one tab with a changeset: ordered edit operations or one replace, applied atomically, shown live to everyone with the tab open, credited to you and revertable. Pass the base you read (rev and element fingerprints) to refuse a write over a change made since. A whole-tab replace on a tab id the document lacks creates that tab.

`POST /documents/{id}/tabs/{tabId}/changesets`

## Request

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

## Path parameters

- `id` string, required
- `tabId` string, required

## Query parameters

- `dryRun` string

## Request body

- ChangesetRequest
  - `base` ChangesetBase
    - `elements` object
    - `rev` number, required
  - `operations` union
    - unknown[]
      - unknown
    - string
  - `replace` ChangesetReplaceBody
    - `dashboard` object
    - `elements` unknown[]
      - unknown
    - `finish` 'flexible' | 'professional' | 'sketch' | 'marker'
    - `form` object
    - `graph` unknown
    - `kind` 'board' | 'sheet'
    - `layout` 'auto' | 'preserve'
    - `mermaid` string
    - `name` string
    - `template` string
    - `theme` string
  - `strict` boolean
  - `summary` string

## Response `200`

Success.

- ChangesetResponse
  - `changeset` ChangesetWritten, required
    - `id` string, required
    - `previousRev` number, required
    - `rebasedOver` number, required
    - `rev` number, required
    - `tabId` string, required
  - `dryRun` boolean, required
  - `lint` LintReport, required
    - `counts` object, required
      - `error` number, required
      - `info` number, required
      - `warning` number, required
    - `findings` LintFinding[], required
      - `code` 'box-overlap' | 'arrow-dangling' | 'arrow-behind-box' | 'edge-crossings' | 'label-collision' | 'label-overflow' | 'node-isolated' | 'group-escape' | 'group-split-edges' | 'duplicate-label' | 'flow-backwards' | 'aspect-extreme' | 'colour-on-themed' | 'text-overflow', required
      - `fix` string, required
      - `message` string, required
      - `refs` string[], required
      - `severity` 'error' | 'warning' | 'info', required
    - `measures` LintMeasures, required
      - `arrows` number, required
      - `behind` number, required
      - `boxes` number, required
      - `crossings` number, nullable, required
      - `extent` object, nullable, required
        - `height` number, required
        - `width` number, required
      - `overlaps` number, required
    - `skipped` object, required
      - `crossings` boolean, required
  - `results` ResultLine[], required
    - union
      - object
        - `at` number[]
        - `ends` string[]
        - `kind` string, required
        - `label` string
        - `mark` '+', required
        - `ref` string, required
        - `size` number[]
        - `styleOf` string
      - object
        - `changes` FieldChange[], required
          - `from` union
            - string
            - number
            - boolean
            - JsonValue[]
            - object
          - `key` string, required
          - `to` union
            - string
            - number
            - boolean
            - JsonValue[]
            - object
        - `mark` '~', required
        - `ref` string, required
      - object
        - `ends` string[]
        - `kind` string, required
        - `label` string
        - `mark` '-', required
        - `pinnedTo` string
        - `reason` 'pinned' | 'unwrapped'
        - `ref` string, required
      - object
        - `delta` number[]
        - `layout` object
          - `direction` 'down' | 'right'
          - `style` 'flow' | 'tree' | 'mindmap', required
        - `mark` '»', required
        - `reason` 'make room' | 'carried' | 'laid out' | 'landed on a lane', required
        - `refs` string[], required
      - object
        - `joined` string[], required
        - `left` string[], required
        - `mark` 'container', required
        - `ref` string, required
      - object
        - `mark` '!', required
        - `warning` EditWarning, required
          - `code` 'no_base' | 'shape_coerced' | 'value_coerced' | 'label_capped' | 'colour_overrides_theme' | 'arrows_freed', required
          - `message` string, required
          - `ref` string
  - `text` string, required
  - `warnings` string[], required

## Other responses

- `400`: Error.
- `401`: Error.
- `403`: Error.
- `404`: Error.
- `409`: Error.
- `410`: Error.
- `412`: Error.
- `413`: Error.
- `422`: 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)