NAV

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 through our feature feedback form.

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. Solid Stroke
dashed A dashed line. Dashed Stroke
dotted A dotted line. Dotted Stroke

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

Default Block

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

Text Block

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

Hotspot Block

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

Image Block

Sticky Note

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

Sticky Note Block

Shape Library

Circle

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

Circle Block

Cloud

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

Cloud Block

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

Cross Block

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

Diamond Block

Double Arrow

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

Double Arrow Block

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

Flexible Polygon Block

Hexagon

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

Hexagon Block

Isosceles Triangle

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

Isosceles Triangle Block

Octagon

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

Octagon Block

Pentagon

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

Pentagon Block

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

PolyStar Block

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

Default Block

Right Triangle

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

Right Triangle Block

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 Block

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

Braces Container

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

Bracket Container

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

Circle Container

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

Diamond Container

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

Pill Container

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

Rectangle Container

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

Rounded Rectangle Container

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

Advances Swimlane Container

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

Brace Note Block

Connector

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

Connector Block

Database

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

Database Block

Data

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

Data Block

Decision

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

Decision Block

Delay

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

Delay Block

Direct Access Storage

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

Direct Access Storage Block

Display

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

Display Block

Document

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

Document Block

Internal Storage

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

Internal Storage Block

Manual Input

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

Manual Input Block

Manual Operation

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

Manual Operation Block

Merge

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

Merge Block

Multiple Documents

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

Multiple Documents Block

Note

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

Note Block

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

Off-Page Link Block

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

Or Block

Paper Tape

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

Paper Tape Block

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

Predefined Process Block

Preparation

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

Preparation Block

Process

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

Process Block

Stored Data

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

Stored Data Block

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

Summing Junction Block

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

Terminator Block

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 Block

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 Callout Square Block

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 Container Block

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

Spark Frame Block

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

BPMN Activity Block

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

BPMN Black Box Pool Block

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

BPMN Choreography Block

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

BPMN Conversation Block

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

BPMN Data Object Block

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

BPMN Data Store Block

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

BPMN Event Block

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

BPMN Gateway Block

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

BPMN Group Block

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

BPMN Pool Block

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

BPMN Text Annotation Block

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. Straight Line
elbow A line with elbow (right-angle) curves. Elbow Line
curved A line with smooth curves. Curved Line

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 None
aggregation Aggregation
arrow Arrow
hollowArrow Hollow Arrow
openArrow Open Arrow
async1 Async 1
async2 Async 2
closedSquare Closed Square
openSquare Open Square
bpmnConditional BPMN Conditional
bpmnDefault BPMN Default
closedCircle Closed Circle
openCircle Open Circle
composition Composition
exactlyOne Exactly One
generalization Generalization
many Many
nesting Nesting
one One
oneOrMore One Or More
zeroOrMore Zero Or More
zeroOrOne Zero Or One

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.