Overview

Lucid's API allows developers to gain access to document, user or dynamic data information with a user's permission.

A wiki package could gain access to live-updated images of documents to include in its pages. Or a Facebook app could make it easy for a Lucid user to quickly invite a group of Facebook friends to join a document as a collaborator.

Explore below to see a wide variety of APIs that are available and details for how they work.

Getting Started

Headers

All endpoints (unless otherwise specified) require two specific headers:

Authorization: Bearer <OAuth 2.0 Access Token>

Endpoints require a valid OAuth2 token to be included in the Authorization header.

Lucid-Api-Version: <version>

The version corresponds to the version of the resource being accessed. Resources are classified as documents, users, datasets, etc. Each individual resource section will state the currently supported versions.

Types

Type Example Description
Boolean true An RFC7159 JSON boolean value.
String "title" An RFC7159 JSON string 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.
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.
Product lucidchart or lucidspark A Lucid product.

Status Codes and Errors

Lucid APIs use standard HTTP codes to indicate the result of the request.

Successful Responses

200 Ok The request completed successfully.
201 Created The request succeeded and the resource was created.
204 No Content Completed successfully, but returned no response body. Often used with DELETE endpoints.

Errors

Example Error Objects

{
    "code": "unknownOperation",
    "message": "The requested operation is unrecognized or not supported for this resource"
}

{
    "code": "invalidExportType",
    "message": "The requested export type is not supported",
    "details": {
      "requested": "application/json",
      "supported": ["image/jpeg", "image/png"]
    },
    "requestId": "47CA40AE3BD1A335"
}
HTTP Status Error Code Description
400 Bad Request unknownOperation The requested operation is unrecognized or not supported for this resource.
400 Bad Request badRequest Bad or malformed request
403 Unauthorized accessForbidden Access to this resource is forbidden
404 Not Found notFound Resource not found
406 Not Acceptable invalidExportType The requested export type is not supported
409 Conflict alreadyExists Entity already exists
415 Unsupported Media Type invalidImportType Importing the provided file type is not supported
500 Internal Server Error internalServerError An unknown error occurred.
503 Service Unavailable The service is down for maintenance.

OAuth 2.0 Authentication

Using OAuth 2.0

In order to use any of the Lucid APIs, an app must have permission from the user to access their data. This permission can be granted with an OAuth2 access token. Details of the OAuth 2.0 authorization process can be found at https://oauth.net/2/.

Limitations

When accessing Lucid APIs using OAuth 2.0, the following limitations apply:

  • You must be a team admin in your Lucid account in order to obtain the client ID and secret as described below.
  • Only users in your account can use the app with your client ID and secret. If you would like to develop an app that all Lucid users can use, please contact us.
  • Authorization must happen in the browser, because a user must give consent for the client to access their information. For this reason, the authorization request cannot be made from Postman, curl, or some other HTTP client.

App registration

Note: Registering a new application requires Team Admin permissions for the Lucid account.

To set up an app to use OAuth 2.0, perform the following steps:

  1. Obtain an OAuth 2.0 client ID and client secret from the account's Lucid team administration page.
  2. Register at least one redirect URI on that page. Lucid will redirect the user to this location once they have granted access. This should be a URL that the app controls. Lucid will append the authorization code to the URL in the code query parameter.
Test redirect URI

As a service, Lucid provides a redirect uri that can be used to allow the user to copy the authorization code to the clipboard.

To use it, register the redirect URI:

https://lucid.app/oauth2/clients/{client id}/redirect

When this redirect URI is used and a user grants access to the app, Lucid will redirect the user to a page on our site where they can view and copy the authorization code.

Obtaining an access token

Example URL: https://lucid.app/oauth2/authorize?client_id=rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf&redirect_uri=https://lucid.app/oauth2/clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect&scope=lucidchart.document.content

# Example request made using json body
curl https://api.lucid.co/oauth2/token
     --request POST
     --header "Content-Type: application/json"
     --data-binary '{
         "code":"vtpL4oKCv3LSJ8C78FohTYN9uJUUkkZ4mQDYBucl094r",
         "client_id":"ovpI4yfVXc-BqqL0-prHDd3YAyF6bp-lWBpZicVo",
         "client_secret":"TPKtc0SyuAbyleYq8MMtpxZMD7y4WFpPuf5a",
         "grant_type":"authorization_code"
         }'
# Example request made using form-data
curl https://api.lucid.co/oauth2/token
     --data code=vtpL4oKCv3LSJ8C78FohTYN9uJUUkkZ4mQDYBucl094r
     --data client_id=ovpI4yfVXc-BqqL0-prHDd3YAyF6bp-lWBpZicVo
     --data client_secret=TPKtc0SyuAbyleYq8MMtpxZMD7y4WFpPuf5a
     --data grant_type=authorization_code

When a user wants to allow app to connect to their Lucid account, use the following flow:

  1. Direct the user to open https://lucid.app/oauth2/authorize in a browser with the following URL query parameters appended in order to grant access:
client_id The client ID obtained during App registration
redirect_uri One of the redirect URIs registered for the app during App registration
scope The scopes the app is requesting access to
state Can be any value. Will be included in the redirect back to the app once authorization is completed

If the user has not yet logged into Lucid, the redirect will first take them to a login page, and then display the grant access page.

  1. Once the user grants access, they will be redirected to the URI specified. The code query parameter will contain a short-lived authorization code that will be used to obtain an access token.
  2. Make a POST request to https://api.lucid.co/oauth2/token with a Create Access Token body.
  3. The response will be an OAuth2 Token.

Using the access token

With the access token, an app can make requests to Lucid APIs and get access to the user's data. To make an authenticated request, include an Authorization header with the access token as a "Bearer" token. The header value should look like this: Authorization: Bearer <access token>

Note: Access can be revoked by the user or team admin at any time if they decide that they no longer want the app to have access to the user's Lucid data.

Refreshing the access token

# Example request
curl https://api.lucid.co/oauth2/refreshToken
     --request POST
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>'
     --header 'Content-Type: application/json'
     --data-raw '{
         "refresh_token": "oauth2-AVU=-yPcwtzLkusIEnT7D9slQH4g8Ur0MdpUmpT0Z6BSMf6lmesRpTTSBGNniK",
         "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_",
         "client_secret": "D-SkY5dE9m7hQApMwc9DV0iCzSRVV62MnRvG6KKOZt4vNpcw8mTVxM8T9x7qpV72xLEiw",
         "grant_type": "refresh_token"
     }'

All access tokens have a brief usable lifetime (currently one hour), after which they expire. To continue accessing that user's data, the app should obtain a new token using the refresh token that was issued alongside the access token. This refresh must be performed before the token's expiration time is reached. To refresh a token, make a POST request to https://api.lucid.co/oauth2/refreshToken with a Refresh Access Token body.

The response will match the format of the authorization response as an OAuth2 Token. Note: Refreshing a token invalidates the old access and refresh tokens. Be sure the app stores the new tokens returned in the response.

Important: Be sure to authenticate using the scope offline_access if the app will want to be able to refresh tokens.

Possible errors

For general information regarding errors that may be returned when requesting access from a user or creating a token, see sections 4.1.2.1 and 5.2 of RFC6749. The following table contains information specific to Lucid's APIs:

Error Code Possible Causes
invalid_client An admin on the Lucid account may have disabled access to your OAuth2 client.

Access Scopes

Scope Description shown to users on the consent screen
lucidchart.document.app View, edit, and manage any Lucidchart document selected for this third-party application.
Create, view, edit, and manage any Lucidchart document within its app-specific folder.
lucidchart.document.app.folder Create, view, edit, and manage any Lucidchart document within its app-specific folder.
lucidchart.document.app.picker View, edit, and manage any Lucidchart document selected for this third-party application.
lucidchart.document.app.picker:readonly View and download any Lucidchart document selected for this third-party application.
lucidchart.document.content Create, view, edit, and delete any Lucidchart document on your account.
lucidchart.document.content:readonly View and download any Lucidchart document on your account.
lucidspark.document.app View, edit, and manage any Lucidspark board selected for this third-party application.
Create, view, edit, and manage any Lucidspark board within its app-specific folder.
lucidspark.document.app.folder Create, view, edit, and manage any Lucidspark board within its app-specific folder.
lucidspark.document.app.picker View, edit, and manage any Lucidspark board selected for this third-party application.
lucidspark.document.app.picker:readonly View and download any Lucidspark board selected for this third-party application.
lucidspark.document.content Create, view, edit, and delete any Lucidspark board on your account.
lucidspark.document.content:readonly View and download any Lucidspark board on your account.
offline_access Continue to perform authorized actions when you’re not logged in (required to refresh tokens).
user.profile Allow applications to view basic information about you (e.g., full name, username, and email).

Important: The following list of scopes will be deprecated in favor of product specific scopes. In the meantime, they will be mapped to their Lucidchart scope equivalent (ex. document.content becomes lucidchart.document.content). Make sure your access tokens are using the new product specific scopes.

Scope Description shown to users on the consent screen
document.app View, edit, and manage any Lucidchart document selected for this third-party application.
Create, view, edit, and manage any Lucidchart document within its app-specific folder.
document.app.folder Create, view, edit, and manage any Lucidchart document within its app-specific folder.
document.app.picker View, edit, and manage any Lucidchart document selected for this third-party application.
document.app.picker:readonly View and download any Lucidchart document selected for this third-party application.
document.content Create, view, edit, and delete any Lucidchart document on your account.
document.content:readonly View and download any Lucidchart document on your account.

Resources

OAuth2 Token

A token that can be used to make authenticated API calls to Lucid APIs.

{
    "access_token": "oauth2-AVU=-klPMohE8EMdrmrHcAT5oydrwz3DPKpz40q4n8iKne5YjYY2oENT4YBXXyJt",
    "user_id": 341,
    "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_",
    "expires": 1605732868411,
    "scopes": ["lucidchart.document.app", "offline_access"],
    "token_type": "bearer",
    "refresh_token": "oauth2-AVU=-yPcwtzLkusIEnT7D9slQH4g8Ur0MdpUmpT0Z6BSMf6lmesRpTTSBGNniKd"
}
access_token String Token to be used when making requests with OAuth 2.0 authentication
client_id String The client ID
expires Timestamp Time until this token expires and will no longer work
refresh_token String If the token includes the scope offline_access then a refresh token will be provided
scopes Array[String] Scopes allowed on this token
token_type String Value is always "bearer"
user_id Number ID of the user this token is on behalf of
OAuth2 Introspect Token

Information about an OAuth2 token.

{
    "active": true,
    "user_id": 1001,
    "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_",
    "token_type": "bearer",
    "scope": "document.app offline_access",
    "exp": 1605732868411
}
active Boolean A boolean value indicating whether or not the token is active
client_id String The client ID
expires Timestamp Timestamp for when this token expires and will no longer work
scope String Space-separated list of scopes allowed on this token
token_type String The type of token returned (currently, always "bearer")
user_id Number ID of the user this token is on behalf of

Create Access Token

# Example request
curl https://api.lucid.co/oauth2/token
     --request POST
     --data 'grant_type=authorization_code'
     --data 'code=<authorization code>'
     --data 'client_id=<client id>'
     --data 'client_secret=<client secret>'
{
    "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
    "token_type": "bearer",
    "expires": 1619797052020,
    "refresh_token": "IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
    "scopes": ["lucidchart.document.content", "offline_access"]
}

POST https://api.lucid.co/oauth2/token

Request

POST /oauth2/token HTTP/1.1 Host: api.lucid.co Content-Type: application/x-www-form-urlencoded Accept: application/json grant_type=authorization_code &code=<authorization code> &client_id=<client id> &client_secret=<client secret>

Form Data
client_id String The client ID
client_secret String The client secret
code String The authorization code
grant_type String Value is always "authorization_code"
Response
200 Ok application/json with the access token and optional refresh token (if the offline_access scope was included).
403 Forbidden if the app making the request does not have permission to the document, the document has been deleted, or does not exist.
Example

HTTP/1.1 200 OK Content-Type: application/json { "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3", "token_type": "bearer", "expires": 1619797052020, "refresh_token": "IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk", "scopes": ["lucidchart.document.content", "offline_access"] }

Refresh Access Token

# Example request
curl https://api.lucid.co/oauth2/refreshToken
     --request POST
     --data 'grant_type=refresh_token'
     --data 'refresh_token=<refresh token>'
     --data 'client_id=<client id>'
     --data 'client_secret=<client secret>'
{
    "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
    "token_type": "bearer",
    "expires": 1619797052020,
    "refresh_token": "IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
    "scopes": ["lucidchart.document.content", "offline_access"]
}

POST https://api.lucid.co/oauth2/refreshToken

Request

POST /oauth2/refreshToken HTTP/1.1 Host: api.lucid.co Content-Type: application/x-www-form-urlencoded Accept: application/json grant_type=refresh_token &refresh_token=<refresh token> &client_id=<client id> &client_secret=<client secret>

Form Data
client_id String The client ID
client_secret String The client secret
grant_type String Value is always "refresh_token"
refresh_token String The current refresh token
Response
200 Ok application/json with the new access token and refresh token, as specified in OAuth2 token
403 Forbidden if the app making the request does not have permission to the document, the document has been deleted, or does not exist.
Example

HTTP/1.1 200 OK Content-Type: application/json { "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3", "token_type": "bearer", "expires": 1619797052020, "refresh_token": "IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk", "scopes": ["lucidchart.document.content", "offline_access"] }

Introspect Access Token

# Example request
curl https://api.lucid.co/oauth2/token/introspect
     --request POST
     --data 'token=<access or refresh token>'
     --data 'client_id=<client id>'
     --data 'client_secret=<client secret>'
{
    "active": true,
    "user_id": 1001,
    "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_",
    "token_type": "bearer",
    "scope": "document.app offline_access",
    "exp": 1605732868411
}

POST https://api.lucid.co/oauth2/token/introspect

Retrieves information about the specified access or refresh token.

Request

POST /oauth2/token/introspect HTTP/1.1 Host: api.lucid.co Content-Type: application/x-www-form-urlencoded Accept: application/json token=<access or refresh token> &client_id=<client id> &client_secret=<client secret>

Form Data
client_id String The client ID
client_secret String The client secret
token String The token to inspect
Response
200 Ok application/json with information about the token, as specified in OAuth2 Introspect Token
403 Forbidden if the client credentials are invalid.
Examples

If an active, non-revoked token is introspected:

HTTP/1.1 200 OK Content-Type: application/json { "active": true, "user_id": 1001, "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_", "token_type": "bearer", "scope": "document.app offline_access", "exp": 1605732868411 }

If the token has been revoked or is otherwise invalid:

HTTP/1.1 200 OK Content-Type: application/json { "active": false }

Revoke Access Token

# Example request
curl https://api.lucid.co/oauth2/token/revoke
     --request POST
     --data 'token=<access or refresh token>'
     --data 'client_id=<client id>'
     --data 'client_secret=<client secret>'

POST https://api.lucid.co/oauth2/token/revoke

Revokes the specified access or refresh token, preventing the token from being used.

Request

POST /oauth2/token/revoke HTTP/1.1 Host: api.lucid.co Content-Type: application/x-www-form-urlencoded Accept: application/json &token=<access or refresh token> &client_id=<client id> &client_secret=<client secret>

Form Data
client_id String The client ID
client_secret String The client secret
token String The token to revoke
Response
200 Ok if the client credentials are valid.
403 Forbidden if the client credentials are invalid.

Documents

Document resource

{
    "documentId": "110808fd-4553-4316-bccf-4f25ff59a532",
    "title": "document title",
    "editUrl": "https://lucid.app/lucidchart/110808fd-4553-4316-bccf-4f25ff59a532/edit",
    "viewUrl": "https://lucid.app/lucidchart/110808fd-4553-4316-bccf-4f25ff59a532/view",
    "version": 101,
    "pageCount": 5,
    "canEdit": false,
    "creatorId": 12345,
    "lastModified": "2020-06-26T16:29:37Z",
    "lastModifiedUserId": 54321,
    "customTags": ["in progress"],
    "status": "COMPLETE"
}

The example shown for this object may not be exhaustive. More fields may appear than shown here.

documentId UUID Document ID
title String Document Title
editUrl URI Link to edit document
viewUrl URI Link to view document
version Number Most recent version
pageCount Number Number of pages wtihin document
canEdit Boolean If requesting user can edit document
creatorId Number ID of user who created and owns the document
lastModified DateTime Date and time of when the document was last modified
lastModifiedUserId Number ID of user who most recently modified the document
customTags Array[String] List of any custom tags assigned to document
status String (Optional) Current assigned status of document

Get Document

# Example request
curl --request GET 'https://api.lucid.co/documents/6fe09818-47f0-422f-886d-2e6089696824'
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>'
     --header 'Lucid-Api-Version: 1'
     --header 'Content-Type: application/json'

GET https://api.lucid.co/documents/:id

Retrieves information about a specific document within Lucid. Requires at least read only access to the requested document.

Valid Access Scopes

lucidchart.document.content lucidchart.document.app lucidspark.document.content lucidspark.document.app

Request

GET /documents/:id HTTP/1.1 Host: api.lucid.co Authorization: <OAuth 2.0 Access Token> Lucid-Api-Version: 1 Content-Type: application/json

Path Parameters
id UUID
Example 6fe09818-47f0-422f-886d-2e6089696824

ID of document to be retrieved
Response
200 Ok with Document resource containing information about the requested document.
403 Forbidden if the app making the request does not have permission to the document, the document has been deleted, or does not exist.

Create Blank Document

// Body of request
{
    "title": "new document title"
}
# Example request
curl --request POST 'https://api.lucid.co/documents' \
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \
     --header 'Lucid-Api-Version: 1' \
     --header 'Content-Type: application/json' \
     --data-raw '{"title": "new document title", "product": "lucidchart"}'

POST https://api.lucid.co/documents

Creates a new blank document for the requesting user, with the specified title.

Valid Access Scopes

lucidchart.document.content lucidchart.document.app lucidspark.document.content lucidspark.document.app

Note: If the client making the request uses one of the document.app.folder scopes then the document will be created in a folder specific to that client. If one of the document.content scopes is used, documents will be created in the user's My Documents folder.

Request

POST /documents HTTP/1.1 Host: api.lucid.co Authorization: <OAuth 2.0 Access Token> Lucid-Api-Version: 1 Content-Type: application/json { "title": "new document title", "product": "lucidchart" }

Body
title String
Example "new document title"

Title that should be given to newly created document
product Product
Example "lucidchart"

Product used to create the new document
Response
201 Created with Document resource containing information about the newly created document.

Import Document

# Example request
curl --request POST 'https://api.lucid.co/documents' \
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \
     --header 'Lucid-Api-Version: 1' \
     --form 'file=@location/file.xml;type=x-application/vnd.lucid.drawio'
     --form 'title=My new document'

POST https://api.lucid.co/documents

Imports a given file to upload as a new document within Lucidchart

Valid Access Scopes

lucidchart.document.content lucidchart.document.app

Note: If the client making the request uses one of the document.app.folder scopes then the document will be created in a folder specific to that client. If one of the document.content scopes is used, documents will be created in the user's My Documents folder.

Request

POST /documents HTTP/1.1 Host: api.lucid.co Authorization: <OAuth 2.0 Access Token> Lucid-Api-Version: 1 Content-Type: multipart/form-data;boundary="boundary" --boundary Content-Disposition: form-data; name="file"; filename="<filename>" Content-Size: <size> <binary data> --boundary Content-Disposition: form-data; name="title" <title> --boundary--

Multipart Form Data
file Binary

The doc
  • x-application/vnd.lucid.drawio
  • x-application/vnd.lucid.gliffy
  • x-application/vnd.lucid.visio
title String
Example "My new document"

Title that should be given to the newly created document
Response
201 Created with Document resource containing information about the newly created document.

Export Document

# Example request
curl --request GET 'https://api.lucid.co/documents/7b36f31b-e4c0-4f2b-889f-e309c4108505'
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>'
     --header 'Lucid-Api-Version: 1'
     --header 'Accept: image/png;dpi=50, '

GET https://api.lucid.co/documents/:id

Exports a given document in a specified format. Requires at least read only access to the requested document.

Valid Access Scopes

lucidchart.document.content lucidchart.document.app lucidspark.document.content lucidspark.document.app

Request

GET /documents/:id HTTP/1.1 Host: api.lucid.co Authorization: Bearer <OAuth 2.0 Access Token> Lucid-Api-Version: 1 Accept: <content type>

Headers
Accept The format of the document to export.

Can be one of the following content types: image/jpg, image/jpg;dpi={dpi}, image/png, or image/png;dpi={dpi}

Where {dpi} is an optional number representing the DPI of the image. If not provided, DPI defaults to 170.
Path Parameters
id UUID

ID of document to be exported
Query Parameters
pageId Number
Example pageId=3

Specific page of document to export. Defaults to first page.
crop String

Specifies the crop settings for the document export.

Possible values:
  • x, y, width, height
    Crop to the specified region (in pixels) on the page
    Example crop=1000,300,30,7
  • content
    Crop to page content
    Example crop=content
Response
200 Ok with the binary data in the response body. The Accept header will specify the type of image that the response body contains.

Trash Document

# Example request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6' \
     --header 'Lucid-Api-Version: 1' \
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "operation": "trashDocument",
        "parameters": {}
    }'

PATCH https://api.lucid.co/documents/:id

Moves the specified document to the trash. Requires the user to be the owner of the requested document.

Valid Access Scopes

lucidchart.document.content lucidchart.document.app lucidspark.document.content lucidspark.document.app

Request

PATCH /documents/:id HTTP/1.1 Host: api.lucid.co Authorization: Bearer <OAuth 2.0 Access Token> Lucid-Api-Version: 1 Content-Type: application/json { "operation": "trashDocument", "parameters": {} }

Path Parameters
id UUID

ID of document to be moved to the trash
Body
operation String
Example trashDocument

Operation to perform on the document.
parameters Object
Example {}

Any parameters needed to perform the operation, in this instance none.
Response
200 Ok
403 Forbidden if the app making the request does not have permission to the document, the document has been deleted, or does not exist.

Embedding Lucid Documents

To embed a Lucid document using the OAuth2 access token, a short-lived embed token must be generated, and then the document can be embedded in an HTML page within an <iframe>.

Get Embed Token

# Example request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/embedToken' \
     --header 'Lucid-Api-Version: 1' \
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "domain": "example.com",
        "resourceUrl": "https://lucid.app/documents/embeddedchart/001bd56d-1b10-4196-8ac6-45e3c22bd1c6"
    }'

POST https://api.lucid.co/documents/:id/embedToken

Generates a tightly-controlled, limited scope, short-term temporary access token to allow third parties to access a specific resource externally without exposing the OAuth 2.0 access token.

The embed token grants the embedding website access to a specific URL (both embedded within the signed token for verification, as well as the response). The token is short-lived (5 minutes) to grant access to embed the resource (i.e. document viewer) but does not grant access to any additional resource within Lucid.

Valid Access Scopes

lucidchart.document.content lucidchart.document.app lucidspark.document.content lucidspark.document.app

Request

POST /documents/:id/embedToken HTTP/1.1 Host: api.lucid.co Authorization: Bearer <OAuth 2.0 Access Token> Lucid-Api-Version: 1 Content-Type: application/json { "domain": "{domain}", "resourceUrl": "{resourceUrl}" }

Path Parameters
id UUID

ID of document to embedded
Body
domain String
Example example.com

The domain which will host the embedded viewer.
resourceUrl String
Example https://lucid.app/documents/embeddedchart/001bd56d-1b10-4196-8ac6-45e3c22bd1c6

The URL of the resource being accessed.
Response
200 Ok with JWT the can be used to embed a document viewer
403 Forbidden if the app making the request does not have permission to the document, the document has been deleted, or does not exist.
Example

HTTP/1.1 200 OK Content-Type: application/jwt Content-Length: 289 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNvdXJjZSI6Imh0dHBzOi8vd3d3Lmx1Y2lkY2hhcnQuY29t L2RvY3VtZW50cy9lbWJlZGRlZGNoYXJ0Lzxkb2N1bWVudElkPiIsImNvbnN1bWVyIjoiPGNvbnN1bWVyPiIsImRvb WFpbiI6Ijxkb21haW4-IiwiaWF0IjoiPGlzc3VlZD4iLCJleHAiOiI8aXNzdWVkPiJ9.SJ1G16UGhMzGa-ENVPk7a KGTv6rhp3zKk_icLePhDwA

Embedded Viewer

<!-- Embed in a browser window -->
<iframe
    src="https://lucid.app/documents/embeddedchart/001bd56d-1b10-4196-8ac6-45e3c22bd1c6?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNvdXJjZSI6Imh0dHBzOi8vd3d3Lmx1Y2lkY2hhcnQuY29tL2RvY3VtZW50cy9lbWJlZGRlZGNoYXJ0Lzxkb2N1bWVudElkPiIsImNvbnN1bWVyIjoiPGNvbnN1bWVyPiIsImRvbWFpbiI6Ijxkb21haW4-IiwiaWF0IjoiPGlzc3VlZD4iLCJleHAiOiI8aXNzdWVkPiJ9.SJ1G16UGhMzGa-ENVPk7aKGTv6rhp3zKk_icLePhDwA"
></iframe>

GET https://lucid.app/documents/embeddedchart/:id?token=:token

Embed a document viewer within an <iframe>.

Request

Embed the viewer within an HTML page.

<iframe src='https://lucid.app/documents/embeddedchart/:id?token=:token' ></iframe>

Path Parameters
id UUID

ID of document to be embedded
Query Parameters
token String

Token retrieved from the Get Embed Token endpoint
Response
200 Ok text/html with an embedded document viewer for the specified document.
Example

HTTP/1.1 200 OK Content-Type: text/html <html response>

Users

Profile resource

The Profile resource contains basic profile information (username, email, full name) about the current authenticated user.

{
    "username": "johndoe",
    "email": "john-doe@example.com",
    "fullName": "John Doe"
}
username String Username of current user
email String Email of current user
fullName String Full name of current user

Note: The example shown for this object may not be exhaustive. More fields may appear than shown here.

Get Profile

# Example request
curl --request GET 'https://api.lucid.co/users/me/profile'
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>'
     --header 'Lucid-Api-Version: 1'
{
    "username": "johndoe",
    "email": "john-doe@example.com",
    "fullName": "John Doe"
}

GET https://api.lucid.co/users/me/profile

Retrieves basic information about the authenticated user.

Valid Access Scopes

user.profile

Request

GET /users/me/profile HTTP/1.1 Host: api.lucid.co Authorization: Bearer <OAuth 2.0 Access Token> Lucid-Api-Version: 1

Response
200 Ok with JSON object containing information about the requesting user.
Example

HTTP/1.1 200 OK Content-Type: application/json { "username": "johndoe", "email": "john-doe@example.com", "fullName": "John Doe" }

Legacy APIs

Authentication

Note: Legacy APIs use OAuth 1.0 for authentication, which uses separate set up and authentication steps than the OAuth 2.0 authentication of the standard APIs.

In order to use the Lucidchart API, a client must have permission from the user to access their data. This permission is granted with an OAuth 1.0 access token following the OAuth 1.0 specification. Details of the OAuth 1.0 authorization process and libraries for most languages can be found at https://oauth.net/1/.

To obtain an access token, the following steps need to be taken:

  1. Request an OAuth consumer key and secret from this page.

  2. Obtain a request token. Using the consumer key and secret obtained in step 1, a request token can be obtained by following the OAuth 1.0 protocol (see Obtaining an Unauthorized Request Token). The callback should be provided as part of making the call for a request token (Lucidchart does not currently support the OOB flow).

    The endpoint for obtaining a request token is: https://api.lucid.co/oauth/requestToken

  3. Obtain authorization. Authorization is obtained by redirecting the user to the Lucidchart authorization page with the appropriate oauth query parameters (see Obtaining User Authorization).

  4. Obtain the access token. If the user authorizes the third party, they will be redirected back to the third-party callback URL (that was provided when when the request token was requested) with a verifier as described in the oauth specification. Using the verifier and request token, the third party can request an access token (see Obtaining an Access Token).

    The endpoint for obtaining an access token is: https://api.lucid.co/oauth/accessToken

With the access token, a third party can sign requests to the Lucidchart API and get access to users data (see Signing Requests). Note that the Access Token can be revoked by the user at any time the user decides they no longer want the third party to have access to their Lucid data.

Data

The Data API lets you bring any kind of data into Lucid and visualize it. Using a simple REST API, changes to your data can be reflected in the document in a near real-time. The Data API facilitates:

  • Uploading datasets to Lucid manually, from an integration, or via API
  • Processing datasets to match Lucid's common format
  • Updating stored data sources, either manually or automatically
  • Querying and retrieving specific data for use in a document
  • Managing and sharing access to stored data sources
  • Authenticating with external data sources

Using the Data API allows Lucid Enterprise customers to flexibly add data to their documents without sacrificing any of the real-time collaboration and granular access control features that are central to the Lucid platform.

Authentication

Every request using the Data API must be authenticated with valid user credentials. This API supports both OAuth 1.0 authentication and OAuth 2.0 authentication.

Rate Limits

To prevent abuse and undue stress on the system the Data API has a rate limiting feature (sometimes called throttling) that restricts the requests of users.

Lucid recommends that you design your integration to gracefully handle this rate limit error. One way of doing that would be to have your integration sleep for 60 seconds when this error is encountered, and then subsequently retry the request. Alternatively, you might choose to implement exponential backoff, an error handling strategy whereby you periodically retry a failed request with progressively longer wait times between retries until either the request succeeds or the certain number of retry attempts is reached.

The error can be identified by having a 429 Too Many Requests status code.

Hard Refresh Interval 30 seconds since last
Soft Refresh Interval 30 seconds since last
User API Rate 750 requests per minute
File Size Limit 3 MB

Get Rate Limits

GET https://data.lucid.app/rateLimits

See what your current rate limits are.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/rateLimits'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /rateLimits HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Response
{
    "userHardRefreshInterval": 30,
    "userSoftRefreshInterval": 30,
    "userApiCallRate": 750,
    "fileSizeLimit": 3
}
200 Ok with current limits for requesting user.

Data Set

A data set is a logical grouping of data sources and can be thought of as a group of related spreadsheet files. A data set can contain multiple related data sources, but a data source can be a member of at most one data set.

The data set endpoints are responsible for the creation, deletion, and updating of data sets. The available actions are outlined below. A user can only modify data sets they have access to.

Resources

Data Set
{
    "uri": "https://data.lucid.app/dataSets/2168",
    "name": "Data Set Name",
    "properties": "https://data.lucid.app/dataSets/2168/properties",
    "created": "2021-06-02T19:52:33Z",
    "modified": "2021-06-02T19:52:33Z",
    "creatorId": 123456,
    "dataSetGrants": "https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168",
    "dataSources": "https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168"
}
uri URI Link to get self
name String Name of the data set
properties URI Link to get properties specific to this data set
created DateTime Timestamp of when the data set was created
modified DateTime Timestamp of when the data set was last modified
creatorId Integer Id of user who created the data set
dataSetGrants URI Link to get grants for this data set
dataSources URI Link to get data sources connected to this data set
Paginated List
{
    "dataSets": [Data Set, Data Set, ...],
    "total": 125,
    "prev": "https://data.lucid.app/dataSets?start=80&end=90",
    "next": "https://data.lucid.app/dataSets?start=100&end=110"
}
dataSets Array[Data Set] Array of data sets
total Number Total number of existing data sets
prev URI Link to get the previous list of data sets
next URI Link to get the next list of data sets

Get All Data Sets Count

HEAD https://data.lucid.app/dataSets

This endpoint returns the number of data sets a user has access to. The return value is in the response headers as Lucid-DataSets-Total

Valid OAuth2 Access Scope

data-service.admin

Request
curl --head 'https://data.lucid.app/dataSets'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

HTTP/1.1 200 OK
...
lucid-datasets-total: 123

HEAD /dataSets HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Response
200 Ok with lucid-datasets-total header in response

Get All Data Sets

GET https://data.lucid.app/dataSets

This endpoint returns all data sets that the user has access to. The results will be paginated. If the number of data sets exceeds the pagination limit, links will be provided to get the next set of results or the previous set of results (if applicable). The range of returned values can be determined by optional start and end parameters. If the difference between the end and start values is greater than the pagination limit, the endpoint returns data sets in the range from start to start + pagination limit. Items in the response are determined based on their creation order.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/dataSets?start=1&end=100'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /dataSets HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Query Parameters
start Number
Example start=3

Starting 1-based index of data sets to retreive. Defaults to 1.
end Number
Example end=150

Ending index of data sets to retreive. Defaults to 100.
Response
200 Ok with paginated list of Data Sets

Get Data Set

GET https://data.lucid.app/dataSets/:id

Gets a specific existing data set from Lucid

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/dataSets/435'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /dataSets/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 435

ID of data set to be retrieved
Response
200 Ok with Data Set

Create Data Set

POST https://data.lucid.app/dataSets

Creates a new data set and a corresponding new data set grant for the user. Note that a data set cannot be created with data sources already inside it, so data sources must be added to a data set through either the Create Data Source endpoint or the Update Data Source endpoint.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request POST 'https://data.lucid.app/dataSets'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

POST /dataSets HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Body
{
    "name": "Data Set Name",
    "properties": {
        "Color": "green",
        "AuthoredBy": "Lucidchart"
    }
}
name String
Example "New Data Set"

Name to give to new data set
properties Map[String,JsValue]
Example {"Color": "red", "AuthoredBy": "Lucidchart"}

Used to create the data set properties for the new data set.
Response
200 Ok with Data Set

Update Data Set Name

PATCH https://data.lucid.app/dataSets/:id

This endpoint takes the payload specified below and updates the data set name. Updates will only occur if the user has access to the data set. Note that the other fields in a dataset cannot be updated through this endpoint.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/dataSets/184'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

PATCH /dataSets/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Body
name String
Example "Updated Data Set"

Name to give to existing data set
Response
200 Ok with Data Set

Delete Data Set

DELETE https://data.lucid.app/dataSets/:id

This removes the specified data set and its associated properties. Once deleted, none of the information can be recovered. The data sources in the set will be removed from the data set but otherwise they will not be deleted or altered.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/dataSets/435'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /dataSets/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 435

ID of data set to be deleted
Response

200 Ok

Data Set Grant

Each data set must have one or more associated data set grant(s). The data set grants' purpose is to specify the authorization level of the data set. Each data set grant consists of a role, a permission type, and an identifier string saying which user, account or document the permission belongs to.

These endpoints are responsible for creating and deleting data set grants. The available endpoints are outlined below. Each endpoint takes optional access tokens to determine access to the requested resource. A user can create and delete data set grants only if they have appropriate access.

Resources

Data Set Grant
{
    "uri": "https://data.lucid.app/dataSetGrants/8",
    "dataSet": "https://data.lucid.app/dataSets/435",
    "permissionType": "account",
    "identifier": "1234",
    "role": "edit"
}
uri URI Link to get self
dataSet URI Link to get data set
permissionType String Permission type granted.

"user": This permission grants access to individual users if their Lucid id is equal to the grant's identifier string.

"account": This permission grants access to every user on the account specified by the grant's identifier string.

"document": This permission grants access to anyone who has access to the document referenced in the grant value, even if they are not a user on the associated Lucid account. Note that the kind of access a user has to a particular document affects the permissions granted by a data set grant through that document. In particular, if a user has read-only permissions on a particular document, any data set grant through that document will give them at most the 'view' access level, regardless of the access level listed on the data set grant itself.
identifier String The document id, account id, or user id matching the permission type
role String Available types are: "edit" and "view"

Get All Data Set Grants

GET https://data.lucid.app/dataSetGrants

Finds and returns all data set grants for the queried data set if the user has access to the data set.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/dataSetGrants?dataSet=https://data.lucid.app/dataSets/435'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'
[
    {
        "uri": "https://data.lucid.app/dataSetGrants/8",
        "dataSet": "https://data.lucid.app/dataSets/435",
        "permissionType": "account",
        "identifier": "1234",
        "role": "edit"
    },
    {
        "uri": "https://data.lucid.app/dataSetGrants/26",
        "dataSet": "https://data.lucid.app/dataSets/435",
        "permissionType": "user",
        "identifier": "9999",
        "role": "view"
    }
]

GET /dataSetGrants HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Query Parameters
dataSet URI
Example dataSet=https://data.lucid.app/dataSets/435

Data set to find all grants for.
Response
200 Ok with Array[Data Set Grant]

Get Data Set Grant

GET https://data.lucid.app/dataSetGrants/:id

Gets the requested data set grant if the access tokens are valid and the user has access to the data set. Note that the id in the URI is the number at the end of the data set grant's uri, not the identifier field of the object.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/dataSetGrants/435'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /dataSetGrants/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 435

ID of data set grant to be retrieved
Response
200 Ok with Data Set Grant

Create Data Set Grant

POST https://data.lucid.app/dataSetGrants

Creates a new data set grant for the specified data set. The requesting user must have access to the data set in order for it to succeed.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request POST 'https://data.lucid.app/dataSetGrants'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'
{
    "dataSet": "https://data.lucid.app/dataSets/435",
    "permissionType": "user",
    "identifier": "9999",
    "role": "view"
}

POST /dataSetGrants HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Body
dataSet URI
Example https://data.lucid.app/dataSets/435

Data set to add grant to.
permissionType String
Example "user"

Type of permission being given. Valid values are "account", "document" or "user".
identifier String
Example "9999"

Identifier for permission type.
role String
Example "view"

Role being given. Valid values are "view" and "edit".
Response
200 Ok with Data Set Grant

Delete Data Set Grant

DELETE https://data.lucid.app/dataSetGrants/:id

Removes the specified data set grant ONLY if it's not the last data set grant. There must always be at least one data set grant for a given data set, therefore the last data set grant cannot be deleted. A response message is returned with the result of the deletion. Note that the id in the URI is the number at the end of the data set grant's URI, not the identifier field of the Data Set Grant.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/dataSetGrants/26'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /dataSetGrants/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 26

ID of data set grant to be deleted
Response

200 Ok

Data Set Properties

Data sets can have properties that can describe a data set as a whole. Data set properties are a key-value store of information that is available to the consumer of the data set. Data set properties are very similar to collection properties.

The data set property endpoints are responsible for the creation, deletion, and updating of properties associated with a data set. The available endpoints are outlined below. A user can modify properties if they have access to the parent data set.

Get Data Set Properties

GET https://data.lucid.app/dataSets/:id/properties

Gets all properties for the specified data set if the user has access to the data set.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/dataSets/435/properties'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /dataSets/:id/properties HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 435

ID of data set to get properties for
{
    "backgroundColor": "blue",
    "font": "Times New Roman"
}
Response
200 Ok with Map[String,JsValue] of properties on the specified data set

Update Data Set Properties

PATCH https://data.lucid.app/dataSets/:id/properties

Allows a user to update the properties on a data set. This endpoint uses the supplied values to either update existing properties or add new properties.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/dataSets/184/properties'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

PATCH /dataSets/:id/properties HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 184

ID of data set to update properties for
Body
Map[String,JsValue]
Example { "property2": "bb", "property3": "c" }

Properties to update or add to specified data set
Response
200 Ok with list of properties that were affected

Delete Data Set Properties

DELETE https://data.lucid.app/dataSets/:id/properties

Removes only the properties provided in the query parameter. The deleted properties cannot be undone. The deletion will only occur if the user has access to the data set.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/dataSets/435/properties?properties=prop1,prop2'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /dataSets/:id/properties HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 435

ID of data set for properties to be deleted from
Query Parameters
properties Array[String]
Example properties=prop1,prop2

List of property names to remove from specified data set.
Response

200 Ok

Data Source

A data source is comprised of collections and can be thought of as a spreadsheet file, structured like an Excel file or a Google Sheets document. A data source can optionally belong to at most one data set, but it can also exist without belonging to any data set.

The data source endpoints are responsible for the creation, deletion, and updating of data sources. The available actions are outlined below. A user can only modify the data sources that they have access to.

Resources

Data Source
{
    "uri": "https://data.lucid.app/dataSources/2967",
    "name": "BambooHR",
    "product": "chart",
    "sourceGrants": "https://data.lucid.app/sourceGrants?dataSource=https://data.lucid.app/dataSources/2967",
    "adapterType": "BAMBOO_HR",
    "collections": "https://data.lucid.app/collections?dataSource=https://data.lucid.app/dataSources/2967",
    "items": "https://data.lucid.app/dataSources/2967/items",
    "linkParameters": {},
    "created": "2018-08-08T21:26:03Z",
    "lastModified": "2019-12-10T17:24:56Z",
    "deleted": null,
    "pending": false,
    "dataSet": null
}
uri URI Link to get self
name String Name of data source
sourceGrants URI Link to get grants specific to this data source
adapterType String Original type that the data source was created from
collections URI Link to get Collections connected to this data source
created DateTime Timestamp of when this data source was created
lastModified DateTime Timestamp of when this data source was last modified
pending Boolean If a data source is marked pending it won't be available for users to select within Lucid
dataSet URI Link to get connected data set
linkParameters Object (Optional) Link to get any parameters used for linking the data to it's source
deleted DateTime (Optional) Timestamp of when this data source was deleted
Paginated List
{
    "dataSources": [Data Source, Data Source, ...],
    "total": 125,
    "prev": "https://data.lucid.app/dataSources?start=80&end=90",
    "next": "https://data.lucid.app/dataSources?start=100&end=110"
}
dataSources Array[Data Source] Array of data sources
total Number Total number of existing data sources
prev URI Link to get the previous list of data sources
next URI Link to get the next list of data sources

Get All Data Sources Count

HEAD https://data.lucid.app/dataSources

This endpoint returns the number of data sources a user has access to. The return value is in the response headers as Lucid-DataSources-Total

Valid OAuth2 Access Scope

data-service.admin

Request
curl --head 'https://data.lucid.app/dataSources'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

HTTP/1.1 200 OK
...
lucid-datasources-total: 123

HEAD /dataSources HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Response
200 Ok with lucid-datasources-total header in response

Get All Data Sources

GET https://data.lucid.app/dataSources

This endpoint returns all data sources that the user has access to. The results will be paginated. If the number of data sources exceeds the pagination limit, links will be provided to get the next set of results or the previous set of results (if applicable). The range of returned values can be determined by optional start and end parameters. If the difference between the end and start values is greater than the pagination limit, the endpoint returns data sources in the range from start to start + pagination limit. Items in the response are determined based on their creation order.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/dataSources?start=1&end=100'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /dataSources HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Query Parameters
start Number
Example start=3

Starting 1-based index of data sources to retreive. Defaults to 1.
end Number
Example end=150

Ending index of data sources to retreive. Defaults to 1000.
Response
200 Ok with paginated list of Data Sources

Get Data Source

GET https://data.lucid.app/dataSources/:id

Gets a specific existing data source from Lucid. If the creator of the data source is the user making the request, the link parameters will be returned with the data source.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/dataSources/123'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /dataSources/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 123

ID of data source to be retrieved
Response
200 Ok with Data Source

Create Data Source

POST https://data.lucid.app/dataSources

Creates a new data source and a corresponding new data source grant for the user.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request POST 'https://data.lucid.app/dataSources'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

POST /dataSources HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Body
name String
Example "New Data Source"

Name to give to new data source
Response
200 Ok with Data Source

Delete Data Source

DELETE https://data.lucid.app/dataSources/:id

This removes the specified data source and anything related to it (collections, schema, items, link parameters). Once deleted, none of the information can be recovered.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/dataSources/123'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /dataSources/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 123

ID of data source to be deleted
Response

200 Ok

Data Source Grant

Each data source must have one or more associated source grant(s). The source grants' purpose is to specify the authorization level of the data source for a user trying to access it. Each source grant consists of an access level, a permission type, and an identifier string saying which user, account or document the permission belongs to.

These endpoints are responsible for creating and deleting data source grants. The available endpoints are outlined below. Each endpoint takes optional access tokens to determine access to the requested resource. A user can create and delete data source grants only if they have appropriate access.

Example Scenario 1

Bob uploads a Google Sheets document using the Data API, attaches a data source to a Lucidchart document, and shares the Lucidchart document with a coworker (Alice) who is on the same Lucid account. Alice is able to see the data already on the Lucidchart document as well as any updates or refreshes to the data that Bob makes. However, she cannot refresh the data herself. Next, Bob creates a new "account" level source grant for his data source. Because Alice and Bob are coworkers on the same company account, Alice is now able to refresh the data on the Lucidchart document and see changes as the Google Sheets document gets updated. The added "account" level source grant allows Alice to update the data in the Lucidchart document because she is on the same company account as Bob.

Example Scenario 2

Bob uploads a Google Sheets document using the Data API, attaches a data source to a document, and shares the document with a consultant (Carol). Carol does not belong to the same Lucidchart account as Bob. Carol is able to see the data already on the Lucidchart document, but she cannot refresh the data or see any changes made to the Google Sheets document. Bob creates a new "document" level source grant. Carol is now able to refresh the data on the Lucidchart document and see changes as the Google Sheets document gets updated.

Resources

Data Source Grant
{
    "uri": "https://data.lucid.app/sourceGrants/8",
    "dataSource": "https://data.lucid.app/dataSources/435",
    "permissionType": "user",
    "identifier": "5678",
    "role": "edit"
}
uri URI Link to get self
dataSource URI Link to get data source
permissionType String Permission type granted.

"user": This permission grants access to individual users if their Lucid id is equal to the grant's identifier string.

"account": This permission grants access to every user on the account specified by the grant's identifier string.

"document": This permission grants access to anyone who has access to the document referenced in the grant value, even if they are not a user on the associated Lucid account. Note that the kind of access a user has to a particular document affects the permissions granted by a data source grant through that document. In particular, if a user has read-only permissions on a particular document, any data source grant through that document will give them at most the 'view' access level, regardless of the access level listed on the data source grant itself.
identifier String The document id, account id, or user id matching the permission type
role String Available types are: "edit" and "view"

Get All Data Source Grants

GET https://data.lucid.app/sourceGrants

Finds and returns all data source grants for the queried data source if the user has access to the data source.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/sourceGrants?dataSet=https://data.lucid.app/dataSets/435'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'
[
    {
        "uri": "https://data.lucid.app/sourceGrants/8",
        "dataSource": "https://data.lucid.app/dataSources/1",
        "permissionType": "account",
        "identifier": "1234",
        "role": "edit"
    },
    {
        "uri": "https://data.lucid.app/sourceGrants/1",
        "dataSource": "https://data.lucid.app/dataSources/1",
        "permissionType": "user",
        "identifier": "9999",
        "role": "view"
    }
]

GET /sourceGrants HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Query Parameters
dataSource URI
Example dataSource=https://data.lucid.app/dataSources/435

Data source to find all grants for.
Response
200 Ok with Array[Data Source Grant]

Get Data Source Grant

GET https://data.lucid.app/sourceGrants/:id

Gets the requested data source grant if the access tokens are valid and the user has access to the data source. Note that the id in the URI is the number at the end of the data source grant's URI, not the identifier field of the object.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/sourceGrants/435'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /sourceGrants/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 435

ID of data source grant to be retrieved
Response
200 Ok with Data Source Grant

Create Data Source Grant

POST https://data.lucid.app/sourceGrants

Creates a new data source grant for the specified data source. The requesting user must have access to the data source in order for it to succeed.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request POST 'https://data.lucid.app/sourceGrants'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'
{
    "dataSet": "https://data.lucid.app/dataSets/435",
    "permissionType": "user",
    "identifier": "9999",
    "role": "view"
}

POST /sourceGrants HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Body
dataSet URI
Example https://data.lucid.app/dataSets/435

Data set to add grant to.
permissionType String
Example "user"

Type of permission being given. Valid values are "account", "document" or "user".
identifier String
Example "9999"

Identifier for permission type.
role String
Example "view"

Role being given. Valid values are "view" and "edit".
Response
200 Ok with Data Source Grant

Delete Data Source Grant

DELETE https://data.lucid.app/sourceGrants/:id

Removes the specified data source grant ONLY if it's not the last data source grant. There must always be at least one data source grant for a given data source, therefore the last data source grant cannot be deleted. A response message is returned with the result of the deletion. Note that the id in the URI is the number at the end of the data source grant's URI, not the identifier field of the Data Source Grant.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/sourceGrants/26'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /sourceGrants/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 26

ID of data source grant to be deleted
Response

200 Ok

Collection

A collection is a container inside of a data source. A data source can have many collections, but a collection can only belong to one data source. A collection can be thought of as a tab or individual sheet in a spreadsheet file. In the case of a CSV file, there would only be a single collection. Each collection contains a schema, items, collection properties, and metadata collections.

The collection endpoints are responsible for creating, updating, and deleting collections. The individual endpoints are outlined below. Each endpoint takes optional access tokens to determine access to the requested collection. A user can only modify collections if they have access to the data source.

Resources

Collection
{
    "uri": "https://data.lucid.app/collections/3",
    "dataSource": "https://data.lucid.app/dataSources/1",
    "name": "Some New Collection",
    "lastSync": "2018-03-28T14:48:45Z",
    "versionTimestamp": "2019-12-13T22:40:54Z",
    "created": "2018-03-23T17:34:31Z",
    "lastModified": "2018-03-28T14:48:44Z",
    "items": "https://data.lucid.app/collections/3/items",
    "schema": "https://data.lucid.app/collections/3/schema",
    "properties": "https://data.lucid.app/collections/3/properties",
    "metadata": "https://data.lucid.app/collections/3/metadata",
    "metadataType": null,
    "parent": null,
    "syncStarted": null,
    "deleted": null,
}
uri URI Link to get self
dataSource URI Link to get parent data source
name String Name of collection
lastSync DateTime Timestamp of the last time the collection was synced with upstream source
versionTimestamp DateTime Timestamp of the last time the collection, the collection's schema, the collection's contents, one of its collection properties, or anything in any of its metadata collections was changed. It can be used to tell if a copy of the data is out of date and needs to be refreshed.
created DateTime Timestamp of when this collection was created
lastModified DateTime Timestamp of when this collection was last modified
items URI Link to get associated items
schema URI Link to get associated schema
properties URI Link to get associated properties
metadata URI Link to get associated metadata collections
metadataType String (Optional) If a metadata collection, this specifies what type of metadata it contains
parent URI (Optional) If a metadata collection, this link will get it's parent collection
syncStarted DateTime (Optional) Represents the sync status of the collection. When it is null, there is no sync happening. When it has a DateTime value, that value represents the start time for the sync that is currently happening.
deleted DateTime (Optional) Timestamp of when this collection was deleted
Paginated List
{
    "collections": [Collection, Collection, ...],
    "total": 125,
    "prev": "https://data.lucid.app/collections?start=80&end=90",
    "next": "https://data.lucid.app/collections?start=100&end=110"
}
collections Array[Collection] Array of collections
total Number Total number of existing collections
prev URI Link to get the previous list of collections
next URI Link to get the next list of collections

Get All Collections Count

HEAD https://data.lucid.app/collections

This endpoint returns the number of collections a user has access to. The return value is in the response headers as Lucid-Collections-Total.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --head 'https://data.lucid.app/collections'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

HTTP/1.1 200 OK
...
lucid-collections-total: 123

HEAD /collections HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Response
200 Ok with lucid-collections-total header in response

Get All Collections

GET https://data.lucid.app/collections

This endpoint returns all collections that the user has access to. The results will be paginated. If the number of collections exceeds the pagination limit, links will be provided to get the next set of results or the previous set of results (if applicable). The range of returned values can be determined by optional start and end parameters. If the difference between the end and start values is greater than the pagination limit, the endpoint returns collections in the range from start to start + pagination limit. Items in the response are determined based on their creation order.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/collections?start=1&end=100'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /collections HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Query Parameters
start Number
Example start=3

Starting 1-based index of collections to retreive. Defaults to 1. >
end Number
Example end=150

Ending index of collections to retreive. Defaults to 1000. >
Response
200 Ok with paginated list of Collections

Get Collection

GET https://data.lucid.app/collections/:id

Gets a specific existing collection from Lucid.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/collections/3'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /collections/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 3

ID of collection to be retrieved
Response
200 Ok with Collection

Create Collection

POST https://data.lucid.app/collections

Creates a new collection for the specified data source. Only succeeds if the user has access to the data source.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request POST 'https://data.lucid.app/collections'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

POST /collections HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Body
{
    "dataSource": "https://data.lucid.app/dataSources/1",
    "name": "Reports 2020",
    "schema": [
        {
            "name": "Name",
            "fieldType": "STRING",
            "order": 1
        },
        {
            "name": "Employee ID",
            "fieldType": "NUMBER",
            "default": "1",
            "order": 2
        }
    ],
    "properties": {
        "backgroundColor": "green",
        "fontSize": "12"
    }
}
dataSource URI
Example https://data.lucid.app/dataSources/1

URI of data source that the collection should be added to
name String
Example "Reports 2020"

Name to give to new collection
schema Array[Field Definition]
Example [{"name": "Employee ID", "fieldType": "STRING", "order": 1}]

The schema field takes an array of Field Definition objects.
properties Object
Example {"fontSize": "12"}

The properties field is used to store a string mapping of properties to be used by the client. An empty object can be provided.
Response
200 Ok with Collection

Update Collection

PATCH https://data.lucid.app/collections/:id

This endpoint takes a JSON object and uses it to update the collection's name and/or data source. The JSON object of the updated collection is returned. Updates will only occur if the user has access to the data source. Only top level collections can be updated. Metadata collections cannot be updated.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/collections/5'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

PATCH /collections/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 5

ID of collection to be updated
Body
{
    "dataSource": "https://data.lucid.app/dataSources/12",
    "name": "Reports 2019",
}

{
    "name": "Reports 2018",
}
dataSource URI
Example https://data.lucid.app/dataSources/12

URI of data source that the collection should be moved to be a part of
name String
Example "Reports 2019"

Updated name to give to collection
Response
200 Ok with Collection

Delete Collection

DELETE https://data.lucid.app/collections/:id

This removes the collection and anything that belongs to it (metadata collections, schema, and items). Data sources will not be removed. This action cannot be undone and will only occur if the user has access to the data source.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/collections/3'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /collections/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 123

ID of collection to be deleted
Response

200 Ok

Get All Metadata Collections

GET https://data.lucid.app/collections/:id/metadata

This endpoint returns a list of Collections for any metadata collections that exist on the requested collection. The return will only occur if the user has access to the data source. Each metadata collection will have a link to its parent collection in the parent field.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/collections/1232/metadata'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /collections/:id/metadata HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Response
200 Ok with list of Collections

Create Metadata Collection

POST https://data.lucid.app/collections/:id/metadata

Create a new metadata collection for a given collection. The user must have access to the data source in order to create a metadata collection. Metadata collections cannot be updated.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request POST 'https://data.lucid.app/collections/123/metadata'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

POST /collections/:id/metadata HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 123

ID of collection to add metadata collection to
Body
{
    "name": "Reports 2020",
    "metadataType": "TextColor",
    "schema": [
        {
            "name": "Name",
            "fieldType": "STRING",
            "order": 1
        },
        {
            "name": "Employee ID",
            "fieldType": "NUMBER",
            "default": "1",
            "order": 2
        }
    ],
    "properties": {
        "backgroundColor": "green",
        "fontSize": "12"
    }
}
name String
Example "Reports 2020"

Name to give to new collection
metadataType String
Example "TextColor"

Type of metadata this collection contains
schema Array[Field Definition]
Example [{"name": "Employee ID", "fieldType": "STRING", "order": 1}]

The schema field takes an array of Field Definition objects.
properties Object
Example {"fontSize": "12"}

The properties field is used to store a string mapping of properties to be used by the client. An empty object can be provided.
Response
200 Ok with Collection

Collection Properties

Collections can have properties that can describe the collection as a whole. Some of these properties are predefined, meaning that either the Data API or the client will automatically read and interpret them in ways already determined by Lucid. However, the Data API itself does not limit which properties may be created or used, and third-party applications can use any unused properties to tag collections for any purpose.

The collection property endpoints are responsible for the creation, deletion, and updating of properties associated with a collection. The available endpoints are outlined below. A user can modify properties on a collection if they have access to the parent data source.

Get Collection Properties

GET https://data.lucid.app/collections/:id/properties

Gets all properties for the specified collection if the user has access to the data source.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/collections/435/properties'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /collections/:id/properties HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 435

ID of collection to get properties for
{
    "backgroundColor": "blue",
    "font": "Times New Roman"
}
Response
200 Ok with Map[String,JsValue] of properties on the specified collection

Update Collection Properties

PATCH https://data.lucid.app/collections/:id/properties

Allows a user to update the properties on a collection. This endpoint uses the supplied values to either update existing properties or add new properties.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/collections/184/properties'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

PATCH /collections/:id/properties HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 184

ID of collection to update properties for
Body
Map[String,JsValue]
Example { "property2": "bb", "property3": "c" }

Properties to update or add to specified collection
Response
200 Ok with list of properties that were affected

Delete Collection Properties

DELETE https://data.lucid.app/collections/:id/properties

Removes only the properties provided in the query parameter. The deleted properties cannot be undone. The deletion will only occur if the user has access to the collection.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/collections/435/properties'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /collections/:id/properties HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 435

ID of collection for properties to be deleted from
Query Parameters
properties Array[String]
Example properties=property1,property2

List of property names to remove from specified collection.
Response

200 Ok

Schema

Each collection has one schema which describes the content of the collection. You can think of the schema as a header row in a spreadsheet. The schema is made up of field definitions.

Each field holds a value and can be thought of as a single cell in a spreadsheet. An item can have many fields, but a field can only belong to one item.

Each field definition describes the name and type (string, number, boolean, etc) of the field. It also specifies whether or not the field is a primary key, the order in the primary key if it is a primary key, and the default value for the field. The name of the field can be thought of as the column name in a spreadsheet. Primary keys act as identifiers for the items they belong to. If an item's field value is not specified, the default value from the field definition will be used.

For example, suppose you want to store the following snippet from a spreadsheet:

First Name Phone Number Over 18
1 Bob 1234567890 true
2 Alice 4567890123 true
3 Carol 7891234560 false

The schema would have three field definitions, one for each column. The first field definition's name would be "First Name". The type would be "string". The "First Name" field is not the primary key since the unique identifier in this case is the "Phone Number". The second field definition's name would be "Phone Number". The type would be "number". It is a primary key, because it is a unique value that can be used to identify each item. The third field definition's name is "Over 18" with a type of "boolean".

The schema endpoints are responsible for the creation, deletion, and updating of field definitions within a schema. A user can only modify field definitions if they have access to the data source.

Resources

{
    "uri": "https://data.lucid.app/collections/2/schema/4",
    "name": "ColB",
    "fieldType": "NUMBER",
    "collection": "https://data.lucid.app/collections/2",
    "isPrimary": false,
    "order": 1,
    "default": "5",
    "label": null
}
uri URI Link to get self
name String Name of field
fieldType String Stores the type of the field. The type does not affect how the data is interpreted in the Data Service; it is for use on the client side. Some valid values are: BOOLEAN, STRING, NUMBER, and ANY.
collection URI Link to get associated collection
isPrimary Boolean Denotes whether the specified field is part of the primary key. The default value is false.
order String (Optional) Denotes a default ordering for the fields. This is currently used by the Lucid client to determine the order in which the fields are displayed, unless the context suggests a better ordering
default String (Optional) Represents the default value for this field
label String (Optional) Override name for field which is used when displaying to users

Get All Field Definitions

GET https://data.lucid.app/collections/:collectionId/schema

This endpoint returns all field definitions for a given collection if the user has access

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/collections/2/schema'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'


[
    {
        "uri": "https://data.lucid.app/collections/1/schema/1",
        "name": "colA",
        "fieldType": "STRING",
        "collection": "https://data.lucid.app/collections/1",
        "isPrimary": false,
        "order": 2,
        "default": "foo"
    },
    {
        "uri": "https://data.lucid.app/collections/1/schema/2",
        "name": "colB",
        "fieldType": "NUMBER",
        "collection": "https://data.lucid.app/collections/1",
        "isPrimary": true,
        "order": 1,
        "default": null
    }
]

GET /collections/:collectionId/schema HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection schema belongs to
Response
200 Ok with Array[Field Definition]

Get Field Definition

GET https://data.lucid.app/collections/:collectionId/schema/:id

Gets a specific existing field definition for a given collection

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/collections/2/schema/4'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'
{
    "uri": "https://data.lucid.app/collections/2/schema/4",
    "name": "colA",
    "fieldType": "STRING",
    "collection": "https://data.lucid.app/collections/2",
    "isPrimary": false,
    "order": 2,
    "default": "foo"
}

GET /collections/:collectionId/schema/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection schema belongs to
id Integer
Example 4

ID of field definition to retrieve
Response
200 Ok with Field Definition

Update Field Definitions

PATCH https://data.lucid.app/collections/:id/schema

This endpoint allows updating multiple field definitions at once. The easiest way to accomplish this is to modify the values in the response from the get all field definitions endpoint and send a PATCH request. Changing the values will update existing field definitions within the collection's schema. Any fields sent without a uri field will result in an addition to the schema if the name field is unique within the schema. Fields cannot be deleted with this endpoint.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/collections/5/schema'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'
[
    {
        "uri": "https://data.lucid.app/collections/1/schema/1",
        "name": "colFirst",
        "fieldType": "STRING",
        "collection": "https://data.lucid.app/collections/1",
        "isPrimary": false,
        "order": 2,
        "default": "foo"
    },
    {
        "name": "colB",
        "fieldType": "NUMBER",
        "collection": "https://data.lucid.app/collections/1",
        "isPrimary": true,
        "order": 1,
        "default": null
    }
]

PATCH /collections/:id/schema HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 5

ID of collection schema to be updated
Body
Array[Field Definition]

List of field definitions to be added or updated for the collection.
Response
200 Ok with Array[Field Definition] containing new or updated fields on the collection.

Update Field Definition

PATCH https://data.lucid.app/collections/:collectionId/schema/:id

This endpoint takes a Field Definition, which is used to update the specified field definition. The easiest way to accomplish this is to modify the values in the response from the GET field definition endpoint and send a PATCH request.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/collections/5/schema/3'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'
{
    "uri": "https://data.lucid.app/collections/5/schema/3",
    "name": "updated col name",
    "fieldType": "STRING",
    "collection": "https://data.lucid.app/collections/5",
}

PATCH /collections/:collectionId/schema/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 5

ID of collection schema to be updated
id Integer
Example 3

ID of specific field within the schema to be updated
Body
Field Definition

Field definition to be updated for the collection.
Response
200 Ok with Field Definition containing new or updated fields.

Delete Field Definitions

DELETE https://data.lucid.app/collections/:collectionId/schema

This endpoint removes only the field definitions provided in the query parameter. The fields in the query parameter must belong to the collection specified. The results of this deletion cannot be undone. The deletion will only occur if the user has access to the data source.

NOTE: If the entire schema is removed then all of the values of each data item are also removed.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/collections/2/schema?fields=/collections/2/schema/1,/collections/2/schema/2'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /collections/:collectionId/schema? HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection schema belongs to
Query Parameters
fields Array[URI]
Example fields=/collections/2/schema/1,/collections/2/schema/2

Specific field defininitions to remove from collection's schema
Response

200 Ok

Delete Field Definition

DELETE https://data.lucid.app/collections/:collectionId/schema/:id

This removes the field definition from the collection's schema. This results of this action cannot be undone. The delete will only occur if the user has access to the data source. This action will also remove all data item values associated with the deleted field.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/collections/2/schema/4'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /collections/:collectionId/schema/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection schema belongs to
id Integer
Example 4

ID of field definition to delete
Response

200 Ok

Data Item

An item is a container inside of a collection and can be thought of as a single row in a spreadsheet. A collection can have many items, but an item can only belong to one collection. Each item is made up of fields.

Each data item consists of its URI, collection, and a list of fields. The fields consist of a mapping from schema field names to data item values. Each field name corresponds to a matching field in the collection's schema. If a data item has not been given a specific value for each schema field, the value will either be the default on the schema field or null.

The data item endpoints are responsible for the creation, deletion, and updating of data items within a collection. The actions are outlined below. A user can modify data items if they have access to the data source.

Resources

Data Item
{
    "uri": "https://data.lucid.app/collections/1009534/items/46",
    "collection": "https://data.lucid.app/collections/1009534",
    "fields": {
        "A": "This is the original version",
        "B": "123.0",
        "C": "5.0"
    }
}
uri URI Link to get self
collection URI Link to get collection the item belongs to
fields Object Mapping of field names found in schema to this specific item's values
Data Item Find By Key
{
    "fieldValues": ["Joey", "Ontario"]
}
fieldValues Array[String] Specifies the actual value that the fields need to have to be found.
Data Item Patch By Key
{
    "fieldValues": ["Rowland"],
    "patch": {
        "First Name": "Jordan",
        "Last Name": "Haron"
    }
}
fieldValues Array[String] Specifies the actual value that the fields need to have to be found.
patch Map[String, Optional[String]] List of field names with the new value that the field should be set to. Changes will be applied to any matching items and if the value is null, that field will be deleted from the matching data items.
Paginated List
{
    "items": [Data Item, Data Item, ...],
    "total": 125,
    "prev": "https://data.lucid.app/collections/44/items?start=80&end=90",
    "next": "https://data.lucid.app/collections/44/items?start=100&end=110"
}
items Array[Data Item] Array of data items
total Number Total number of existing data items
prev URI Link to get the previous list of data items
next URI Link to get the next list of data items

Get All Data Items Count

HEAD https://data.lucid.app/collections/:collectionId/items

This endpoint returns the number of data items a user has access to. The return value is in the response headers as Lucid-Items-Total

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request HEAD 'https://data.lucid.app/collections/3/items'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

HEAD /collections/:collectionId/items HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 3

ID of collection items belong to
Response

200 Ok

Get All Data Items

GET https://data.lucid.app/collections/:collectionId/items

This endpoint returns all data items within a collection that the user has access to. The results will be paginated. If the number of data items exceeds the pagination limit, links will be provided to get the next set of results or the previous set of results (if applicable). The range of returned values can be determined by optional start and end parameters. If the difference between the end and start values is greater than the pagination limit, the endpoint returns collections in the range from start to start + pagination limit. Items in the response are determined based on their creation order.

This endpoint also supports an optional filter string that can be used to filter down the data items returned based off the items' fields' values. If a filter is included, the start and end parameters only refer to items which satisfy the filter; this is also true of the total value in the response. For more details, see Data Item Filters.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/collections/3/items?start=1&end=100'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /collections/:collectionId/items HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 3

ID of collection items belong to
Query Parameters
start Number
Example start=3

Starting 1-based index of data items to retreive. Defaults to 1.
end Number
Example end=150

Ending index of data items to retreive. Defaults to 10000.
filter String
Example end=age%20%3E%2016

Url-encoded filter string. Example unencoded is filter=age > 16
Response
200 Ok with paginated list of Data Items

Get Data Item

GET https://data.lucid.app/collections/:collectionId/items/:id

Gets a specific existing data item from a given collection

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request GET 'https://data.lucid.app/collections/3/items/1'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

GET /collections/:collectionId/items/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection schema belongs to
id Integer
Example 4

ID of data item to retrieve
Response
200 Ok with Data Item

Get Data Items By Key

POST https://data.lucid.app/collections/:collectionId/items/:id

Returns all data items in the specified collection whose field values match the values specified in a Data Item By Key Find JSON Object. If necessary, you can paginate this endpoint's results using query parameters.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request POST 'https://data.lucid.app/collections/3/items/1'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

POST /collections/:collectionId/items/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection schema belongs to
id Integer
Example 4

ID of data item to retrieve
Query Parameters
start Number
Example start=3

Starting 1-based index of data items to retreive. Defaults to 1.
end Number
Example end=150

Ending index of data items to retreive. Defaults to 10000.
Body
{
    "targetValues": [
        {
            "fieldValues": ["Joey", "Ontario"]
        },
        {
            "fieldValues": ["Sheela", "Indigo"]
        }
    ],
    "keySchemaFields": ["first name", "last name"],
}
targetValues Array[Data Item Find By Key]
Example [{"fieldValues": ["Joey", "Ontario"]}]

List of parameters by which to search for data items.
keySchemaFields Array[String]
Example ["first name"]

Fields used to search for items in the collection. If it is not provided, primary keys from the schema are used.
Response
200 Ok with paginated list of Data Items

Note: For more complex data item search queries, consider using the filter parameter with Get All Data Items.

Create Data Items

POST https://data.lucid.app/collections/:id/items

If the user has access to the collection, new data items are created using the supplied values. Primary key constraints are not enforced. Any field name that is not part of the schema definition is ignored by default. The schema should be created prior to any data items being created.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request POST 'https://data.lucid.app/collections/123/items'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

POST /collections/:id/items HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 123

ID of collection to add data items to
[
    {
        "ColA": "a value",
        "ColB": "b value"
    },
    {
        "ColA": "aa value",
        "ColB": "bb value",
        "ColC": "cc value"
    }
]
Body
Array[Map[String,String]]
Example [{"ColA": "a value"}]

Field value pairs to create data items from. Each mapping is for a single data item.
Response
200 Ok with Array[Data Item]

Update Data Item

PATCH https://data.lucid.app/collections/:collectionId/items/:id

Update values for the specified item. The easiest way to accomplish is to modify the values in the response from Get Data Item and send a PATCH request. Changing the values will update existing data item values. The collection field is ignored as the data item cannot be moved to a different collection. It the new value is null, it means the value is deleted. If the provided field name does not exist in the collection schema, that value is ignored.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/collections/5/items/2'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

PATCH /collections/:collectionId/items/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 5

ID of collection for data item to be updated in
id Integer
Example 5

ID of data item to be updated
Body
{
    "uri": "https://data.lucidchart.com/collections/22/items/3",
    "fields": {
        "ColA": "new a value",
        "ColB": null
    }
}
uri URI
Example https://data.lucid.app/collections/22/items/3

URI of data item to be updated
fields Map[String,Optional[JsValue]]
Example {"ColA": "new aa value"}

Field value pairs to update data items from. Mapping is for a single data item.
Response
200 Ok with Data Item

Update Data Items

PATCH https://data.lucid.app/collections/:id/items

This endpoint allows updating multiple data items at once. The easiest way to accomplish is to modify the values in the response from Get All Data Items and send a PATCH request. Changing the values will update existing data item values. The collection field is ignored as the data item cannot be moved to a different collection. It the new value is null, it means the value is deleted. If the provided field name does not exist in the collection schema, that value is ignored.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/collections/5/items'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

PATCH /collections/:id/items HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
id Integer
Example 5

ID of collection for data items to be updated in
[
    {
        "uri": "https://data.lucidchart.com/collections/22/items/3",
        "fields": {
            "ColA": "new a value",
            "ColB": null
        }
    },
    {
        "uri": "https://data.lucidchart.com/collections/22/items/4",
        "fields": {
            "ColA": "new aa value",
            "ColB": "new bb value",
            "ColC": "should not show up"
        }
    }
]
Body
uri URI
Example https://data.lucid.app/collections/22/items/3

URI of data item to be updated
fields Map[String,Optional[JsValue]]
Example {"ColA": "new aa value"}

Field value pairs to update data items from. Mapping is for a single data item.
Response
200 Ok with Array[Data Item]

Update Data Items By Key

PATCH https://data.lucid.app/collections/:collectionId/itemsByKey

Find any data items whose fields match specified values and update those items using a patch. If the value of a field in a patch is null, that value will be deleted from the item. If the provided field name does not exist in the collection schema, that value is ignored. Attempts to update the Collection field will be ignored as a data item cannot be moved to a different collection.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request PATCH 'https://data.lucid.app/collections/5/itemsByKey'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

PATCH /collections/:collectionId/itemsByKey HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 5

ID of collection for data item to be updated in
{
    "patches": [
        {
            "fieldValues": ["Alex", "Rowland"],
            "patch": {
                "First Name": "Jordan",
                "Last Name": "Haron"
            }
        }
    ],
    "keySchemaFields": ["Last Name"],
}
Body
patches Array[Data Item Patch By Key]

Define what items from the collection you are changing and how to change them. The order of strings in fieldValues must match that of either keySchemaFields or of the actual primary keys from the real schema if keySchemaFields is not defined.
keySchemaFields Array[String]
Example ["first name"]

Fields used to search for items in the collection. If it is not provided, primary keys from the schema are used.
Response
200 Ok with message indicating the number of items updated. Ex: "Updated 1 item(s)"

Delete Data Item

DELETE https://data.lucid.app/collections/:collectionId/items/:id

Removes the specified data item from the collection. This deletion cannot be undone. The deletion will only occur if the user has access to the data source.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/collections/3/items/1'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /collections/:collectionId/items/:id HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection item belongs to
id Integer
Example 4

ID of data item to delete
Response

200 Ok

Delete Data Items

DELETE https://data.lucid.app/collections/:collectionId/items

Removes only the data items provided in the query parameter. The data items in the query parameter must belong to the collection specified. The deletion cannot be undone. The deletion will only occur if the user has access to the data source.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/collections/3/items'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /collections/:collectionId/items HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection item belongs to
Query Parameters
items Array[URI]
Example items=/collections/2/items/5,/collections/2/items/6

List of data items to delete from collection
Response

200 Ok

Delete Data Items By Key

DELETE https://data.lucid.app/collections/:collectionId/itemsByKey

Finds all the items whose key values match those specified by the payload and deletes them. The deletion cannot be undone. The deletion will only occur if the user has access to the data source.

Valid OAuth2 Access Scope

data-service.admin

Request
curl --request DELETE 'https://data.lucid.app/collections/3/itemsByKey'
     --header 'Authorization: Bearer <OAuth Access Token>'
     --header 'Accept: application/json;v=1'

DELETE /collections/:collectionId/itemsByKey HTTP/1.1 Host: data.lucid.app Authorization: <OAuth Access Token> Accept: application/json;v=1

Path Parameters
collectionId Integer
Example 2

ID of collection item belongs to
{
    "targetValues": [
        {
            "fieldValues": ["Joey", "Ontario"]
        },
        {
            "fieldValues": ["Sheela", "Indigo"]
        }
    ],
    "keySchemaFields": ["first name", "last name"]
}
targetValues Array[Data Item Find By Key]

Defines what items within the collection you are searching for. The order of strings in fieldValues must match that of either keySchemaFields or of the actual primary keys from the real schema if keySchemaFields is not defined.
keySchemaFields Array[String]
Example ["first name"]

Fields used to search for items in the collection. If it is not provided, primary keys from the schema are used.
Response

200 Ok

Data Item Filters

The data item filter is a query string that is optionally available on the Get All Data Items endpoint. Its purpose is to allow you to limit which items you get from the Data API. This section covers its syntax and limitations.

The central component of the item filter expression is the comparison. By itself, a comparison is the simplest valid filter. All comparisons are strictly of the form fieldname -> operator -> constant. Note that the order is important; the field name must be on the left side and the constant must be on the right. A simple example of a comparison would be the filter name = "James", which will limit the results to only items where the field name has the value "James". If you wish to do a numeric comparison instead, you could use a filter like age > 21. Note that string constants are wrapped in quotes, while numeric constants are not.

Fields

If the name of the field you are filtering on contains spaces or other special characters, you can wrap the field name in any of the three simple quotation marks: " or ' or `. Thus the string "full name" = "John Smith" is a valid comparison for the field full name. If the field name includes quotes, you may either wrap the field name using one of the other quote characters (preferred) or you can escape the quote marks inside the field name by doubling them. For instance, you can represent the field name "I can't even" as either "I can't even" or 'I can''t even'.

Operators

There are 8 operators you can use in your comparisons:

Operator Valid Constant Type Notes
= String, Number Equality works well with strings and with integer numbers. Floating-point numbers here and in general have difficulties with equality. This is a very involved problem, so if you are having trouble with it we suggest looking up specialized resources elsewhere.
!= String, Number Note that = and != are only inverses over field values which are considered comparable to the constant, as outlined in the section below.
> String, Number
>= String, Number
< String, Number
<= String, Number
IN String, Number, Array[String] If the constant is either a string or number, it is treated as an array of strings or numbers that has a single element.
CONTAINS String, Number The data item will be split by comma seperator, and checked to see if any one of the children is the same as the constant.

All string comparisons are case-insensitive.

Comparisons and Type Coercion

For all operators, the value of the field must be considered comparable with the constant in order for the result to be true. For instance, when the constant is a number, the fields are coerced to a number before the comparison is performed. If the field cannot be coerced to a number, the result of the comparison is false. This means, for instance, that a field with value "0.0" is equal to the numeric constant 0 but not the string constant "0". This also means that a field with value "a" will return false for both "a" = 0 and "a" != 0 because "a" cannot be coerced to a number. Similarly, if the constant is an array of strings, the comparison can evaluate to true only if the operator involved is IN; all other operators combined with an array constant are automatically false.

Constants

A constant can be either a quoted string, a number, or an array of strings.

A constant is a string if the constant is wrapped in any of the simple quotation marks (" or ' or `). As with field names, to include quotation marks inside a quoted string, you can either use a different quote symbol or escape the quotation marks by doubling them in every desired location inside the string.

A constant is a number if it is not quoted, not inside parentheses, and can be parsed as a valid floating point number in Java.

A constant is an array of strings if it is a comma-separated list of strings wrapped inside a pair of parentheses. Arrays only evaluate when using the IN operator; any other operator used with an array of strings automatically evaluates to false. An example of a comparison using an array of strings is "name IN ("Peter", "Paul", "Mary")"; this will evaluate to true only if the name is one of "Peter", "Paul", or "Mary".

Compound filters

Compound filters can be created from comparisons using the AND, OR and NOT operators, as outlined in the following table. You can use parentheses to group operations if the default precedence is not what you need.

Operator Precedence Effect
NOT Highest Invert the result of the filter immediately after this operator
AND Medium The compound filter is only true if the filters before and after this operator are both true
OR Lowest True if either the filter before or after this operator is true

For example, if you want a match for all items with names that are not "Thomas" or "Susan", you could use the compound filter NOT name IN ("Thomas", "Susan"). If you want people whose age is either less than 8 or greater than 10, you could use the compound filter age < 8 OR age > 10. If you only want people with first name "Chris" and whose last name is neither "Smith" nor "Wesson", you could use the compound filter first_name = "Chris" AND NOT last_name IN ("Smith", "Wesson").

For a more complex example of compound filters and their precedences, consider the following filter:

age > 21 AND NOT last_name in ("Smith", "Wesson") OR as_adult = "true"

This filter will return every item from the collection that has the field as_adult set to the value "true". It will also return every item which has an age greater than 21 and whose last_name is not either "Smith" or "Wesson". If there are any items which satisfy both of these conditions, they will be included in the results, but only once. This is equivalent to the filter

((age > 21 AND (NOT last_name in ("Smith", "Wesson"))) OR as_adult = "true")

but different from the filter

age > 21 AND (NOT last_name in ("Smith", "Wesson") OR as_adult = "true")

This last filter will only return items which have an age greater than 21, but only if they have as_adult equal to "true" or if their last_name is anything besides "Smith" or "Wesson".

Full filter syntax

The full syntax for the filter string is given by the following definitions:

filter = comparison | composite filter

comparison = fieldname operator constant

fieldname = identifier | quotedstring

identifier = a sequence of non-whitespace chars

quotedstring = ("|'|`)("|'|`)
(both of the outer quotes must be the same symbol)


operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'IN'

constant = stringconstant | numberconstant | stringarray

stringconstant = quotedstring

numberconstant = any non-quoted string (without whitespace) that Java parses as a valid double

stringarray = '(' stringconstant [, stringconstant... ] ')'

composite filter = notfilter | andfilter | orfilter

notfilter = 'NOT' filter

andfilter = filter 'AND' filter

orfilter = filter 'OR' filter

Documents

Resources

Document Metadata resource
<?xml version="1.0" ?>
<documents>
   <document>
       <documentId>4df67392-0894-44ad-987e-6ab30a2e3afb</documentId>
       <title>Mockup #1</title>
       <editUrl>https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/view</viewUrl>
       <version>220</version>
       <pageCount>3</pageCount>
   </document>
</documents>

The primary resource of the document metadata endpoint, enclosed in a <documents> tag.

documents Array[Document] The list of document metadata. For the document metadata endpoint, will have a single entry.
Document List resource
<?xml version="1.0" ?>
<documents>
   <document>
       <documentId>4da321d6-134c-417c-9658-63090ad1862f</documentId>
       <title>test</title>
       <editUrl>https://lucid.app/lucidchart/4da321d6-134c-417c-9658-63090ad1862f/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4da321d6-134c-417c-9658-63090ad1862f/view</viewUrl>
       <version>173</version>
       <pageCount>3</pageCount>
   </document>
   <document>
       <documentId>4de6caa6-2380-4ce5-8328-15230a2e3afb</documentId>
       <title>test2</title>
       <editUrl>https://lucid.app/lucidchart/4de6caa6-2380-4ce5-8328-15230a2e3afb/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4de6caa6-2380-4ce5-8328-15230a2e3afb/view</viewUrl>
       <version>253</version>
       <pageCount>1</pageCount>
   </document>
   <document>
       <documentId>4df63d98-59f0-438a-aded-6aa20a2e3afb</documentId>
       <title>My File</title>
       <editUrl>https://lucid.app/lucidchart/4df63d98-59f0-438a-aded-6aa20a2e3afb/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4df63d98-59f0-438a-aded-6aa20a2e3afb/view</viewUrl>
       <version>32</version>
       <pageCount>1</pageCount>
   </document>
   <document>
       <documentId>4df67392-0894-44ad-987e-6ab30a2e3afb</documentId>
       <title>Mockup #1</title>
       <editUrl>https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/view</viewUrl>
       <version>221</version>
       <pageCount>1</pageCount>
   </document>
</documents>

The primary resource of the document list endpoint, enclosed in a <documents> tag.

documents Array[Document] The list of document metadata
Document Entry resource
<document>
    <documentId>4df67392-0894-44ad-987e-6ab30a2e3afb</documentId>
    <title>Mockup #1</title>
    <editUrl>https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/edit</editUrl>
    <viewUrl>https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/view</viewUrl>
    <version>221</version>
    <pageCount>1</pageCount>
</document>

Each element of the document metadata list, enclosed in a <document> tag.

documentId String ID of the document
title String The title of the document
editUrl URI A URL that can be used to open the editor for this document. Requires the user to log in.
viewUrl URI A URL that can be used to open the viewer for this document. Requires the user to log in.
version Number The current version of the document
pageCount Number The number of pages in the document
Document Error resource
<error>
   <status>401</status>
   <message>Access Denied</message>
</error>

When the document metadata or document list endpoints result in an error, an XML error response will be returned with a status code and message, enclosed in a <error> message.

status Number The HTTP status code of the error
message String The error message describing the error

Get Document Metadata

Note: A new version of this endpoint exists, try Get Document API.

curl --request GET 'https://lucid.app/documents/describe/4da321d6-134c-417c-9658-63090ad1862f'
     --header 'Authorization: Bearer <OAuth 1.0 Access Token>'
<?xml version="1.0" ?>
<documents>
   <document>
       <documentId>4da321d6-134c-417c-9658-63090ad1862f</documentId>
       <title>test</title>
       <editUrl>https://lucid.app/lucidchart/4da321d6-134c-417c-9658-63090ad1862f/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4da321d6-134c-417c-9658-63090ad1862f/view</viewUrl>
       <version>173</version>
       <pageCount>3</pageCount>
   </document>
</documents>

GET https://lucid.app/documents/describe/:id

Given a document ID, the metadata about that document can be obtained. Signed OAuth 1.0 headers are required to make this call. The call will return an HTTP status 200 if it succeeded with a response that is an XML document.

Request

GET /documents/describe/:id HTTP/1.1 Host: lucid.app Authorization: <OAuth 1.0 Access Token>

Path Parameters
id UUID
Example 6fe09818-47f0-422f-886d-2e6089696824

ID of document to be described
Response
200 Ok with Document Metadata resource containing information about the requested document.
401 Access Denied with Document Error resource
Document Editor URL

To edit a document in the user's browser, the user must be sent to the Lucidchart editor. The document metadata contains an editUrl field that the user can be directed to in order to edit their document. A third party can add to the editUrl a query parameter that will cause a button to appear in the editor with a link back to their application. Both an app and callback need to be provided and the callback should be URL encoded.

For example, if the editUrl for a document is:

https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/edit

OAuth params can also be added to this URL (see Embed the Lucidchart document list for a description of how to add OAuth 1.0 params).

To send the user to the Lucidchart editor with a return button to the example application, the user would be redirected to:

https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/edit?app=example&callback=http%3A%2F%2Fexample.com

Get Document List

curl --request GET 'https://lucid.app/documents/docs'
     --header 'Authorization: Bearer <OAuth 1.0 Access Token>'
<?xml version="1.0" ?>
<documents>
   <document>
       <documentId>4da321d6-134c-417c-9658-63090ad1862f</documentId>
       <title>test</title>
       <editUrl>https://lucid.app/lucidchart/4da321d6-134c-417c-9658-63090ad1862f/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4da321d6-134c-417c-9658-63090ad1862f/view</viewUrl>
       <version>173</version>
       <pageCount>3</pageCount>
   </document>
   <document>
       <documentId>4de6caa6-2380-4ce5-8328-15230a2e3afb</documentId>
       <title>test2</title>
       <editUrl>https://lucid.app/lucidchart/4de6caa6-2380-4ce5-8328-15230a2e3afb/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4de6caa6-2380-4ce5-8328-15230a2e3afb/view</viewUrl>
       <version>253</version>
       <pageCount>1</pageCount>
   </document>
   <document>
       <documentId>4df63d98-59f0-438a-aded-6aa20a2e3afb</documentId>
       <title>My File</title>
       <editUrl>https://lucid.app/lucidchart/4df63d98-59f0-438a-aded-6aa20a2e3afb/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4df63d98-59f0-438a-aded-6aa20a2e3afb/view</viewUrl>
       <version>32</version>
       <pageCount>1</pageCount>
   </document>
   <document>
       <documentId>4df67392-0894-44ad-987e-6ab30a2e3afb</documentId>
       <title>Mockup #1</title>
       <editUrl>https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/edit</editUrl>
       <viewUrl>https://lucid.app/lucidchart/4df67392-0894-44ad-987e-6ab30a2e3afb/view</viewUrl>
       <version>221</version>
       <pageCount>1</pageCount>
   </document>
</documents>

GET https://lucid.app/documents/docs

If a third party would like to render the document list themselves, they can obtain all the documents and the metadata about the document directly. The signed OAuth headers are required to make this call.

Request

GET /documents/docs Host: lucid.app Authorization: Bearer <OAuth 1.0 Access Token>

Response
200 Ok with Document List resource containing information about the requested document.
401 Access Denied with Document Error resource

Create New Document

Note: To programmatically create a blank document, use the new Create Blank Document API.

To create a document directly (not through the documents list), the user must be sent to the Lucidchart editor. A third party can send a user to the newDoc endpoint which will open the Lucidchart editor with a new document and cause a button to appear with a link back to their application. A callback needs to be provided and the callback should be URL encoded. OAuth params should also be added to this URL (see "Display the Lucidchart document list" for a description of how to add OAuth params).

The URL to redirect the user to has the form: https://lucid.app/api/newDoc?callback=<your callback>&oauth_signature=<oauth signature>&oauth_version=1.0&oauth_nonce=<nonce>&oauth_signature_method=HMAC-SHA1&oauth_consumer_key=<consumer_key>&oauth_token=<token>&oauth_timestamp=<timestamp>

The user will be brought to a new document in the editor and "return to " will be displayed. As with the edit endpoint, the callback will be called when the user clicks the button and the query param documentId will be added to the callback URL so the app at the callback has the ID of the document that was created.

Embed the Lucidchart document list

This approach to displaying the document list has Lucidchart render the document list as HTML. The client provides Lucidchart with a callback to send the user to when they take an action. For example, the client could have an iframe in which the Lucidchart document list is rendered. The URL is:

https://lucid.app/documents/external?callback=<URL Encoded callback>

This would prompt the user for login if they do not already have an active session that is in a cookie. OAuth parameters can be sent with the request to avoid the login prompt:

https://lucid.app/documents/external?callback=<URL Encoded callback>&oauth_signature=<oauth signature>&oauth_version=1.0&oauth_nonce=<nonce>&oauth_signature_method=HMAC-SHA1&oauth_consumer_key=<consumer_key>&oauth_token=<token>&oauth_timestamp=<timestamp>

This will display a page without the Lucidchart "chrome" that includes the users documents list as well as links to create a new document. If the user clicks on an existing document, the user will be redirected to the callback with the document id added as a query parameter. If the user creates a new document, they will be brought to the Lucidchart editor where they can create a document. There will be a button at the top of the editor to return to the client application. For example, suppose the following URL was put in an iframe in a third-party application:

Example: https://lucid.app/documents/external?callback=http%3A%2F%2Fexample.com

If the user clicked on a document in their document list with document id 1234 (or created a new document with id 1234), they would be directed to:

https://www.example.com?documentId=1234

The query parameter documentId allows the third party to know the document the user selected or created. The client can use the documentId with the "document" api to obtain metadata about the document or the images api to obtain a static image of the document.

Graph

Resources

Document resource

The primary resource of the Graph API, enclosed in a <document> tag

documentId UUID The ID of the document
title String The document's title
version Integer The current version number of the document
blocks Array[Block] The collection of blocks on the document
lines Array[Line] The collection of lines on the document
Block resource

A block enclosed in a <block> tag

id String ID of the block
class String A unique string representing the type of block (e.g. ProcessBlock)
customName String
text String The text contents of the block. If multiple text areas are present on the shape, they will be present in textAreas
textAreas Array[TextArea] The collection of all text areas on the shape.
link String If the block has a shape action, the link for the action.
field String Zero or more fields, if present.
Line resource

A line enclosed in a <line> tag

id String ID of the line
text String The text contents of the line.
endpoint1 Endpoint Information about first endpoint
endpoint2 Endpoint Information about second endpoint
Endpoint resource
style String The style of endpoint used for this endpoint
line String The ID of the line connected to this endpoint (if connected to a line)
block String The ID of the block connected to this endpoint (if connected to a block)
TextArea resource

A single textarea enclosed in a <textArea> tag

key String The textarea's unique key for the shape
value String The contents of the textarea

Get Document Graph

curl https://lucid.app/api/graph/4e8cc0f9-69f8-4d42-9993-0d5633ee25f2
     --header 'Authorization: Bearer <OAuth 1.0 Access Token>'
<document>
  <documentId>4e8cc0f9-69f8-4d42-9993-0d5633ee25f2</documentId>
  <title>Document Title</title>
  <version>70</version>
   <blocks>
     <block>
     <id>Sh6DwyXm4ZYP</id>
     <class>ERDEntityBlock</class>
     <field>Field</field>
     <field>Field</field>
   </block>
     <block>
     <id>Qn6DHVIX_Z_J</id>
     <class>ProcessBlock</class>
     <text>Process</text>
   </block>
     <block>
     <id>gx6D89zN5VyN</id>
     <class>OffPageLinkBlock</class>
     <link>ext:https://app.lucidchart.com</link>
     <text>Off-Page Link</text>
   </block>
  </blocks>
    <lines>
     <line>
     <id>Ei6DlbvpCxJz</id>
       <endpoint1>
       <style>None</style>
     </endpoint1>
      <endpoint2>
      <style>Arrow</style>
     </endpoint2>
   </line>
    <line>
     <id>Gi6DFkSl4VEu</id>
      <endpoint1>
      <style>None</style>
      <block>Sh6DwyXm4ZYP</block>
     </endpoint1>
      <endpoint2>
      <style>Arrow</style>
      <line>Ei6DlbvpCxJz</line>
     </endpoint2>
     <text>right here</text>
   </line>
  </lines>
</document>

GET https://lucid.app/api/graph/:documentId

A third party can request information about all of the blocks, lines, connections, and text fields. No styling or shape data information will be returned.

Any custom shape created or renamed after July 8th, 2013 will have a<customName> attribute as well

Request

GET /api/graph/:documentId HTTP/1.1 Host: lucid.app Authorization: Bearer <OAuth 1.0 Access Token>

Response
200 Ok text/xml with Graph resource containing information about the requested document.
400 Bad Request Graph data is unable to be retrieved for the given document.
Client side debugging

To see what the graph API will give you from a server side call, without having to make a server call, you can open a document in Chrome, open the javascript console (ctrl+shift+j) and type:

lucid.getGraphData()

This will output an XML string of the graph data for the selected blocks and lines, or if none are selected it will output the state of the entire document.

Shape library textarea keys

Unless otherwise specified, the main label for shape textareas is Title.

Flowchart Shape Textarea Name(s)
Process Text
Decision Text
Terminator Text
Predefined Process Text
Document Text
Multiple Documents Text
Manual Input Text
Preparation Text
Data (I/O) Text
Database Text
Direct Access Storage (Hard Disk) Text
Internal Storage Text
Paper Tape Text
Manual Operation Text
Delay Text
Stored Data Text
Merge Text
Connector Text
Display Text
Off-Page Link Text
Note Text
Swim Lane Lane_##
Geometric Shapes
Isosceles Triangle Text
Right Triangle Text
Pentagon Text
Hexagon Text
Octagon Text
Cross Text
Right Arrow Text
Cloud Text
Heart Text
Star Text
Left Arrow Text
Up Arrow Text
Down Arrow Text
Callout Tip
Entity Relationship Shape Textarea Name
ERD Entity Block Name, Field[row#]
ERD Entity Block 2 Name, Key[row#], Field[row#]
ERD Entity Block 3 Name, Field[row#], Type[row#]
ERD Entity Block 4 Name, Key[row#], Field[row#], Type[row#]
UML Shape Textarea Name
Class Title, Text1, Text2
Active Class Text
Simple Class Title, Text1, Text2
Interface Title, Text1, Text2
Simple Interface Title, Text1, Text2
Multiplicity Text
Package Title, Text
Constraint Text
Note Text
Text Text
Actor Text
Use Case Text, ExtensionPoints, ExtensionPointLabel
Use Case(w/ Extension Points) Text, ExtensionPoints, ExtensionPointLabel
Rectangle Container Text
Option Loop Title, Text
State/Activity State, Action
Object Text
Send Signal Text
Receive Signal Text
UML Object Text
Alternative Title, Text, Else
Entity Text
Boundary Text
Control Text
Component Text
Node Text
UML Node Text
UML Node Instance Text
Weak Entity Text
Attribute Text
Multi-valued Attribute Text
Relationship Text
Weak Relationship Text
BPMN 2.0 Shape Textarea Name(s)
Task Text
Transaction Text
Event Sub-Process Text
Call Activity Text
Start Event Text
Intermediate Event Text
End Event Text
Choreography Participant1, Name, TaskName
Conversation Text
Gateway Text
Data Object Text, Title
Data Store Text
Pool (White Box) MainText, Lane_0, Lane_1
Pool (Black Box) Text
Data Flow Shape Textarea Name(s)
External Entity Text
Process Text
YDMDFDDataStore Text
Process Number, Text
Process Text
Data Store Number, Text
Data Store Text
Org Charts Shape Textarea Name(s)
Org Chart Name, Role, Phone, Email
Value Stream Shape Textarea Name(s)
Customer/Supplier Text
Dedicated Process Title, Text
Shared Process Text, Resource
Workcell Text
Data Cell Cell_1, Cell_2, Cell_3
Inventory Text
Supermarket Cell_1, Cell_2, Cell_3
Safety/Buffer Stock Cell_1, Cell_2, Cell_3
External Shipment Airplane Text
External Shipment Forklift Text
External Shipment Truck Text
Production Control Title, Resources
Other Information Text
Heijyunka Box Title, Text1, Text2
Go See Production Text
Kaizen Burst Text
Operator Text
Timeline tw_1, tw_2, TotalVA, TotalNVA
Quality Problem Text
Production Kanban Text
Production Kanban Batch Text
Withdrawal Kanban Text
Withdrawal Kanban Batch Text
Signal Kanban Text
Shipment Arrow Text
AWS Architecture Shapes Textarea Name(s)
Amazon EC2 Title, Text
Instance Title, Text
S3 Bucket Title, Text
Bucket Title, Text
Object Title, Text
EBS Title, Text
Volume Title, Text
Snapshot Title, Text
Amazon Route 53 Title, Text
Hosted Zone Title, Text
Route Table Title, Top, Middle, Bottom
Relational Database Title, Text
Topic Text, Title
Server Rack Diagrams Shapes Textarea Name(s)
Server Rack Text
Blank Slot Text
RAID Array Text
Server Text
Ethernet Switch Text
Patch Panel Text
Router Text
Monitor Text
Slideout Keyboard Text
Power Strip Text
Power Supply Text
Bridge Text
Tape Drive Text
Circuit Diagrams Shapes Textarea Name(s)
IC Pin0, Pin1, Pin2,..., Title
Mind Mapping Shapes Textarea Name(s)
Mind Map Node Text
Process Engineering Shapes Textarea Name(s)
Vessel Text
Open Tank Text
Closed Tank Text
Storage Sphere Text
Column Text
Bag Text
Gas Cylinder Text
Gas Holder Text
Clarifier Text
Tank Text
Tray Column Text
Reaction Vessel Text
Boiler Text
Condenser Text
Cooling Tower Text
Heat Exchanger Text
Ejector/Injector Text
Compressor/Turbine Text
Motor Driven Turbine Text
Triple Fan Blades Text
Fan Blades Text
Centrifugal Pump Text
Gate Valve Text
Butterfly Valve Text
Ball Valve Text

Images

GET https://lucid.app/documents/image/:documentId/:pageNum/:width/:square

A third party can obtain an image (PNG) of a Lucidchart document.

Request

GET /documents/image/:documentId/:pageNum/:width/:square HTTP/1.1 Host: lucid.app Authorization: Bearer <OAuth 1.0 Access Token>

Path Parameters
documentId UUID

The ID of the document for which an image will be returned.
pageNum Number

The page of the document for which an image will be returned.
width Number

The width of the image to be returned.
square Number

If 1 then return square image, otherwise return an image in the original aspect ratio.
Response
200 OK image/png with PNG image data.
Example

HTTP/1.1 200 OK Content-Type: image/png <image data>

Visio

Resources

Visio resource
{
    "status": 200,
    "visio_doc_id": "7a6402bd9f26d0901b48290bada32636",
    "viewer": "https://lucid.app/visio/viewer/7a6402bd9f26d0901b48290bada32636?reg_level=professional"
}

A successful response when the Visio file is imported. The viewer field can be opened in a browser to view the imported document.

status Number Status code (200)
visio_doc_id String Document ID
viewer URI Link to view document
Visio error resource
{
    "status": 400,
    "code": "UNSUPPORTED_FILE_TYPE",
    "message": "Unsupported file type"
}

An error response will produce a machine-readable standard error code and a human-readable message describing the import error.

status Number Error status
code String Machine-readable error code
message String Human-readable error message

Import Visio File

POST https://lucid.app/visio/conversions

Import a Visio file and receive a URL to view that document in Lucidchart. On a successful import, the service returns a status of 200 with a JSON body containing the URL to the viewer.

Request
curl --request POST 'https://lucid.app/visio/conversions' \
     --header 'Authorization: Bearer <OAuth 1.0 Access Token>' \
     --form file=@/path/to/flowchart.vsd \
     --form name=flowchart.vsd \
     --form reg_level=professional
{
    "status": 200,
    "visio_doc_id": "7a6402bd9f26d0901b48290bada32636",
    "viewer": "https://lucid.app/visio/viewer/7a6402bd9f26d0901b48290bada32636?reg_level=professional"
}

POST /visio/conversions HTTP/1.1 Host: lucid.app Authorization: Bearer <OAuth 1.0 Access Token> Content-Type: multipart/form-data;boundary="boundary" --boundary Content-Disposition: form-data; name="file"; filename="<filename>" Content-Size: <size> <binary data> --boundary Content-Disposition: form-data; name="name" <name> --boundary Content-Disposition: form-data; name="reg_level" <reg_level> --boundary--

Multipart Form Data
file File

Visio file to be imported
name String

File name
reg_level String

Registration level to use if user signs up for a Lucidchart account while viewing the document. Defaults to "professional".

Valid values are:
  • free
  • professional
  • team-5
Response
200 OK application/json with JSON object containing information about the newly created document.
400 Bad Request with JSON object containing error information.
Example

HTTP/1.1 200 OK Content-Type: application/json { "status": 200, "visio_doc_id": "7a6402bd9f26d0901b48290bada32636", "viewer": "https://lucid.app/visio/viewer/7a6402bd9f26d0901b48290bada32636?reg_level=professional" }