---
title: "Create a document, optionally seeding it with tabs and filing it in a team and/or folder. An invalid placement refuses the whole create by name (placement_invalid, team_forbidden, folder_not_found, folder_scope_mismatch) or a malformed intent (intent_invalid); nothing is written."
method: POST
path: "/documents"
tags: ["Documents"]
---

# Create a document, optionally seeding it with tabs and filing it in a team and/or folder. An invalid placement refuses the whole create by name (placement_invalid, team_forbidden, folder_not_found, folder_scope_mismatch) or a malformed intent (intent_invalid); nothing is written.

`POST /documents`

## Request

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

## Request body

- object
  - `id` string, required
  - `name` string, required: At most 60 characters; a longer name is stored shortened at a word boundary with an ellipsis, and whitespace runs collapse to one space.
  - `tabs` union[]: The tabs to seed. A tab may give `graph`, `mermaid` or `template` in place of `elements`, compiled by the edit-operations engine; a tab it refuses refuses the create (422, with `tabId`).
    - union
      - Tab
        - `articles` object
        - `backgroundAnimationSpeed` number
        - `backgroundColor` string
        - `backgroundOpacity` number
        - `backgroundPattern` 'grid' | 'blank' | 'lines' | 'crosshatch' | 'graph' | 'confetti' | 'stripes' | 'diagonal' | 'waves' | 'bricks' | 'isometric' | 'hexagonal' | 'engineering' | 'checkerboard' | 'sparkles' | 'eggs' | 'cobwebs' | 'snowflakes' | 'candy-stripes' | 'flow' | 'drift' | 'aurora' | 'ripple' | 'ribbons'
        - `backgroundPatternScale` number
        - `customColours` string[]
        - `dashboard` DashboardLayout
          - `background` 'tint'
          - `rows` DashboardRow[], required
            - `fill` true
            - `height` number, required
            - `id` string, required
            - `slots` DashboardSlot[], required
              - …
        - `defaultTextSize` union
          - 'scale' | 'sm' | 'md' | 'lg'
          - number
        - `elements` Element[], required
          - union
            - union
              - …
            - ArrowElement
              - …
        - `esLanesSettled` boolean
        - `finish` 'flexible' | 'professional' | 'sketch' | 'marker'
        - `folder` string
        - `font` string
        - `form` FormDefinition
          - `closedMessage` string
          - `closesAt` number
          - `confirmation` string
          - `cover` FormCover
            - `fill` union
              - …
            - `pattern` 'dots' | 'grid' | 'lines'
          - `description` string
          - `destination` FormDestination
            - `status` string, required
            - `tabId` string, required
            - `typeId` string, required
          - `heading` string, required
          - `limit` number
          - `sections` FormSection[], required
            - `description` string
            - `id` string, required
            - `questions` FormQuestion[], required
              - …
            - `showIf` SectionRule
              - …
            - `title` string, required
          - `sheet` FormSheetDestination
            - `sheetId` string, required
            - `tabId` string, required
          - `starter` 'blank' | 'bug-report' | 'feedback' | 'feature-request' | 'rsvp' | 'job-application' | 'contact'
          - `v` 1, required
        - `id` string, required
        - `kind` 'diagram' | 'event-storming' | 'board' | 'sheet' | 'dashboard' | 'form'
        - `layers` Layer[]
          - `id` string, required
          - `locked` boolean
          - `name` string, required
          - `opacity` number
          - `visible` boolean
        - `locked` boolean
        - `name` string, required
        - `opensIn` 'diagram' | 'draw' | 'workshop' | 'pages' | 'plan'
        - `pageOrientation` 'portrait' | 'landscape'
        - `pages` Page[]
          - `background` PageBackground
            - `fill` union
              - …
            - `pattern` 'dots' | 'grid' | 'lines'
          - `fit` PageSides
            - `height` number, required
            - `width` number, required
          - `flow` string
          - `id` string, required
          - `kind` 'infographic' | 'article' | 'slide' | 'logo'
          - `locked` true
          - `name` string
          - `orientation` 'portrait' | 'landscape', required
          - `rowAt` RowAt
            - `x` number, required
            - `y` number, required
          - `size` 'a4' | 'letter' | 'a3' | 'square' | 'social' | 'wide' | 'slide' | 'slide-classic' | 'logo' | 'fit'
          - `startedBlank` true
        - `patternColor` string
        - `tagColours` TagColour[]
          - `color` string, required
          - `tag` string, required
        - `templateChosen` boolean
        - `theme` string
        - `timer` TabTimer
          - `anchorAt` number
          - `durationMs` number
          - `frozenMs` number
          - `mode` 'countdown' | 'stopwatch', required
          - `running` boolean, required
          - `startedAt` number
        - `vote` TabVote
          - `active` boolean, required
          - `hideCounts` boolean
          - `hideCursors` boolean
          - `onePerElement` boolean
          - `revealed` boolean, required
          - `reviewIndex` number
          - `round` string
          - `startedBy` string
          - `voteLayerId` string
          - `votes` object, required
          - `votesPerPerson` number, required
      - object
        - `id` string, required
        - `name` string
        - `theme` string
        - `graph` object
        - `mermaid` string
        - `template` string
  - `source` 'ai' | 'mcp' | 'cli'
  - `teamId` string, nullable: The team library to file into; absent or null = the caller's My documents. Requires a signed-in caller (or API token) who has joined the team.
  - `folderId` string, nullable: A folder of the chosen space. null, present, is that space's root chosen on purpose; absent with no teamId is no choice, where a default folder may answer.
  - `intent` object, nullable: What the new document is made as, recorded on it (opensIn, tabKind, templateFamily). With no choice of place, the document lands in the caller's default folder for it: the tab kind default, else the template family default, else the mode default, else the root of My documents. Malformed: intent_invalid (400).
    - `mode` 'diagram' | 'draw' | 'workshop' | 'pages' | 'plan', required
    - `tabKind` 'diagram' | 'event-storming'
    - `templateFamily` 'retrospective' | 'kanban'
  - `createdAt` integer
  - `savedAt` integer
  - `markUsed` boolean: Whether making the document counts as a use of it for the caller, so it joins their Jump back in at once. Default true; send false when making many documents in one go (the editor does for an import of more than one), so they wait until opened. Not a boolean: 400 invalid markUsed.

## Response `201`

Success.

- object
  - `document` Document, required
    - `communityState` 'listed' | 'hidden' | 'null', nullable
    - `createdAt` number, required
    - `folderId` string, nullable, required
    - `id` string, required
    - `itemTypes` ItemTypeCatalogue
      - `types` ItemTypeDef[], required
        - `color` string, required
        - `custom` CustomFieldDef[]
          - `currency` string
          - `id` string, required
          - `kind` 'text' | 'longtext' | 'number' | 'currency' | 'date' | 'checkbox' | 'link' | 'email' | 'choice' | 'multichoice' | 'rating' | 'card', required
          - `label` string, required
          - `linkType` string
          - `onCard` boolean
          - `options` string[]
          - `scale` number
        - `defaultStatus` string
        - `detailsLabel` string
        - `display` object
          - `compact` object
            - `body` CardField[]
              - …
            - `foot` CardField[]
              - …
            - `footEnd` CardField[]
              - …
            - `head` CardField[]
              - …
            - `headEnd` CardField[]
              - …
            - `lead` CardField[]
              - …
            - `row` CardField[]
              - …
            - `trail` CardField[]
              - …
          - `detailed` object
            - `body` CardField[]
              - …
            - `foot` CardField[]
              - …
            - `footEnd` CardField[]
              - …
            - `head` CardField[]
              - …
            - `headEnd` CardField[]
              - …
            - `lead` CardField[]
              - …
            - `row` CardField[]
              - …
            - `trail` CardField[]
              - …
          - `minimal` object
            - `body` CardField[]
              - …
            - `foot` CardField[]
              - …
            - `footEnd` CardField[]
              - …
            - `head` CardField[]
              - …
            - `headEnd` CardField[]
              - …
            - `lead` CardField[]
              - …
            - `row` CardField[]
              - …
            - `trail` CardField[]
              - …
        - `excludedStatuses` string[]
        - `fields` string[], required
        - `glyph` union, required
          - 'task' | 'story' | 'bug' | 'project' | 'action' | 'epic' | 'milestone' | 'release' | 'ticket' | 'kanban' | 'checklist' | 'inbox' | 'person' | 'team' | 'user-plus' | 'user-check' | 'contact' | 'crown' | 'chat' | 'mail' | 'phone' | 'megaphone' | 'bell' | 'send' | 'video' | 'at' | 'calendar' | 'flag' | 'clock' | 'target' | 'pin' | 'hourglass' | 'repeat' | 'note' | 'idea' | 'bookmark' | 'book' | 'document' | 'pencil' | 'lightbulb' | 'puzzle' | 'quote' | 'star' | 'heart' | 'risk' | 'shield' | 'lock' | 'eye' | 'fire' | 'sparkle' | 'info' | 'question' | 'ban' | 'trophy' | 'coin' | 'chart' | 'trend' | 'briefcase' | 'cart' | 'building' | 'percent' | 'wallet' | 'cube' | 'gift' | 'wrench' | 'code' | 'laptop' | 'database' | 'cloud' | 'globe' | 'home' | 'key' | 'leaf' | 'link'
          - 'item'
        - `id` string, required
        - `label` string, required
        - `newTitle` string, required
        - `tabs` ItemTypeTab[]
          - `fields` string[], required
          - `id` string, required
          - `label` string, required
      - `version` number, required
    - `itemTypesRev` number
    - `name` string, required
    - `opensIn` 'diagram' | 'draw' | 'workshop' | 'pages' | 'plan', required
    - `ownerColor` string, nullable, required
    - `ownerId` string, required
    - `ownerName` string, nullable, required
    - `presentation` string, nullable, required
    - `savedAt` number, required
    - `shareCode` string, nullable, required
    - `shareable` boolean, required
    - `source` 'ai' | 'mcp' | 'cli', required
    - `tabKind` 'diagram' | 'event-storming', required
    - `tabs` TabSummary[], required
      - `documentId` string, required
      - `folder` string
      - `id` string, required
      - `name` string, required
      - `orderIndex` number, required
      - `outOfScope` true
      - `updatedAt` number, required
    - `teamId` string, nullable, required
    - `templateFamily` 'retrospective' | 'kanban', required

## Other responses

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