These docs are for v1.0. Click to read the latest docs for v1.2.

The Lucid Standard Import offers the ability to format JSON that can be used to import shapes, lines, groups, and more into a new Lucidchart or Lucidspark board.

The Standard Import can be accessed via Lucid's Import Document REST API endpoint, where the file and title are provided through the form data. If no title is specified, the document will be automatically assigned the name of the file.

The import request has an additional required product field where the user specifies the new document's product. The two currently-supported products are lucidchart and lucidspark.

The Lucid Standard Import is evolving and over time more features may be added. If there is something missing, submit and request feedback in our Community feedback space.

Explore below to see the wide variety of objects we support as well as details on the format of each.

📘

Due to the evolving nature of Lucid documents, an unchanged Standard Import file may produce varying results over time.

curl 'https://api.lucid.co/documents'\
     --request 'POST'\
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>'\
     --header 'Lucid-Api-Version: 1'\
     --form 'file=@<location>/import.lucid;type=x-application/vnd.lucid.standardImport'\
     --form 'title=New Document'\
     --form 'product=lucidchart'\
     --form 'parent=1234'

Getting Started

Lucid import files use a .lucid extension and are at a base level a ZIP file which must contain a file named at document.json.

Optional components:

  • CSV files in the /data folder (refer to the Data section)
  • Images in the /images folder (refer to the Images section)

Filesize limitations:

  • .lucid ZIP file contents - 50MB
  • /data< folder contents - 1MB
  • /images folder contents - 50MB
  • document.json - 1MB
import.lucid
├── data
│   └── records.csv
├── images
│   └── logo.png
└── document.json

Example Import Files

Here are some .lucid ZIP file examples you can reference or use in your own projects.

Each link directs you to a folder in GitHub that contains a .lucid ZIP file, a folder containing the unzipped contents of the ZIP file, and a brief description of the example.

Example Import Usages

You can also find examples of how to use the Standard Import in the /standard-import folder in Lucid's repository of Sample Lucid REST Applications.

These examples solve some common use cases with the Standard Import. More information on how to use them "out-of-the-box" can be found in their respective README.md files.

Basic Document Format

The basic document format consists of a version tag, zero or more collections, and one or more pages, containing zero or more lines, shapes, groups, and/or layers.

All items within the document (pages, shapes, lines, layers, etc.) require a unique ID.

For information on the specific format of each JSON object, refer to each object's section of the documentation.

PropertyDescription
versionNumber
The specified version of the standard import to use.
Required
pagesArray[Pages]
An array of page objects that define what shapes, groups, lines, etc. will be present on the specified page. Note that a minimum of one page is required.
Required
collectionsArray[Collections]
An array of collection objects to draw data from.
Optional
extensionBootstrapDataBootstrap Data
Bootstrap data for a specific extension package.
Optional
{
    "version": 1,
    "collections": [
        {
            "id": "network",
            "dataSource": "Network.csv"
        }
    ],
    "pages": [
        {
            "id": "page1",
            "title": "Main Plan",
            "shapes": [...],
            "lines": [...],
            "groups": [...],
            "layers": [...]
        }
    ],
    "extensionBootstrapData": {
        "packageId": "74672098-cf36-492c-b8e6-2c4233549cd3",
        "extensionName": "sheets-adapter",
        "minimumVersion": "1.4.0",
        "data": {
            "a": 1,
            "b": 2
        }
    }
}

Bootstrap Data

Bootstrap data can be attached to the created document to be consumed by a specific Extension Package. See Bootstrap Data for documents created via API for usage.

PropertyDescription
packageIdString
Id of the extension package which will consume this data
extensionNameString
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.
minimumVersionString
Minimum version of the extension package which will consume this data.
dataMap[String, String]
Data to provide to the extension package.
{
    "packageId": "74672098-cf36-492c-b8e6-2c4233549cd3",
    "extensionName": "sheets-adapter",
    "minimumVersion": "1.4.0",
    "data": {
      "a": 1,
      "b": 2
    }
}