---
title: "Create Document"
method: POST
path: "/v1/documents"
tags: ["Document Access"]
---

# Create Document

`POST /v1/documents`

Creates a new document for the requesting user, with the specified title. Requires `title` and `product`. Optionally, a `parent` folder, `extensionBootstrapData`, or Lucid Standard Import `content` can be provided to customize the new document.

> 📘
>
> This endpoint can only create a new Lucidchart or Lucidspark document. It cannot modify an existing document's contents.

> 📘 ##### Document Creation Location
>
> When there is no `parent` field on the request, the new document will be created in a default location depending on the authorizing token's scopes.
>
> - If the token authorizing the request uses one of the `document.app` scopes, then the document will be created in an `app-specific folder`.
> - If one of the `document.content` scopes is used, the document will be created in the user's 'My Documents folder'.
> - If both types of scopes are authorized on the token, the `document.content` behavior will take priority and the document will be created in the user's 'My Documents' folder.

> 📘 ##### Bootstrap Data for Create Document
>
> Bootstrap data can be attached to the created document to be consumed by a specific [Extension Package](https://lucid.readme.io/docs/lucid-extension-api). See [Bootstrap Data for documents created via API](https://lucid.readme.io/docs/editor-extension-data#bootstrap-data-for-documents-created-via-api) for usage.

> 📘 Standard Import
>
> When `content` is provided, it must conform to the Lucid Standard Import schema. For more information on how to use the Standard Import, refer to the extensive reference documentation [here](doc:overview-si).
>
> For examples of how to use the Standard Import, refer to the `/standard-import` folder in Lucid's repository of [Sample Lucid REST Applications](https://github.com/lucidsoftware/sample-lucid-rest-applications/tree/main/standard-import). This repo also contains some example `.zip` Standard Import files you can reference or use in your own projects.

## Valid Authentication Methods

**API Key Grants:**
- `DocumentEdit`

**OAuth 2.0 User Token Scopes:**
- `lucidchart.document.content`
- `lucidchart.document.app.folder`
- `lucidspark.document.content`
- `lucidspark.document.app.folder`

## Request body

- object
  - `title` string, required — Title that should be given to the newly created document.
  - `product` 'lucidchart' | 'lucidspark', required — The Lucid Suite product types that can be created.
  - `parent` number — Folder ID for the new document.
  - `extensionBootstrapData` BootstrapData — Bootstrap data can be attached to the created document to be consumed by a specific Extension Package.
    - `packageId` string, required — Id of the extension package which will consume this data
    - `extensionName` string, required — Name of the editor extension which will consume this data. Note this is the name field of an editor extension found in your manifest.json file.
    - `minimumVersion` string, required — Minimum version of the extension package which will consume this data
    - `data` object, required — Data to provide to the extension package
  - `content` LucidStandardImportContent — Defines the content of a document using the Lucid Standard Import format, including pages, shapes, and lines. Mutually exclusive with `extensionBootstrapData`.
    - `version` 1, required — The version of the Lucid Standard Import format.
    - `pages` LucidStandardImportPage[], required — List of pages to create in the document. At least one page is required.
      - `id` string, required — Unique identifier for the page within the import.
      - `title` string, required — The title of the page.
      - `shapes` LucidStandardImportShape[] — List of shapes to place on the page.
        - `id` string, required — Unique identifier for the shape within the import. Used to reference this shape from lines and groups.
        - `type` 'bpmnActivity' | 'bpmnBlackBoxPool' | 'bpmnChoreography' | 'bpmnConversation' | 'bpmnDataObject' | 'bpmnDataStore' | 'bpmnEvent' | 'bpmnGateway' | 'bpmnGroup' | 'bpmnPool' | 'bpmnTextAnnotation' | 'braceContainer' | 'braceNote' | 'bracketContainer' | 'circle' | 'circleContainer' | 'cloud' | 'connector' | 'cross' | 'namedContainer' | 'namedShape' | 'data' | 'database' | 'decision' | 'delay' | 'diamond' | 'diamondContainer' | 'directAccessStorage' | 'display' | 'document' | 'doubleArrow' | 'flexiblePolygon' | 'freehandBlock' | 'freehandDrawing' | 'hexagon' | 'hotspot' | 'image' | 'internalStorage' | 'isoscelesTriangle' | 'lucidCard' | 'manualInput' | 'manualOperation' | 'merge' | 'multipleDocuments' | 'note' | 'octagon' | 'offPageLink' | 'or' | 'paperTape' | 'pentagon' | 'pillContainer' | 'polyStar' | 'predefinedProcess' | 'preparation' | 'process' | 'rectangle' | 'rectangleContainer' | 'rightTriangle' | 'roundedRectangleContainer' | 'singleArrow' | 'sparkCalloutSquare' | 'sparkContainer' | 'sparkFrame' | 'stickyNote' | 'storedData' | 'summingJunction' | 'swimLanes' | 'table' | 'terminator' | 'text' | 'umlClass', required — The type of shape to create.
        - `boundingBox` BoundingBox, required — The bounding box that defines a shape's position and size on the page.
          - `x` number, required — The x-coordinate of the top-left corner.
          - `y` number, required — The y-coordinate of the top-left corner.
          - `w` number, required — The width of the bounding box.
          - `h` number, required — The height of the bounding box.
        - `text` string — Text content to display inside the shape.
        - `opacity` integer — Opacity of the shape, from 0 (fully transparent) to 100 (fully opaque).
        - `note` string — A note to attach to the shape.
        - `zIndex` integer — The z-order of the shape on the page.
        - `customData` LucidStandardImportCustomDatum[] — Custom key-value data to attach to the shape.
          - `key` string, required — The data key.
          - `value` string, required — The data value.
        - `style` LucidStandardImportStyle — Visual style properties for a shape.
          - `fill` union — Fill style for a shape. The `type` field determines the fill kind. - `color`: A solid color fill. - `image`: An image fill, either by URL or by reference to an image in the import archive.
            - LucidStandardImportColorFill — A solid color fill.
              - …
            - LucidStandardImportImageFill — An image fill, either by URL or by reference to an image in the import archive.
              - …
          - `stroke` LucidStandardImportStroke — Stroke styling for a line.
            - `color` string — Hex color string for the stroke.
            - `width` number — Stroke thickness. Must be between 0 and 10, inclusive.
            - `style` 'solid' | 'dotted' | 'dashed' — The stroke dash style.
          - `rounding` number — Corner rounding radius for the shape. Must be between 0 and 720, inclusive.
          - `textColor` string — Text color as a hex color string.
        - `actions` LucidStandardImportAction[] — Interactive actions attached to the shape (e.g., navigate to a URL or page).
          - union — An interactive action attached to a shape. The `type` field determines the action kind.
            - object — Navigate to an external URL.
              - …
            - object — Navigate to a page in the current document.
              - …
            - object — Navigate to a page in another document.
              - …
            - object — Toggle visibility of layers.
              - …
            - object — Show layers.
              - …
            - object — Hide layers.
              - …
        - `linkedData` LucidStandardImportLinkedDatum[] — Links to data collection entries.
          - `collectionId` string, required — The ID of the collection containing the data.
          - `key` string, required — The key identifying the data entry within the collection.
      - `lines` LucidStandardImportLine[] — List of lines to place on the page.
        - `id` string, required — Unique identifier for the line within the import.
        - `lineType` 'straight' | 'elbow' | 'curved', required — The type of line routing.
        - `stroke` LucidStandardImportStroke — Stroke styling for a line.
          - `color` string — Hex color string for the stroke.
          - `width` number — Stroke thickness. Must be between 0 and 10, inclusive.
          - `style` 'solid' | 'dotted' | 'dashed' — The stroke dash style.
        - `endpoint1` union, required — An endpoint of a line. The `type` field determines how the endpoint is positioned. - `shapeEndpoint`: Connects to a shape by its ID. - `positionEndpoint`: Connects to an absolute position on the page. - `lineEndpoint`: Connects to another line at a relative position.
          - object — An endpoint connected to a shape.
            - `type` 'shapeEndpoint', required
            - `style` 'none' | 'aggregation' | 'arrow' | 'hollowArrow' | 'openArrow' | 'async1' | 'async2' | 'closedSquare' | 'openSquare' | 'bpmnConditional' | 'bpmnDefault' | 'closedCircle' | 'openCircle' | 'composition' | 'exactlyOne' | 'generalization' | 'many' | 'nesting' | 'one' | 'oneOrMore' | 'zeroOrMore' | 'zeroOrOne', required — The visual style of a line endpoint.
            - `shapeId` string, required — The ID of the shape to connect to.
            - `position` RelativePoint — A relative point with coordinates between 0 and 1, inclusive.
              - …
          - object — An endpoint at an absolute position on the page.
            - `type` 'positionEndpoint', required
            - `style` 'none' | 'aggregation' | 'arrow' | 'hollowArrow' | 'openArrow' | 'async1' | 'async2' | 'closedSquare' | 'openSquare' | 'bpmnConditional' | 'bpmnDefault' | 'closedCircle' | 'openCircle' | 'composition' | 'exactlyOne' | 'generalization' | 'many' | 'nesting' | 'one' | 'oneOrMore' | 'zeroOrMore' | 'zeroOrOne', required — The visual style of a line endpoint.
            - `position` AbsolutePoint, required — An absolute point on the page canvas.
              - …
          - object — An endpoint connected to another line.
            - `type` 'lineEndpoint', required
            - `style` 'none' | 'aggregation' | 'arrow' | 'hollowArrow' | 'openArrow' | 'async1' | 'async2' | 'closedSquare' | 'openSquare' | 'bpmnConditional' | 'bpmnDefault' | 'closedCircle' | 'openCircle' | 'composition' | 'exactlyOne' | 'generalization' | 'many' | 'nesting' | 'one' | 'oneOrMore' | 'zeroOrMore' | 'zeroOrOne', required — The visual style of a line endpoint.
            - `lineId` string, required — The ID of the line to connect to.
            - `position` number, required — Relative position along the line (0 to 1 inclusive).
        - `endpoint2` union, required — An endpoint of a line. The `type` field determines how the endpoint is positioned. - `shapeEndpoint`: Connects to a shape by its ID. - `positionEndpoint`: Connects to an absolute position on the page. - `lineEndpoint`: Connects to another line at a relative position.
          - object — An endpoint connected to a shape.
            - `type` 'shapeEndpoint', required
            - `style` 'none' | 'aggregation' | 'arrow' | 'hollowArrow' | 'openArrow' | 'async1' | 'async2' | 'closedSquare' | 'openSquare' | 'bpmnConditional' | 'bpmnDefault' | 'closedCircle' | 'openCircle' | 'composition' | 'exactlyOne' | 'generalization' | 'many' | 'nesting' | 'one' | 'oneOrMore' | 'zeroOrMore' | 'zeroOrOne', required — The visual style of a line endpoint.
            - `shapeId` string, required — The ID of the shape to connect to.
            - `position` RelativePoint — A relative point with coordinates between 0 and 1, inclusive.
              - …
          - object — An endpoint at an absolute position on the page.
            - `type` 'positionEndpoint', required
            - `style` 'none' | 'aggregation' | 'arrow' | 'hollowArrow' | 'openArrow' | 'async1' | 'async2' | 'closedSquare' | 'openSquare' | 'bpmnConditional' | 'bpmnDefault' | 'closedCircle' | 'openCircle' | 'composition' | 'exactlyOne' | 'generalization' | 'many' | 'nesting' | 'one' | 'oneOrMore' | 'zeroOrMore' | 'zeroOrOne', required — The visual style of a line endpoint.
            - `position` AbsolutePoint, required — An absolute point on the page canvas.
              - …
          - object — An endpoint connected to another line.
            - `type` 'lineEndpoint', required
            - `style` 'none' | 'aggregation' | 'arrow' | 'hollowArrow' | 'openArrow' | 'async1' | 'async2' | 'closedSquare' | 'openSquare' | 'bpmnConditional' | 'bpmnDefault' | 'closedCircle' | 'openCircle' | 'composition' | 'exactlyOne' | 'generalization' | 'many' | 'nesting' | 'one' | 'oneOrMore' | 'zeroOrMore' | 'zeroOrOne', required — The visual style of a line endpoint.
            - `lineId` string, required — The ID of the line to connect to.
            - `position` number, required — Relative position along the line (0 to 1 inclusive).
        - `text` LucidStandardImportLineText[] — Text labels to display along the line.
          - `text` string, required — The text content.
          - `position` number — Relative position along the line (0 to 1 inclusive).
          - `side` 'top' | 'middle' | 'bottom' — Which side of the line the text appears on.
        - `customData` LucidStandardImportCustomDatum[] — Custom key-value data to attach to the line.
          - `key` string, required — The data key.
          - `value` string, required — The data value.
        - `linkedData` LucidStandardImportLinkedDatum[] — Links to data collection entries.
          - `collectionId` string, required — The ID of the collection containing the data.
          - `key` string, required — The key identifying the data entry within the collection.
        - `joints` AbsolutePoint[] — Control points for straight lines.
          - `x` number, required — The x-coordinate. Must be between -1200000 and 1200000, inclusive.
          - `y` number, required — The y-coordinate. Must be between -1200000 and 1200000, inclusive.
        - `elbowControlPoints` AbsolutePoint[] — Control points for elbow lines.
          - `x` number, required — The x-coordinate. Must be between -1200000 and 1200000, inclusive.
          - `y` number, required — The y-coordinate. Must be between -1200000 and 1200000, inclusive.
        - `cornerRadius` number — Corner radius for elbow line bends.
        - `zIndex` integer — The z-order of the line on the page.
        - `lineJumps` boolean — Whether this line draws a small hump where it crosses other lines. When set, overrides the page-level `lineJumps` setting for this line only.
      - `groups` LucidStandardImportGroup[] — List of groups to create on the page.
        - `id` string, required — Unique identifier for the group.
        - `items` string[] — List of item IDs (shapes, lines, groups) contained in this group.
        - `customData` LucidStandardImportCustomDatum[] — Custom key-value data to attach to the group.
          - `key` string, required — The data key.
          - `value` string, required — The data value.
        - `linkedData` LucidStandardImportLinkedDatum[] — Links to data collection entries.
          - `collectionId` string, required — The ID of the collection containing the data.
          - `key` string, required — The key identifying the data entry within the collection.
        - `note` string — A note to attach to the group.
        - `zIndex` integer — The z-order of the group on the page.
      - `layers` LucidStandardImportLayer[] — List of layers to create on the page.
        - `id` string, required — Unique identifier for the layer.
        - `title` string, required — The display name of the layer.
        - `items` string[] — List of item IDs (shapes, lines, groups) contained in this layer.
        - `customData` LucidStandardImportCustomDatum[] — Custom key-value data to attach to the layer.
          - `key` string, required — The data key.
          - `value` string, required — The data value.
        - `linkedData` LucidStandardImportLinkedDatum[] — Links to data collection entries.
          - `collectionId` string, required — The ID of the collection containing the data.
          - `key` string, required — The key identifying the data entry within the collection.
        - `note` string — A note to attach to the layer.
        - `layerIndex` integer — The index order of the layer.
      - `customData` LucidStandardImportCustomPageDatum[] — Custom key-value data to attach to the page.
        - `key` string, required — The data key.
        - `value` string, required — The data value.
        - `global` boolean — When true, this data is globally inherited.
      - `dataBackedShapes` LucidStandardImportGenerator[] — List of data-backed shape generators (e.g., org charts, mind maps).
        - `type` 'orgChart' | 'mindMap' | 'assistedLayout' | 'umlSequence', required — The type of generator.
      - `settings` LucidStandardImportPageSettings — Page-level settings for a Lucid Standard Import page.
        - `fillColor` string — Background fill color for the page as a hex color string.
        - `infiniteCanvas` boolean — Whether the page uses an infinite canvas.
        - `size` union — Page size configuration. Either a standard page size with an optional format, or a custom size with explicit dimensions.
          - LucidStandardImportStandardPageSize — A standard named page size.
            - `type` 'letter' | 'legal' | 'executive' | 'a3' | 'a4' | 'a5' | 'tabloid' | 'folio' | 'statement', required — The standard page size name.
            - `format` 'landscape' | 'portrait' — Page orientation.
          - LucidStandardImportCustomPageSize — A custom page size with explicit dimensions.
            - `w` number, required — Width of the page. Must be between 1.0 and 20000.0, inclusive.
            - `h` number, required — Height of the page. Must be between 1.0 and 20000.0, inclusive.
        - `autoTiling` boolean — Whether auto-tiling is enabled for the page.
        - `lineJumps` boolean — Whether lines on this page draw small humps where they cross other lines. Individual lines may override this with their own `lineJumps` setting.
    - `collections` LucidStandardImportCollection[] — List of data collections to associate with the document.
      - union — A data collection to associate with the document. Exactly one of `dataSource` or `values` must be provided — providing both or neither is an error.
        - object
          - `id` string, required — Unique identifier for the collection.
          - `dataSource` string, required — The data source this collection belongs to.
        - object
          - `id` string, required — Unique identifier for the collection.
          - `values` object[], required — Inline JSON data for the collection. Each element is an object whose keys become the column headers and whose values become the row data.
    - `documentSettings` LucidStandardImportDocumentSettings — Document-level settings for a Lucid Standard Import.
      - `units` 'in' | 'cm' | 'px' | 'pt' — The measurement unit for the document. Defaults to inches (`in`) if not specified.

## Response `201`

Created with Document resource containing information about the newly created document.

- Document
  - `documentId` string, uuid, required — Unique ID of the document
  - `title` string, required — Title of the document
  - `editUrl` string, uri, required — Link to edit the document
  - `viewUrl` string, uri, required — Link to view the document
  - `version` integer, required — Most recent version
  - `pageCount` integer, required — Number of pages within the document
  - `canEdit` boolean, required — If requesting user can edit the document
  - `created` string, date-time, required — Date and time of when the document was created
  - `creatorId` integer, required — ID of user who created and owns the document
  - `lastModified` string, date-time, required — Date and time of when the document was last modified
  - `lastModifiedUserId` integer, required — ID of user who most recently modified the document
  - `customAttributes` CustomAttribute[], required — List of any custom attributes belonging to the document. Populated for Enterprise Accounts only.
    - `type` 'singleLineText' | 'multiLineText' | 'singleSelectDropdown' | 'multiSelectDropdown' | 'webLink' | 'numericalRange' | 'hierarchicalDropdown', required — The custom attribute type
    - `name` string — Title of the custom attribute. hierarchicalDropdown attributes do not have names.
    - `value` union — The value assigned to the custom attribute. The type of this value is determined by the Attribute Type.
      - string
      - union[]
        - union
          - DataPair — Object representing a key-value pair of data.
            - `name` string, required — Custom data key
            - `value` string, required — Custom data value
          - string
  - `customTags` string[], required — List of any custom tags assigned to the document
  - `product` 'lucidchart' | 'lucidscale' | 'lucidspark', required — The Lucid Suite product that a document was created in.
  - `status` string, nullable — Current assigned status of the document
  - `classification` string, nullable — Current assigned classification of the document
  - `classificationId` string, uuid, nullable — Current assigned classification ID of the document.
  - `trashed` string, date-time, nullable — If defined, the timestamp when the document was moved to the trash
  - `parent` integer, nullable — ID of the parent folder
  - `repository` Repository
    - `repositoryId` string — the ID of the repository
  - `accountId` integer, nullable, required — ID of Lucid account that owns the document
  - `owner` DocumentOwner
    - `id` number — Id of either the user or the account, depending on the type of the document user resource.
    - `type` string — Specifies if the owner resource is referring to a user or an account. Value will be either "user" or "account".
    - `name` string — Full name of the user that owns this document. This field is excluded if this document is owned by an account.

## Other responses

- `400` — Bad Request. * `'content' and 'extensionBootstrapData' cannot both be provided` — the `content` field is mutually exclusive with `extensionBootstrapData`. * Invalid `content` JSON — the provided content does not conform to the Lucid Standard Import schema.
- `403` — Forbidden. * if the user doesn't have access to or permissions to create within the specified parent folder. * if the token authorizing the request has the document.app scope with a specified parent folder that is outside the app folder's folder tree.

---

[API](https://skmtc.net/lucid/apis/lucid-rest-api.md) · [All operations](https://skmtc.net/lucid/apis/lucid-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lucid/lucid-rest-api/revisions/6a32cb9e1aa7/schema)