Overview

Example Request

                     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'
                  

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.

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

Getting Started

Example file structure

                     import.lucid
├── data
│   └── records.csv
├── images
│   └── logo.png
└── document.json
                  

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

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

Document Object

                     
{
    "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
        }
    }
}
                  

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.

Property	Description
version	Number The specified version of the standard import to use.
pages	Array[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.
collections	Array[Collections] An array of collection objects to draw data from.
extensionBootstrapData	Bootstrap Data Bootstrap data for a specific extension package.

Bootstrap Data

Bootstrap Data Resource

                     {
    "packageId": "74672098-cf36-492c-b8e6-2c4233549cd3",
    "extensionName": "sheets-adapter",
    "minimumVersion": "1.4.0",
    "data": {
      "a": 1,
      "b": 2
    }
}
                  

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.

Property	Description
packageId	String Id of the extension package which will consume this data
extensionName	String 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 Minimum version of the extension package which will consume this data
data	Map[String, String] Data to provide to the extension package

Reference

Types

Type	Example	Description
Boolean	true	An RFC7159 JSON boolean value.
String	"title"	An RFC7159 JSON string value.
Number	102 or 1.02E2	An RFC7159 JSON number value.
Integer	18567	An integer value formatted as an RFC7159 JSON number value.
Decimal	123.45	A decimal value formatted as an RFC7159 JSON number value.
Color	#32a834	A hexadecimal RGB string representing a color. See Web Colors for implementation details.
DateTime	2020-06-26T16:29:37Z	The date formatted as an RFC3339 timestamp string in the UTC time zone.
Timestamp	1605732868411	Number of milliseconds since the Unix epoch (January 1, 1970 in the UTC timezone).
UUID	110808fd-4553-4316-bccf-4f25ff59a532	A universally unique identifier (UUID) in the canonical textual representation format.
URI	https://lucid.app/lucidchart/328caaff-08d6-4461-bd52-bb2fbd556420/edit	A uniform resource identifier (URI) as defined in RFC3986.
Array	["in progress"] or [1, 2, 3]	An array of values of other primitive types.
Map	Map[String,String] or Map[String,Optional[String]]	A JSON object as defined in RFC7159.
ID	"block-1"	A string of one to thirty-six characters that are either alphanumeric or one of the following: -_.~

Actions

Actions allow a resource to execute an event when selected. The different types of actions are described below.

GoTo Document

Open another Lucid document

gotoDocument Action

                        {
    "type": "gotoDocument",
    "documentId": "110808fd-4553-4316-bccf-4f25ff59a532",
    "pageId": "page1",
    "newWindow": true
}
                     

Property	Description
documentId	UUID The Lucid document to open. Action will fail if the documentId does not exist or the user does not have access.
pageId	ID Page to open on the document. Actions will fail if the page is not valid.
newWindow	Boolean Open the document in the current window or a new window. The default behavior is to open the document in the same window.

GoTo Page

Switch to a different page on the current document.

gotoPage Action

                        {
    "type": "gotoPage",
    "pageId": "page1"
}
                     

Property	Description
pageId	ID Page to open on the current document. Actions will fail if the page is not valid.

Hide Layer

Hide one or more layers on the current document.

hideLayer Action

                        {
    "type": "hideLayer",
    "layers": [
        "layer1",
        "layer2"
    ]
}
                     

Property	Description
layers	Array[ID] Array of layer IDs to hide.

Show Layer

Show one or more layers on the current document.

showLayer Action

                        {
    "type": "showLayer",
    "layers": [
        "layer1",
        "layer2"
    ]
}
                     

Property	Description
layers	Array[ID] Array of layer IDs to show.

Toggle Layer

Toggle between hidden or shown for one or more layers on the current document.

toggleLayer Action

                        {
    "type": "toggleLayer",
    "layers": [
        "layer1",
        "layer2"
    ]
}
                     

Property	Description
layers	Array[ID] Array of layer IDs to toggle.

URL

Open a URL in the current window or a new window

url Action

                        {
    "type": "url",
    "url": "https://www.example.com",
    "newWindow": true
}
                     

Property	Description
url	String The URL to open.
newWindow	Boolean Open the URL in the current window or a new window. The default behavior is to open the document in the same window.

Bounding Box

The defined container on the canvas for an object.

Bounding Box Resource

                     {
    "x": 5,
    "y": 3,
    "w": 10,
    "h": 15,
    "rotation": 180
}
                  

Property	Description
x	Decimal Absolute x position on the document.
y	Decimal Absolute y position on the document.
w	Decimal Width of the bounding box.
h	Decimal Height of the bounding box.
rotation	Decimal Rotation of the bounding box in degrees. Rotation is clockwise and bounded between 0 and 360 degrees. Note that not all shapes are affected by rotation.

Data

Provide data to your document that can be referenced within pages and shapes.

Custom Data

Set of key-value pairs embedded within a shape.

Custom Data

                        {
    "key": "KeyOne",
    "value": "TestOne"
}
                     

Property	Description
key	String Name of the data key needed to access the data pair.
value	String Value to be returned when the key is requested.

Custom Page Data

Set of key-value pairs embedded within a page.

Custom Page Data

                        {
    "key": "KeyOne",
    "value": "TestOne",
    "global": true
}
                     

Property	Description
key	String Name of the data key needed to access the data pair.
value	String Value to be returned when the key is requested.
global	Boolean Add this pair to all shapes on the page. The default state is false.

Linked Data

Set of references to data provided in an external datasouce, usually a CSV file included with the provided .lucid standard import file.

Linked Data

                        {
    "collectionId": "CollectionOne",
    "key": "9"
}
                     

Property	Description
collectionId	ID Collection source id. Refer to the Data section for more information.
key	String Value of key field defined by the collection source.

Position

Position represents a location on the canvas. As x increases, the position moves to the right on the document canvas. As y increases, the position moves down the canvas.

Absolute Position

An exact location on the canvas.

Absolute Position Resource

                        {
    "x": 5.0,
    "y": 3.5
}
                     

Property	Description
x	Decimal Absolute x position on the document. As x increases, the position moves right on the canvas.
y	Decimal Absolute y position on the document. As y increases, the position moves down the canvas.

Relative Position

A position relative to the length or width of another line or shape. Expressed as a decimal percentage from 0 to 1. A value of 0 represents the start of the shape or line, with 1 representing the end. A value of 0.5 would be the middle. For a block, 0,0 represents the top-left corner and 1,1 represents the bottom-right.

Relative Position Resource

                        {
    "x": 0.25,
    "y": 0.75
}
                     

Property	Description
x	Decimal Relative x position along the line or shape.
y	Decimal Absolute y position along the line or shape.

Style

The combined background and border style of a shape

Style Resource

                        {
    "fill": {
      "type": "color",
      "color": "#ffffff"
    },
    "stroke": {
      "color": "#6f2131",
      "width": 3,
      "style": "solid"
    },
    "rounding": 10
}
                     

Property	Description
fill	Fill Fill of the shape. The default fill is a solid white background.
stroke	Stroke Stroke of the line or shape border. The default stroke is a solid 1px black line.
rounding	Integer Rounding value for the shape border, equal to double the pixel value of the corner radius.

Fill

Defines a shape's background. Can be a color or image.

Property	Description
type	String Type of content to fill the shape with. The Standard Import accepts "color" or "image" (see fill types below).

Color Fill

Fill with Color

                        {
    "type": "color",
    "color": "#800080"
}
                     

Fills the shape with a color.

Property	Description
color	Color Hexadecimal string representing a RGB or RGBA color value.

Image Fill

Fill with Image Ref

                        {
    "type": "image",
    "ref": "image.png",
    "imageScale": "fit"
}
                     

Fill with Image URL

                        {
    "type": "image",
    "url": "https://www.example.com/images/logo.png",
    "imageScale": "stretch"
}
                     

Fills the shape with an image. The image can be provided either within the images directory of the provided .lucid file (see Images), or as a url to an external image.

Property	Description
ref	String Refer to the Images section for how to reference images. Importing will fail if the file can not be found.
url	URL URL address pointing to an image. Importing will not check the validity of the image link.
imageScale	Image Scale Defines the way the image fills the shape. This field defaults to stretch if nothing is provided.

Image Scale Types

Value	Description
fit	Resizes the image to fit within a specified container while maintaining its aspect ratio, ensuring the entire image is visible with possible empty space around it.
fill	Resizes the image to completely fill a specified container, possibly cropping parts of the image to maintain the container's aspect ratio, ensuring the container is entirely covered by the image.
stretch	Resizes the image to fill a specified container without maintaining the original aspect ratio, potentially causing distortion if the aspect ratios differ.
original	Displays the image at its original size without resizing, showing only a portion if the container is smaller than the image.
tile	Repeats the image to fill the entire container both horizontally and vertically, creating a tiled pattern suitable for textures or backgrounds.

Stroke

Define the look of a line or border. May affect other aspects of certain shapes.

Stroke Resource

                        {
    "color": "#ffffff",
    "width": 10,
    "style": "solid"
}
                     

Property	Description
color	Color Hexadecimal string representing a RGB color to fill the line or border. The color defaults is black.
width	Integer Width of the line or border in pixels. The width defaults to 1px.
style	Stroke Style Style of the line or border. The stroke style defaults to solid.

Stroke Style

Defines the look of a drawn line. Affects the border and other aspects of certain shapes.

Value	Description	Image
solid	A solid line.
dashed	A dashed line.
dotted	A dotted line.

Text

Text to display on the shape or line. Formatting of the text can be by provided via raw HTML.

If a font size is not provided, all shapes will default to using auto-scaling font size.

Text Resource - No formatting

                        {
    "text": "Shape title"
}
                     

Property	Description
text	String Display text or Text and style formatting via the HTML style attribute.

Text Style

Text can be formatted via provding an HTML Style string. Any HTML style attributes not listed will be ignored. Some shapes may have a different default for certain fields based on their typical usage.

Text Resource - HTML Formatting

                        {
    "text": "<p style=\"font-size: 5pt;text-align: left;color: green\">A paragraph with HTML formatting.</p>"
}
                     

Value	Default
color	black
font-family	Liberation Sans
font-size	10pt
font-style	normal
font-weight	normal
text-align	center
text-decoration	none
vertical-align	center

Text Markup

HTML markup can be provided in text to further format customize its behavior:

Text Resource - Ordered List via HTML Markup

                        {
    "text": "<ol><li><b>bold</b></li><li><a href=\"https://www.example.com\">visit example.com</a></li></ol>"
}
                     

Markup	Behavior
<br>	Force a line break in the contained text.
<b></b>	Apply bold to the contained text.
<strong></strong>	Apply bold to the contained text.
<i></i>	Apply italic to the contained text.
<em></em>	Apply italic to the contained text.
<s></s>	Apply strike-through to the contained text.
<strike></strike>	Apply strike-through to the contained text.
<u></u>	Apply underline to the contained text.
<a></a>	Create an href within the contained text.
<ol></ol>	Create an ordered-list within the contained text.
<ul></ul>	Create an unordered-list within the contained text.
<li></li>	Create a list-item within an ordered or un-unordered list within the contained text.

Pages

A Page object represents all of the shapes, lines, groups, and layers contained on a single page of a given Lucid document.

Page Format

The format to define a page in JSON is shown below:

Page

                     {
    "id": "page1",
    "title": "Main Plan",
    "shapes": [ ... ],
    "lines": [ ... ],
    "groups": [ ... ],
    "layers": [ ... ],
    "customData": [ ... ]
}
                  

Property	Description
id	ID Identifier for a given page (must be unique).
title	String Page display title.
shapes	Array[Shape] An array of all shapes in the page.
dataBackedShapes	Array[Data Backed Shape] An array of all shapes in the page.
lines	Array[Line] An array of all lines in the page.
groups	Array[Group] An array of all groups in the page.
layers	Array[Layer] An array of all layers in the page.
customData	Array[Custom Page Data] See Custom Page Data for a description of it's purpose.

Shapes

Shapes are organized into libraries. Currently, JSON standard import supports shapes from the Standard Library, Shape Library, Container Library, Flowchart Library, and Lucidspark Library.

Common Properties

These properties are used on most or all shapes. Properties that are exclusive to a small set of shapes are defined near the shapes they're used on.

Property	Description
id	ID Identifier for a given shape (must be unique).
type	String The type of shape. An example of each shape is listed below.
boundingBox	Bounding Box The associated Bounding Box for the shape.
style	Style The style that will apply to the shape.
text	Text Text to display on the shape.
actions	Array[Action] An array of all actions linked to the shape.
customData	Array[Custom Data] An array of all custom data connected to the shape.
linkedData	Array[Linked Data] An array of all linked data connected to the shape.
opacity	Number A whole number between 0 (transparent) and 100 (completely opaque) inclusive, representing the opacity of the shape. Defaults to 100 when not provided.
note	Text Text to add as a note to the shape.

Standard Library

Default Block

Default Block

                     {
    "id": "shape1",
    "type": "rectangle",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Text Block

This shape does not accept the style property.

Text Block

                     {
    "id": "text1",
    "type": "text",
    "boundingBox": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Hotspot Block

This shape does not accept the text property.

Hotspot Block

                     {
    "id": "shape2",
    "type": "hotspot",
    "boundingBox": { ... },
    "style": { ... },
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Image Block

Property	Description
stroke	Stroke Define the look of the border.
image	ImageFill The image to fill the shape.

Image Block

                     {
    "id": "shape3",
    "type": "image",
    "boundingBox": { ... },
    "stroke": { ... },
    "image": { ... },
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Sticky Note

Sticky Note Block

                     {
    "id": "shape4",
    "type": "stickyNote",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Shape Library

Circle

Circle Block

                     {
    "id": "shape5",
    "type": "circle",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Cloud

Cloud Block

                     {
    "id": "shape6",
    "type": "cloud",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Cross

Property	Description
indent	Indent Determines the behavior of the indent on the shape.

Cross Block

                     {
    "id": "shape7",
    "type": "cross",
    "boundingBox": { ... },
    "style": { ... },
    "indent": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Indent

A set of values that determines the appearance of the shape. Values must be between 0 and 0.5.

Indent Resource

                     {
    "x": 0.25,
    "y": 0.25
}
                  

Property	Description
x	Decimal A value that determines the size of the horizontal indent.
y	Decimal A value that determines the size of the vertical indent.

Diamond

Diamond Block

                     {
    "id": "shape8",
    "type": "diamond",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Double Arrow

Double Arrow Block

                     {
    "id": "shape9",
    "type": "doubleArrow",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Flexible Polygon

Property	Description
vertices	Array[RelativePosition] An array of positions. Must have between 3 and 100 vertices inclusive. Defines the border of the shape relative to the bounding box.

Flexible Polygon Block

                     {
    "id": "shape10",
    "type": "flexiblePolygon",
    "boundingBox": { ... },
    "style": { ... },
    "vertices": [ ... ],
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Hexagon

Hexagon Block

                     {
    "id": "shape11",
    "type": "hexagon",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Isosceles Triangle

Isosceles Triangle Block

                     {
    "id": "shape12",
    "type": "isoscelesTriangle",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Octagon

Octagon Block

                     {
    "id": "shape13",
    "type": "octagon",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Pentagon

Pentagon Block

                     {
    "id": "shape14",
    "type": "pentagon",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Poly-Star

Property	Description
shape	Poly-Star Shape Defines the shape of the star.

Poly-Star Block

                     {
    "id": "shape15",
    "type": "polyStar",
    "boundingBox": { ... },
    "style": { ... },
    "shape": { ... },
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Poly-Star Shape

Poly-Star Shape Resource

                     {
    "numPoints": 5,
    "innerRadius": 0.5
}
                  

Property	Description
numPoints	Number The number of points on the star. Must be between 3 and 25.
innerRadius	Number The fraction of the total shape from the center of the star to each inner point. Must be between 0 and 1.

Rectangle

Rectangle Block

                     {
    "id": "shape16",
    "type": "rectangle",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Right Triangle

Right Triangle Block

                     {
    "id": "shape17",
    "type": "rightTriangle",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Single Arrow

Property	Description
orientation	Single Arrow Orientation Determines the direction of the arrow. Defaults to "right".

Single Arrow Block

                     {
    "id": "shape18",
    "type": "singleArrow",
    "boundingBox": { ... },
    "orientation": "right",
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Single Arrow Orientation

Determines the direction of the arrow.

Value	Description
right	A rightward-facing arrow.
left	A leftward-facing arrow.
up	An upward-facing arrow.
down	A downward-facing arrow.

Container Library

Brace Container

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Brace Container Block

                     {
    "id": "shape19",
    "type": "braceContainer",
    "boundingBox": { ... },
    "style": { ... },
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Bracket Container

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Bracket Container Block

                     {
    "id": "shape20",
    "type": "bracketContainer",
    "boundingBox": { ... },
    "style": { ... },
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Circle Container

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Circle Container Block

                     {
    "id": "shape21",
    "type": "circleContainer",
    "boundingBox": { ... },
    "style": { ... },
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Diamond Container

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Diamond Container Block

                     {
    "id": "shape22",
    "type": "diamondContainer",
    "boundingBox": { ... },
    "style": { ... },
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Pill Container

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Pill Container Block

                     {
    "id": "shape23",
    "type": "pillContainer",
    "boundingBox": { ... },
    "style": { ... },
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Rectangle Container

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Rectangle Container Block

                     {
    "id": "shape24",
    "type": "rectangleContainer",
    "boundingBox": { ... },
    "style": { ... },
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Rounded Rectangle Container

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Rounded Rectangle Container Block

                     {
    "id": "shape25",
    "type": "roundedRectangleContainer",
    "boundingBox": { ... },
    "style": { ... },
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Swim Lanes

This shape's bounding box is incompatible with the rotation property.

Property	Description
vertical	Boolean Determines orientation of the swim lanes.
titleBar	Title Bar Defines the behavior of the title bar of the swim lane.
lanes	Array[Swim Lane] An array of swim lanes.
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Swim Lanes Block

                     {
    "id": "shape26",
    "type": "swimLanes",
    "boundingBox": { ... },
    "style": { ... },
    "vertical": false,
    "titleBar": { ... },
    "lanes": [ ... ],
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Title Bar

Title Bar Resource

                     {
    "height": 50,
    "verticalText": true
}
                  

Property	Description
height	Number The height of the title bar.
verticalText	Boolean Determines the orientation of the title text.

Swim Lane

Swim Lane Resource

                     {
    "title": "Swim lane 1",
    "width": 300,
    "headerFill": "#635DFF",
    "laneFill": "#F2F3F5"
}
                  

Property	Description
title	String The title text of a swim lane.
width	Boolean The width of a swim lane. All individual lane widths must add up to total swim lanes width or height, depending on orientation.
headerFill	Color Hexadecimal string representing a RGB or RGBA color value for the header fill.
laneFill	Color Hexadecimal string representing a RGB or RGBA color value for the lane fill.

Flowchart Library

Brace Note

Property	Description
rightFacing	Boolean Determines the orientation of the brace.
braceWidth	Number The width of the brace.

Brace Note Block

                     {
    "id": "shape27",
    "type": "braceNote",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Note",
    "rightFacing": false,
    "braceWidth": 60,
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Connector

Connector Block

                     {
    "id": "shape28",
    "type": "connector",
    "boundingBox": { ... },
    "style": { ... },
    "text": "A",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Database

Database Block

                     {
    "id": "shape29",
    "type": "database",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Database",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Data

Data Block

                     {
    "id": "shape29",
    "type": "data",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Data",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Decision

Decision Block

                     {
    "id": "shape30",
    "type": "decision",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Decision",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Delay

Delay Block

                     {
    "id": "shape31",
    "type": "delay",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Delay",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Direct Access Storage

Direct Access Storage Block

                     {
    "id": "shape32",
    "type": "directAccessStorage",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Hard disk",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Display

Display Block

                     {
    "id": "shape33",
    "type": "display",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Display",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Document

Document Block

                     {
    "id": "shape34",
    "type": "document",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Document",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Internal Storage

Internal Storage Block

                     {
    "id": "shape35",
    "type": "internalStorage",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Internal storage",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Manual Input

Manual Input Block

                     {
    "id": "shape36",
    "type": "manualInput",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Manual input",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Manual Operation

Manual Operation Block

                     {
    "id": "shape37",
    "type": "manualOperation",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Manual operation",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Merge

Merge Block

                     {
    "id": "shape38",
    "type": "merge",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Merge",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Multiple Documents

Multiple Documents Block

                     {
    "id": "shape39",
    "type": "multipleDocuments",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Multiple documents",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Note

Note Block

                     {
    "id": "shape40",
    "type": "note",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Note",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Off-Page Link

Off-Page Link Block

                     {
    "id": "shape41",
    "type": "offPageLink",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Off-page link",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Or

This shape does not accept the text property.

Or Block

                     {
    "id": "shape42",
    "type": "or",
    "boundingBox": { ... },
    "style": { ... },
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Paper Tape

Paper Tape Block

                     {
    "id": "shape43",
    "type": "paperTape",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Paper tape",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Predefined Process

Property	Description
sideWidth	Number The fraction of the block taken up by each side section. Must be between 0 and 0.33.

Predefined Process Block

                     {
    "id": "shape44",
    "type": "predefinedProcess",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Predefined process",
    "sideWidth": 0.1,
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Preparation

Preparation Block

                     {
    "id": "shape45",
    "type": "preparation",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Preparation",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Process

Process Block

                     {
    "id": "shape46",
    "type": "process",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Process",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Stored Data

Stored Data Block

                     {
    "id": "shape47",
    "type": "storedData",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Stored data",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Summing Junction

This shape does not accept the text property.

Summing Junction Block

                     {
    "id": "shape48",
    "type": "summingJunction",
    "boundingBox": { ... },
    "style": { ... },
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Swim Lanes

See Swim Lanes in the Container Library

Terminator

Terminator Block

                     {
    "id": "shape49",
    "type": "terminator",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Terminator",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Lucidspark Library

Freehand Drawing

Property	Description
style	Freehand Drawing Style A line style specific to freehand drawings.
points	Array[AbsolutePosition] An array of positions that define the shape of the freehand drawing.
offset	AbsolutePosition The position of the freehand drawing. All points are relative to the offset.

Freehand Drawing Block

                     {
    "id": "shape50",
    "type": "freehandDrawing",
    "style": { ... },
    "points": [ ... ],
    "offset": { ... },
    "note": "Test Note"
}
                  

Freehand Drawing Style

Property	Description
width	Number The thickness of the line. Must be between 0 and 100.
color	Color Hexadecimal string representing a RGB or RGBA color value of the line.

Spark Callout Square

Spark Callout Square Block

                     {
    "id": "shape51",
    "type": "sparkCalloutSquare",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Spark Container

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Spark Container Block

                     {
    "id": "shape52",
    "type": "sparkContainer",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Text",
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Spark Frame

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Spark Frame Block

                     {
    "id": "shape53",
    "type": "sparkFrame",
    "boundingBox": { ... },
    "style": { ... },
    "title": "Frame 1",
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

BPMN 2.0 Library

Activity

This shape has unique properties that give it a variety of appearances. See additional examples

Property	Description
activityType	Activity Type The type of activity.
taskType	Task Type Adds a task icon to the block. Defaults to none.
activityMarker1	Activity Marker Adds an activity marker to the block. Defaults to none.
activityMarker2	Activity Marker Adds an activity marker to the block. Defaults to none.

Activity Block

                     {
    "id": "shape54",
    "type": "bpmnActivity",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Task",
    "activityType": "task",
    "taskType"  "none",
    "activityMarker1": "none",
    "activityMarker2": "none",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Activity Type

Value
task
transaction
eventSubProcess
callActivity

Task Type

Value
none
send
receive
user
manual
businessRule
service
script

Activity Marker

Value
none
subProcess
loop
parallelMI
sequentialMI
adHoc
compensation

Black Box Pool

Black Box Pool Block

                     {
    "id": "shape55",
    "type": "bpmnBlackBoxPool",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Pool (Black Box)",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Choreography

This shape has unique properties that give it a variety of appearances. See additional examples

Property	Description
choreographyType	Choreography Type The type of choreography.
participants	Array[Participant] A list of non-initiating participants. There must be between 1 and 100 participants.
name	String The name of the initiator.
taskName	String The name of the task.
initiatingMessage	Boolean Adds an initiating message icon to the block. Defaults to false.
responseMessage	Boolean Adds a response message icon to the block. Defaults to false.

Choreography Block

                     {
    "id": "shape56",
    "type": "bpmnChoreography",
    "boundingBox": { ... },
    "style": { ... },
    "choreographyType": "task",
    "participants": [ ... ],
    "name": "Participant A",
    "taskName": "Task",
    "initiatingMessage": false,
    "responseMessage": false,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Choreography Type

Value
task
subchoreography
call

Participant

Participant Resource

                     {
    "text": "Participant",
    "multipleParticipants": false
}
                  

Property	Description
text	String The text of a participant.
multipleParticipants	Boolean Adds a multiple participants icon to the participant.

Conversation

This shape has unique properties that give it a variety of appearances. See additional examples

Property	Description
isCall	Boolean Makes the block into a call block. Defaults to false.
isSubConversation	Boolean Makes the block into a sub-conversation block. Defaults to false.

Conversation Block

                     {
    "id": "shape57",
    "type": "bpmnConversation",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Conversation",
    "isCall": false,
    "isSubConversation": false,
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Data Object

This shape has unique properties that give it a variety of appearances. See additional examples

Property	Description
dataType	Data Type The data type of the shape. Defaults to none.

Data Object Block

                     {
    "id": "shape58",
    "type": "bpmnDataObject",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Data",
    "dataType": "none",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Data Type

Value
none
collection
input
output

Data Store

Data Store Block

                     {
    "id": "shape59",
    "type": "bpmnDataStore",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Data Store",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Event

This shape has unique properties that give it a variety of appearances. See additional examples

Property	Description
eventGroup	Event Group The event group of the shape.
eventType	Event Type The event type of the shape. Defaults to none.
nonInterrupting	Boolean Determines the appearance of the shape. Defaults to false.
throwing	Boolean Determines the appearance of the shape. Defaults to false.

Event Block

                     {
    "id": "shape60",
    "type": "bpmnEvent",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Event",
    "eventGroup": "start",
    "eventType": "none",
    "nonInterrupting": false,
    "throwing": false,
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Event Group

Value
start
intermediate
end

Event Type

Value
none
message
timer
escalation
conditional
link
error
cancel
compensation
signal
multiple
parallelMultiple
terminate

Gateway

This shape has unique properties that give it a variety of appearances. See additional examples

Property	Description
gatewayType	Gateway Type The gateway type of the shape. Defaults to none.

Gateway Block

                     {
    "id": "shape61",
    "type": "bpmnGateway",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Gateway",
    "gatewayType": "none",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Gateway Type

Value
none
exclusive
eventBased
parallel
inclusive
exclusiveEventBased
complex
parallelEventBased

Group

This shape's bounding box is incompatible with the rotation property.

Property	Description
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Group Block

                     {
    "id": "shape62",
    "type": "bpmnGroup",
    "boundingBox": { ... },
    "style": { ... },
    "magnetize": true,
    "text": "Group",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Pool

This shape's bounding box is incompatible with the rotation property.

Property	Description
title	String The title text of a pool.
lanes	Array[Pool Lane] An array of pool lanes. There must be between 1 and 50 lanes.
vertical	Boolean Determines orientation of the pool. Defaults to true.
verticalLaneText	Boolean Determines orientation of the pool lane titles. Defaults to false.
magnetize	Boolean Determines whether shapes within the container move with the container. Defaults to true.

Pool Block

                     {
    "id": "shape63",
    "type": "bpmnPool",
    "boundingBox": { ... },
    "style": { ... },
    "title": "Pool",
    "lanes": [ ... ],
    "vertical": false,
    "verticalLaneText": true,
    "magnetize": true,
    "actions": [ ... ],
    "customData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Pool Lane

Pool Lane Resource

                     {
    "title": "Lane",
    "width": 300,
    "laneFill": "#0000"
}
                  

Property	Description
title	String The title text of a pool lane.
width	Boolean The width of a pool lane. All individual lane widths must add up to total pool width or height, depending on orientation.
laneFill	Color Hexadecimal string representing a RGB or RGBA color value for the lane fill.

Text Annotation

Text Annotation Block

                     {
    "id": "shape64",
    "type": "bpmnTextAnnotation",
    "boundingBox": { ... },
    "style": { ... },
    "text": "Annotation",
    "actions": [ ... ],
    "customData": [ ... ],
    "linkedData": [ ... ],
    "opacity": 100,
    "note": "Test Note"
}
                  

Data Backed Shapes

Data backed shapes represent objects on a page that are defined and generated from a provided dataset. Each data backed shape object includes a type that defines what object it is and how it will be parsed and must be linked to a set of data from which the objects will be generated.

Common Properties

These properties are used all data backed shapes. Additional configuration properties for data backed shape are listed with the description of the shape.

Property	Description
id	ID Identifier for a given data backed shape (must be unique).
type	String The type of data backed shape. An example for each data backed shape is list below.

Org Charts

An Org Chart is a data backed shape that is used to represent the organizational structure of a group of people.

Important: Org charts are limited to a total size for 4000 users summed across all pages of the document.

Org Chart Format

Org Chart Format

                     {
    "id": "orgChart1",
    "type": "orgChart",
    "position": {
        "x": 150,
        "y": 150
    },
    "collectionId": "org-chart-data",
    "idField": "Employee ID",
    "foreignKeyField": "Supervisor ID",
    "nameField": "Full Name",
    "roleField": "Role",
    "imageUrlField": "Image",
    "extraFields": ["Email", "Cell Phone", "Building"]
}
                  

Property	Description
position	AbsolutePosition The absolute point that the top left corner of the generated content will be placed. Note that the size of the object is dependent on the size and layout of the data provided
collectionId	ID The id of the provided collection that the org chart will draw data from.
idField	String Defines the name of the field in the collection that represents the primary key or ID of the identities in the collection. Primary keys should be unique.
foreignKeyField	String Defines the name of the field in the collection that references the value of the idField of another identity in the collection.
nameField	String Defines the name of the field that contains the name of the identity in the collection.
roleField	String Defines the name of the field that contains the role of the identity in the collection. If included, the role will be displayed on the org chart by default.
imageUrlField	String Defines the name of the field that contains the URL pointing to an image of the identity in the collection.
extraFields	Array[String] An array of names of other fields in the collection that should be included on the org chart. By default, these fields will not appear on the org chart directly but can be accessed in the data panel for the org chart to define if they should be displayed.

Lines

Line Format

The format to create a line on the Lucid document between two defined points.

Line Format

                     {
    "id": "line1",
    "lineType": "elbow",
    "endpoint1": {
        "type": "shapeEndpoint",
        "style": "none",
        "shapeId": "block3",
        "position": { "x": 1, "y": 1 }
    },
    "endpoint2": {
        "type": "lineEndpoint",
        "style": "arrow",
        "lineId": "line2",
        "position": 0.5
    },
    "stroke": {
        "color": "#000000",
        "width": 1,
        "style": "solid"
    },
    "text": [
        {
            "text": "test",
            "position": 0.5,
            "side": "middle"
        }
    ],
    "customData": [
        {
            "key": "TestKey",
            "value": "TestValue"
        }
    ],
    "linkedData": [
        {
            "collectionId": "network",
            "key": "9"
        }
    ]
}
                  

Property	Description
id	ID Identifier for a given line (must be unique).
lineType	LineType Type that specifies how the line does, or does not, curve.
endpoint1	Endpoint The first of two endpoints that specifies how and where the line will end.
endpoint2	Endpoint The second of two endpoints that specifies how and where the line will end.
stroke	Stroke Stroke object that defines the look of the line.
text	Array[LineText] An array of line text objects. Multiple text objects can be on the same line.
customData	Array[CustomDatum] An array of Custom Data objects.
linkedData	Array[LinkedDatum] An array of Linked Data objects.

Line Type

Defines the styling of a line's curvature.

Value	Description	Image
straight	A line with no curves.
elbow	A line with elbow (right-angle) curves.
curved	A line with smooth curves.

Endpoint

Defines where a line should end and the styling of the endpoint.

Property	Description
type	EndpointType Type of endpoint to create.
style	EndpointStyle Style type which determines how the endpoint will appear

Note: These common endpoint fields are used on each specific type of endpoint.

Endpoint Type

The type of a given endpoint.

Value	Description
lineEndpoint	An endpoint that attaches to another line (see Line Endpoints for details).
shapeEndpoint	An endpoint that attaches to a shape (see Shape Endpoints for details).
positionEndpoint	An endpoint that is positioned somewhere on the canvas independent of a shape or line (see Position Endpoints for details).

Line Endpoint

An endpoint that attaches to another line.

Line Endpoint

                     {
    "type": "lineEndpoint",
    "style": "arrow",
    "lineId": "line2",
    "position": 0.5
}
                  

Property	Description
Base Endpoint Fields	Endpoint fields that are common to each type of endpoint (see Endpoints for details).
lineId	ID The id for which line to attach the endpoint to.
position	Double A relative position specifying where on the target line this endpoint should attach (must be between 0.0-1.0 inclusive).

Shape Endpoint

An endpoint that attaches to a shape.

Shape Endpoint

                     {
    "type": "shapeEndpoint",
    "style": "none",
    "shapeId": "block1",
    "position": { "x": 1, "y": 0.5 }
}
                  

Property	Description
Base Endpoint Fields	Endpoint fields that are common to each type of endpoint (see Endpoints for details).
shapeId	ID The id for which shape to attach the endpoint to.
position	RelativePosition A relative position specifying where on the target shape this endpoint should attach.

Position Endpoint

An endpoint that is positioned somewhere on the canvas independent of a shape or line.

Position Endpoint

                     {
    "type": "positionEndpoint",
    "style": "arrow",
    "position": { "x": 120, "y": -100 }
}
                  

Property	Description
Base Endpoint Fields	Endpoint fields that are common to each type of endpoint (see Endpoints for details).
position	AbsolutePosition An absolute position specifying where on the canvas this endpoint should land.

Endpoint Style

How to style the endpoint.

Value	Description
none
aggregation
arrow
hollowArrow
openArrow
async1
async2
closedSquare
openSquare
bpmnConditional
bpmnDefault
closedCircle
openCircle
composition
exactlyOne
generalization
many
nesting
one
oneOrMore
zeroOrMore
zeroOrOne

Line Text

Defines what text should be displayed on the line and how it's styled.

LineText

                     {
    "text": "test",
    "position": 0.5,
    "side": "middle"
}
                  

Property	Description
text	Text The text to display on the line.
position	Double A relative position specifying where on the target line this text should appear (must be between 0.0-1.0 inclusive).
side	LineSide A type that specifies how the text should be displayed on the line

Line Side

The side of a line on which to position an object.

Value	Description
top	The top of the line.
middle	The middle of the line, with the line passing behind the object.
bottom	The bottom of the line.

Groups

Groups are collections of items, such as shapes, lines, or other groups. Groups cannot contain layers. Groups allow you to combine multiple items into a single, manageable unit. When you group items, you can move, resize, or format them collectively, treating the group as a single object. This is particularly useful when you want to maintain the relative positions of multiple items or when you want to apply formatting or actions to a set of items simultaneously.

Group Format

Group

                     {
  "id": "group1",
  "items": [ ... ],
  "note": "Test Note",
  "customData": [ ... ],
  "linkedData": [ ... ]
}
                  

Property	Description
id	ID Identifier for a given group (must be unique).
items	Array [ID] An array of IDs of all Shapes, Lines, and Groups in the group.
note	Text Text to add as a note to the group.
customData	Array [Custom Data] An array of custom data in the group. See Custom Data for a description of its purpose.
linkedData	Array [Linked Data] An array of linked data in the group. See Linked Data for a description of its purpose.

Layers

Layers are collections of items, such as shapes, lines, or groups. Layers cannot contain other layers. They are similar to Groups but are more versatile. Layers are used to organize and manage the visual hierarchy of elements within a diagram. You can assign shapes, lines, and groups to different layers and then manipulate the visibility and order of those layers.

Layer Format

Layer

                     {
  "id": "layer1",
  "title": "New Layer",
  "items": [ ... ],
  "note": "Test Note",
  "customData": [ ... ],
  "linkedData": [ ... ]
}
                  

Property	Description
id	ID Identifier for a given layer (must be unique).
title	String Title of the layer.
items	Array [ID] An array of IDs of all Shapes, Lines, and Groups in the layer.
note	Text Text to add as a note to the layer.
customData	Array [Custom Data] An array of custom data in the layer. See Custom Data for a description of its purpose.
linkedData	Array [Linked Data] An array of linked data in the layer. See Linked Data for a description of its purpose.

Images

Example file structure

                     import.lucid
├── images
│   ├── my-image.png
│   └── gifs
│       └── my-gif.gif
└── document.json
                  

Images included in the images directory are uploaded to Lucid and available for referencing in the JSON.

Images are referenced without including directories. To use the file my-gif.gif shown in the example file structure, the reference would be defined as "ref": "my-gif.gif", not "ref": "gifs/my-gif.gif".

Important: The images directory is not allowed to exceed 50MB.

Supported Media

Example usage

                     ...
    "fill": {
        "type": "image",
        "ref": "my-gif.gif"
    }
...
                  

Extension	Description
.jpeg / .jpg	Joint Photographic Experts Group
.png	Portable Network Graphics
.gif	Graphics Interchange Format
.bmp	Windows Bitmap
.tiff	Tagged Image File Format

Data

Example file structure

                     import.lucid
├── data
│   ├── sales-performance.csv
│   └── templates
│       └── email-flow.csv
└── document.json
                  

To import a data set from Google Sheets, Excel, or CSV with your document, include the CSV export of the file in the data directory.

To reference it from the JSON, refer to Linked Data and Collections.

Data files are referenced without including directories. To use the file email-flow.csv shown in the example file structure, the collection data source would be defined as "dataSource": "email-flow.csv", not "dataSource": "templates/email-flow.csv".

Important: The data directory is not allowed to exceed 1MB.

Collections

Collection

                     {
  "id": "sales-performance",
  "dataSource": "sales-performance.csv"
}
                  

Property	Description
id	ID Identifier for a collection that linked data objects will reference.
dataSource	String File reference.

Supported Media

Example usage

                     ...
    "collections": [
        {
            "id": "sales-performance",
            "dataSource": "sales-performance.csv"
        },
        {
            "id": "email-flow",
            "dataSource": "email-flow.csv"
        }
    ]
...
    "linkedData": [
        {
            "collectionId": "email-flow",
            "key": 1
        }
    ]
...
                  

Extension	Description
.txt	Text file
.csv	Comma-Separated Values

Troubleshooting

Common File Errors

Incorrect .lucid file structure

                     import.lucid
└── folder
    ├── document.json
    └── data
        └── email-flow.csv

                  

Correct .lucid file structure

                     import.lucid
├── document.json
└── data
    └── email-flow.csv
                  

Error Code	Error Message	Possible Solution
invalid_file	Standard import file entry does not exist	This error commonly occurs when the parent folder containing the standard import files/folders (document.json, data, images) is compressed into a zip archive instead of selecting the individual files/folders and compressing them as a group (refer to the example file structure on the right to see both the incorrect and the correct way to zip the files).
invalid_file	error.expected.validenumvalue	This error commonly occurs when an invalid enum value is used on fields such as Stroke.style, Line.lineType, Line.text.side, Style.fill.type, and Style.fill.imageScale.
invalid_file	error.expected.jsnumber	This error commonly occurs when a number is expected during JSON parsing, but something else is found instead. For example, this can happen when using the position property of the line endpoint object. For a shapeEndpoint, the position property expects a RelativePosition object. However, a lineEndpoint just expects a number for the position property. When an object is used instead of a number, this error is thrown.

Common Request Errors

Example Request

                     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'
                  

Response Code	Error Message	Possible Solution
415: Unsupported Media Type	invalidImportType: Importing the provided file type is not supported	This error commonly occurs when the type of the file in the form data is not set correctly. Refer to the Import Document endpoint or to the code to the right for an example in cURL of how to set the file type in the form data being sent. For the Standard Import, this file type must be set to x-application/vnd.lucid.standardImport
400: Bad Request	badRequest: You must set the product field to either 'lucidchart' or 'lucidspark' when using the Lucid Standard Import	If the product field is correctly being set in your request (as explained in the Overview), then this error commonly happens when the data is not being sent as form data. This causes the request to fail even if all the data independently is correct. Refer to the Import Document endpoint or to the code to the right for an example in cURL of how to send the request data as form data. Additionally, you may refer to the documentation for your specific API platform, such as Postman.