NAV

Overview

Lucid's REST 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.

You can find example REST API applications in Lucid's repository of Sample Lucid REST Applications.

Using OAuth 2.0

In order to use any of the Lucid REST 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/.

Client Creation

Note: A detailed walkthrough is available in our OAuth 2.0 Client Creation guide.

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

  1. Create a new application on the developer portal (requires developer tools).
  2. Create an OAuth 2.0 client from within the settings of that app.
  3. Obtain an OAuth 2.0 client ID and client secret from the OAuth 2.0 client page within the app.
  4. 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.

Authorization endpoints

The token creation flow is equivalent for users and accounts, except for the authorization url. Users will also see slightly different descriptions on the consent screen for the requested scopes based on whether permission is being granted for a user token or an account token.

Most use cases are built using user tokens. If you're unsure about which is right for you, see Access Token Types and review what is required for the OAuth 2.0 endpoints you intend to use.

  • User token endpoint
    • https://lucid.app/oauth2/authorize
  • Account token endpoint
    • https://lucid.app/oauth2/authorizeAccount

Note: Users in the FedRAMP environment will use different authorization endpoints. See Lucid's FedRAMP environment.

Obtaining an access token

1. Authorization URL
https://lucid.app/oauth2/authorize ?client_id=rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf &redirect_uri=https://lucid.app/oauth2/clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect &scope=lucidchart.document.content%20offline_access%20user.profile
2. Granted Authorization Response
https://lucid.app/oauth2/clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect ?code=vtpL4oKCv3LSJ8C78FohTYN9uJUUkkZ4mQDYBucl094r
3. Token Request
curl 'https://api.lucid.co/oauth2/token' \ --request 'POST' \ --header 'Content-Type: application/json' \ --data-raw '{ "code": "vtpL4oKCv3LSJ8C78FohTYN9uJUUkkZ4mQDYBucl094r", "client_id": "rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf", "client_secret": "x678fc0SyuAbyleYq8MMtpxZMD7y4WFpPuf5a", "grant_type": "authorization_code", "redirect_uri": "https://lucid.app/oauth2/clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect" }'
4. Token Response
HTTP/1.1 200 OK Content-Type: application/json { "access_token": "oauth2-N2QyNWE3NmViMTg4NzAyMTM5ODYzNDAzZWE5NGVhNzQ0OGUzZTc2N...", "refresh_token": "oauth2-ZjU3OGVmMmVmZTEzMDI1OWU4M2M2MTI4ZjY2OWEwZDdhODE3NWVjZ...", "user_id": 1268, "client_id": "rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf", "expires_in": 3600, "expires": 1633107891024, "scopes":[ "lucidchart.document.app", "offline_access" ], "token_type": "bearer" }

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

  1. Direct the user to the appropriate authorization url in a browser with the following URL query parameters appended in order to grant access:
Parameter Description
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 provided in redirect_uri with a code query parameter. The code parameter contains a short-lived (5 minutes) authorization code that will be used to obtain an access token.
    • If using an API tool like Postman, you can use the Test Redirect Uri to retrieve the code manually while developing your integration.
  2. Make a POST request to https://api.lucid.co/oauth2/token with a Create Access Token body containing the code provided.
  3. The response will be an OAuth2 Token.

Using the access token

Request
curl 'https://api.lucid.co/users/me/profile' \ --request 'GET' \ --header 'Authorization: Bearer oauth2-Yzh4Y2Q3ZTVhY2FjYjkwOGJlZGNjNjU5NDM2NjgzZmUwMmNmMjkzM...' \ --header 'Lucid-Api-Version: 1'

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

Include a Lucid-Api-Version header with a valid version number.

Ensure the token has the correct token type and scope for the endpoint it is being used for. For example, the https://api.lucid.co/oauth2/users/me/profile endpoint requires a User token with the user.profile scope.

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

Request
curl 'https://api.lucid.co/oauth2/token' \ --request 'POST' \ --header 'Content-Type: application/json' \ --data-raw '{ "refresh_token": "oauth2-Yzh4Y2Q3ZTVhY2FjYjkwOGJlZGNjNjU5NDM2NjgzZmUwMmNmMjkzM...", "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_", "client_secret": "D-SkY5dE9m7hQApMwc9DV0iCzSRVV62MnRvG6KKOZt4vNpcw8mTVxM8T9x7qpV72xLEiw", "grant_type": "refresh_token" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "access_token": "oauth2-N2QyNWE3NmViMTg4NzAyMTM5ODYzNDAzZWE5NGVhNzQ0OGUzZTc2N...", "refresh_token": "oauth2-ZjU3OGVmMmVmZTEzMDI1OWU4M2M2MTI4ZjY2OWEwZDdhODE3NWVjZ...", "user_id": 1268, "client_id": "f90xoma5O5memgLzA_KWToMWiwBq8kHbYdhSQoxK", "expires_in": 3600, "expires": 1633107891024, "scopes":[ "lucidchart.document.app", "offline_access" ], "token_type": "bearer" }

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 access token using the refresh token that was issued alongside the previously issued access token. This refresh must be performed before the refresh token's expiration (currently 180 days). To refresh a token, make a POST request to https://api.lucid.co/oauth2/token with a Refresh Access Token body.

The response will match the format of the OAuth2 token response and contain another refresh token. This new refresh token can itself be refreshed, meaning that once a user authorizes a token with the offline_access scope, the application housing the tokens can access the user's authorized resources for an indefinite period of time. As refreshing a token does not require the user to open a browser, this indefinite access can be maintained completely programmatically (i.e. without further user intervention).

However, if it is not used, a refresh token will expire 180 days after it was created. If the refresh token expires in this way, the application will have to request access from the user again.

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 request the offline_access scope if the app will want to be able to refresh tokens.

Refresh token example script

Example refresh token script
#!python import json import requests import os from datetime import datetime, timedelta # using local file to store refresh_token FILE_NAME = './token_info.json' # oauth2 client information CLIENT_ID = '30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_' CLIENT_SECRET = 'D-SkY5dE9m7hQApMwc9DV0iCzSRVV62MnRvG6KKOZt4vNpcw8mTVxM8T9x7qpV72xLEiw' # initial refresh token generated manually INITIAL_REFRESH_TOKEN = 'oauth2-fzLTc4MjRiNGY5ZGI4MjlmZWNlZjI5OG...' # 1) Return our current token, or generate a new one if its expired. # If this is the first execution, use a manually generated token to get started def retrieve_access_token(): if (os.path.exists(FILE_NAME)): return retrieve_token_info(None) else: return retrieve_token_info(INITIAL_REFRESH_TOKEN) # 2) Retrieve the current token and refresh if its about to expire def retrieve_token_info(grantedToken): if (grantedToken is not None): return refresh_token(grantedToken) else: with open(FILE_NAME, 'r') as fileHandle: data = json.loads(fileHandle.read()) if datetime.fromisoformat(data['expiration']) > datetime.now()- timedelta(minutes=5): return data['access_token'] return refresh_token(data['refresh_token']) # 3) Refresh my token and save for future use def refresh_token(refresh_token): url = 'https://api.lucid.co/oauth2/token' body = { 'client_id': CLIENT_ID, 'client_secret': CLIENT_SECRET, 'grant_type':'refresh_token', 'refresh_token': refresh_token } request = requests.post(url, json = body) response = json.loads(request.content) save_token_info(response) return response['access_token'] # 4) Set the expiration and save the token for next time def save_token_info(token): expiration = datetime.now() + timedelta(seconds=token.get('expires_in')) token['expiration'] = expiration.isoformat() with open(FILE_NAME, 'w') as fileHandle: fileHandle.write(json.dumps(token)) # get my current or refreshed access_token access_token = retrieve_access_token() print(access_token)

To assist with the development of your Lucid integration, we have provided an example python script that illustrates the typical refresh token flow. It stores the access_token and refresh_token into a local file, and automatically refreshes them upon expiration. It is comprised of four steps:

  1. Check if the file containing a previous refresh token already exists. If it does not, we need to initiate the process by using the value provided in INITIAL_REFRESH_TOKEN to generate a token and store it locally. The INITIAL_REFRESH_TOKEN can be manually generated by following the steps at: Refreshing the access token.
  2. Retrieve the current access_token and refresh_token from the file. If the current access_token has not expired, return it and skip the remaining steps. Otherwise, move onto step 3 to refresh the access_token.
  3. Using the retrieved refresh_token, make a request to the /token endpoint with the refresh_token grant_type. Upon receiving the response, it calls step 4 to save the both tokens for future use and returns the now refreshed access_token.
  4. Before storing the data, utilize the provided expires_in value to generate an ISO format datetime so we know the absolute time our access_token will expire. Store the access_token, refresh_token, and expiration into our file.

Important: For simplicity, this script does not include response code verification or error checking. A production version of this script should handle unexpected values.

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.

Note: Some use cases do not allow custom headers (e.g. some low code frameworks). In these scenarios, the version can be added to the beginning of the path. Example: https://api.lucid.co/v1/users/me/profile.

Access token types

Access tokens can be created on behalf of a user or on behalf of an account.

User tokens

User tokens enable actions to be performed on behalf of the user that authorized their creation. If enabled, any user can authorize your app to create a user token on their behalf. With the proper scopes, a request authorized with a user token can do anything that user could do on their own behalf (e.g. create documents, edit documents, etc.).

Account tokens

Account tokens enable actions to be performed on behalf of an entire account. Only admins on an account can authorize your app to create a token on behalf of the account. Unless specifically intended, admins can't create tokens with scopes that can do things that they themselves can't do. Once created, the token is no longer associated with the user that created it. Anyone who has access to the token can use your app perform the administrative actions allowed by the scopes on the token, whether or not they would be able to do such actions without the token.

API usage

If you want your app to be able to perform any administrative actions (manage users, etc.), you'll need to use account tokens. User tokens can't be used to perform actions like managing users on an account, even if the user the token represents is an admin with permission to manage users. To perform such actions, an account token must be created. For this reason, not all scopes are valid for all token types; some scopes are only valid for user tokens, and some are only valid for account tokens.

Access Scopes

Access scopes are used to limit the permissions of an issued token. When requesting a token, the client includes a list of what actions it wants permission to perform by including the appropriate scopes. Each API includes a list of which scopes allow that action to be performed.

Some scopes contain children to provide additional access granularity. If the parent scope is given, all children permissions are included. For example, requesting lucidchart.document.app includes all permissions given in lucidchart.document.app.folder, etc.

Additional details about Oauth 2.0 scopes can be found at https://oauth.net/2/scope

Access Token Scopes

Account token only scopes are tagged with
User token only scopes are tagged with

Scope Description shown to users on the consent screen
account.info View basic information about your account (e.g., account ID and account name) .
account.user Create, view, edit, and delete users on your account.
account.user:readonly View users on your account.
account.user.transfercontent Transfer ownership of a user's resources to another user on your account.
folder Create, view, edit, share, and delete your folders. Organize your folders and their contents.
folder:readonly View any of your folders and list their contents.
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.app.picker.share.collaborator Create, view, edit, and delete collaborators and invitations of any Lucidchart document on your team or enterprise account selected for the third-party application.
lucidchart.document.app.picker.share.collaborator:readonly View collaborators and invitations of any Lucidchart document on your team or enterprise account selected for the third-party application.
lucidchart.document.app.picker.share.embed Create, view, edit, and delete embeds of any Lucidchart document on your team or enterprise account selected for the third-party application.
lucidchart.document.app.picker.share.link Create, view, edit, and delete the third party application's share links of any Lucidchart document on your team or enterprise account selected for the third-party application.
lucidchart.document.app.picker.share.link:readonly View the third party application's share links of any Lucidchart document on your team or enterprise account selected for the 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.
lucidchart.document.content.share.collaborator Create, view, edit, and delete collaborators and invitations for any of your Lucidchart documents on your team or enterprise account.
lucidchart.document.content.share.collaborator:readonly View collaborators and invitations for any of your Lucidchart documents on your team or enterprise account.
lucidchart.document.content.share.embed Create, view, edit, and delete embeds for any of your Lucidchart documents on your team or enterprise account.
lucidchart.document.content.share.link Create, view, edit, and delete the third party application's share links for any of your Lucidchart documents on your team or enterprise account.
lucidchart.document.content.share.link:readonly View the third party application's share links for any of your Lucidchart documents on your team or enterprise account.
lucidscale.document.app View, edit, and manage any Lucidscale model selected for this third-party application.
Create, view, edit, and manage any Lucidscale model within its app-specific folder.
lucidscale.document.app.folder
Create, view, edit, and manage any Lucidscale model within its app-specific folder.
lucidscale.document.app.picker View, edit, and manage any Lucidscale model selected for this third-party application.
lucidscale.document.app.picker:readonly View and download any Lucidscale model selected for this third-party application.
lucidscale.document.app.picker.share.collaborator Create, view, edit, and delete collaborators and invitations of any Lucidscale model on your team or enterprise account selected for the third-party application.
lucidscale.document.app.picker.share.collaborator:readonly View collaborators and invitations of any Lucidscale model on your team or enterprise account selected for the third-party application.
lucidscale.document.app.picker.share.embed Create, view, edit, and delete embeds of any Lucidscale model on your team or enterprise account selected for the third-party application.
lucidscale.document.app.picker.share.link Create, view, edit, and delete the third party application's share links of any Lucidscale model on your team or enterprise account selected for the third-party application.
lucidscale.document.app.picker.share.link View the third party application's share links of any Lucidscale model on your team or enterprise account selected for the third-party application.
lucidscale.document.content Create, view, edit, and delete any Lucidscale model on your account.
lucidscale.document.content:readonly View and download any Lucidscale model on your account.
lucidscale.document.content.share.collaborator Create, view, edit, and delete collaborators and invitations for any of your Lucidscale models on your team or enterprise account.
lucidscale.document.content.share.collaborator:readonly View collaborators and invitations for any of your Lucidscale models on your team or enterprise account.
lucidscale.document.content.share.embed Create, view, edit, and delete embeds for any of your Lucidscale models on your team or enterprise account.
lucidscale.document.content.share.link Create, view, edit, and delete the third party application's share links for any of your Lucidscale models on your team or enterprise account.
lucidscale.document.content.share.link:readonly View the third party application's share links for any of your Lucidscale models on your team or enterprise 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.app.picker.share.collaborator Create, view, edit, and delete collaborators and invitations of any Lucidspark board on your team or enterprise account selected for the third-party application.
lucidspark.document.app.picker.share.collaborator:readonly View collaborators and invitations of any Lucidspark board on your team or enterprise account selected for the third-party application.
lucidspark.document.app.picker.share.embed Create, view, edit, and delete embeds of any Lucidspark board on your team or enterprise account selected for the third-party application.
lucidspark.document.app.picker.share.link Create, view, edit, and delete the third party application's share links of any Lucidspark board on your team or enterprise account selected for the third-party application.
lucidspark.document.app.picker.share.link:readonly View the third party application's share links of any Lucidspark board on your team or enterprise account selected for the 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.
lucidspark.document.content.share.collaborator Create, view, edit, and delete collaborators and invitations for any of your Lucidspark boards on your team or enterprise account.
lucidspark.document.content.share.collaborator:readonly View collaborators and invitations for any of your Lucidspark boards on your team or enterprise account.
lucidspark.document.content.share.embed Create, view, edit, and delete embeds for any of your Lucidspark boards on your team or enterprise account.
lucidspark.document.content.share.link Create, view, edit, and delete the third party application's share links for any of your Lucidspark boards on your team or enterprise account.
lucidspark.document.content.share.link:readonly View the third party application's share links for any of your Lucidspark boards on your team or enterprise 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.

Deprecated 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.

Limitations

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

  • If the app is not published, only specified app collaborators can use the app with your client ID and secret. If you would like to develop an app that all Lucid users can use, refer to this publishing documentation.

  • 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 most http clients.

General OAuth 2.0 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.
invalid_scopes The provided scopes may not be valid for the requested token type.

Lucid's FedRAMP environment

Users in the FedRAMP environment will use different routes for accessing the REST API. Please see below for details

  • Any OAuth 2.0 endpoints will use api.lucidgov.app instead of api.lucid.co.
    • Example: https://api.lucidgov.app/oauth2/token
  • The authorization endpoint for user tokens is https://lucidgov.app/oauth2/authorize.
  • The authorization endpoint for account tokens is https://lucidgov.app/oauth2/authorizeAccount.
  • The test redirect uri is https://lucidgov.app/oauth2/clients/{client id}/redirect.

OAuth 2.0 Tokens

Resources

OAuth2 Token

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

OAuth2 Token Resource
{ "access_token": "oauth2-Yzh4Y2Q3ZTVhY2FjYjkwOGJlZGNjNjU5NDM2NjgzZmUwMmNmMjkzM...", "user_id": 341, "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_", "expires_in": 3600, "expires": 1605732868411, "scopes": ["lucidchart.document.app", "offline_access"], "token_type": "bearer", "refresh_token": "oauth2-AVU=-yPcwtzLkusIEnT7D9slQH4g8Ur0MdpUmpT0Z6BSMf6lmesRpTTSBGNniKd" }
Property Description
access_token String
Token to be used when making requests with OAuth 2.0 authentication
client_id String
The client ID
expires_in Number
The lifetime in seconds of the access token
expires Timestamp
Time until this token expires (expressed in milliseconds since Unix epoch)
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.

OAuth2 Introspect Token Resource
{ "active": true, "user_id": 1001, "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_", "token_type": "bearer", "scope": "document.app offline_access", "expires_in": 3500, "expires": 1605732868411 }
Property Description
active Boolean
A boolean value indicating whether or not the token is active
client_id String
The client ID
expires_in Number
The remaining lifetime in seconds of the access token
expires Timestamp
Timestamp for when this token expires (expressed in milliseconds since Unix epoch)
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

Request
curl 'https://api.lucid.co/oauth2/token' \ --request 'POST' \ --header 'Content-Type: application/json' \ --data-raw '{ "code": "vtpL4oKCv3LSJ8C78FohTYN9uJUUkkZ4mQDYBucl094r", "client_id": "f90xoma5O5memgLzA_KWToMWiwBq8kHbYdhSQoxK", "client_secret": "x678fc0SyuAbyleYq8MMtpxZMD7y4WFpPuf5a", "grant_type": "authorization_code", "redirect_uri": "https://lucid.app/oauth2/clients/f90xoma5O5memgLzA_KWToMWiwBq8kHbYdhSQoxK/redirect" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "access_token": "oauth2-N2QyNWE3NmViMTg4NzAyMTM5ODYzNDAzZWE5NGVhNzQ0OGUzZTc2N...", "refresh_token": "oauth2-ZjU3OGVmMmVmZTEzMDI1OWU4M2M2MTI4ZjY2OWEwZDdhODE3NWVjZ...", "user_id": 1268, "client_id": "f90xoma5O5memgLzA_KWToMWiwBq8kHbYdhSQoxK", "expires_in": 3469, "expires": 1633107891024, "scopes":[ "lucidchart.document.app", "offline_access" ], "token_type": "bearer" }

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

Access tokens allow a user or account to give an app permissions to make API requests on their behalf. See Access Token Types for more information.

Request Parameters
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"
redirect_uri String
The redirect URI used to get the 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 client credentials are invalid.

Refresh Access Token

Request
curl 'https://api.lucid.co/oauth2/token' \ --request 'POST' \ --header 'Content-Type: application/json' \ --data-raw '{ "refresh_token": "oauth2-Yzh4Y2Q3ZTVhY2FjYjkwOGJlZGNjNjU5NDM2NjgzZmUwMmNmMjkzM...", "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_", "client_secret": "D-SkY5dE9m7hQApMwc9DV0iCzSRVV62MnRvG6KKOZt4vNp...", "grant_type": "refresh_token" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "access_token": "oauth2-N2QyNWE3NmViMTg4NzAyMTM5ODYzNDAzZWE5NGVhNzQ0OGUzZTc2N...", "refresh_token": "oauth2-ZjU3OGVmMmVmZTEzMDI1OWU4M2M2MTI4ZjY2OWEwZDdhODE3NWVjZ...", "user_id": 1268, "client_id": "30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_", "expires_in": 3600, "expires": 1633107891024, "scopes":[ "lucidchart.document.app", "offline_access" ], "token_type": "bearer" }

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

Generate a new access token using the refresh token issued at authentication. See refreshing access tokens for more information about using refresh tokens.

Request Parameters
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 with the new access token and refresh token, as specified in OAuth2 token
403 Forbidden if the client credentials are invalid.

Introspect Access Token

Request
curl 'https://api.lucid.co/oauth2/token/introspect' \ --request 'POST' \ --data 'token=oauth2-N2QyNWE3NmViMTg4NzAyMTM5ODYzNDAzZWE5NGVhNzQ0OGUzZTc2N...' \ --data 'client_id=30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_' \ --data 'client_secret=x678fc0SyuAbyleYq8MMtpxZMD7y4WFpPuf5a'
Response
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", "expires_in": 3342, "expires": 1605732868411 }
Response with revoked/invalid token
HTTP/1.1 200 OK Content-Type: application/json { "active": false }

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

Retrieves information about the specified access or refresh token.

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

Revoke Access Token

Request
curl 'https://api.lucid.co/oauth2/token/revoke' \ --request 'POST' \ --data 'token=oauth2-N2QyNWE3NmViMTg4NzAyMTM5ODYzNDAzZWE5NGVhNzQ0OGUzZTc2N...' \ --data 'client_id=30VYbvlkqZv-SmJd7fTdpH9B9et2yqZA6Wvi5NY_' \ --data 'client_secret=x678fc0SyuAbyleYq8MMtpxZMD7y4WFpPuf5a'
Response
HTTP/1.1 200 OK Content-Length: 0

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

Revokes the specified access or refresh token, preventing the token from being used. Regardless of which is revoked, all tokens from that authorization grant will be invalid.

Request Parameters
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.

Reference

Types

Type Example Description
Boolean true An RFC7159 JSON boolean value.
String "title" An RFC7159 JSON string value.
Number 102 or 1.02E2 An RFC7159 JSON number value.
Integer 18567 An integer value formatted as an RFC7159 JSON number value.
Decimal 123.45 A decimal value formatted as an RFC7159 JSON number value.
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 See Products below.
Products

The Lucid suite contains multiple products and many APIs accept a Product parameter to dictate which to execute against. The valid Products are:

  • lucidchart
  • lucidscale
  • lucidspark

Status Codes and Errors

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

Successful Responses

HTTP Status Description
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

Error Object
{ "code": "unknownOperation", "message": "The requested operation is unrecognized or not supported for this resource" }
Error Object
{ "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
401 Unauthorized unauthorized The request token is missing, expired or invalid
403 Forbidden 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
429 Too Many Requests tooManyRequests The requests received have exceeded the allowed rate limit
500 Internal Server Error internalServerError An unknown error occurred
503 Service Unavailable The service is down for maintenance

Pagination

Request
curl 'https://api.lucid.co/users?pageSize=20&pageToken=eyJvIjoiMSIsImUiOj' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Example Link Header
Link: <https://api.lucid.co/users?pageSize=20&pageToken=eyJvIjoiMSIsImUiOjE2Mjg2OTc3OTF9>; rel="next"

Some API endpoints may return a large number of records in response to a query. To make handling large payloads scalable, Lucid's API uses pagination to limit the number of records returned in a response.

Every paginated endpoint takes two optional query parameters: pageSize and pageToken.

The pageSize parameter is used to indicate the maximum number of records returned per page. By default, each page will contain a maximum of 200 records. If a pageSize greater than 200 is requested, only 200 will be returned. Any endpoints that override this default will document it explicitly.

The pageToken is provided by the API response and acts as a pointer to the next set of records.

Responses by paginated endpoints contain a URI in the Link header called next. This URI is provided to the client to facilitate getting the next paged response and will have the same pageSize as the previous request. Page tokens are included in the next URI and should be considered opaque tokens.

Rate Limiting

Response
HTTP/1.1 429 Too Many Requests Content-Type: application/json Retry-After: 3600 { "code": "tooManyRequests", "message": "You have sent too many requests in a given amount of time." }

To protect the stability of the platform and prevent undue stress on the system, the Lucid API has a rate limiting feature (sometimes called throttling) that restricts requests when the load exceeds a configured amount.

When the number of requests received within a period of time exceeds the allowed threshold, all API requests will respond with 429 Too Many Requests. This response will include a Retry-After header containing the number of seconds until requests will be accepted again.

The rate limits are configured high enough that they should never be hit under reasonable normal usage. However, an integration should be built to handle this response, and wait at least until the Retry-After period has passed before sending further requests. Sending additional requests during the rate-limited window could extend its duration.

Rate limits are applied based on the access token type:
Account Tokens 50 requests per second
User Tokens 15 requests per second

Note: The rate limit may be hit sooner when making requests to APIs that are computationally expensive.

These limits apply to each token's principle individually. For example, an integration could make 15 requests per second using one user's token and an additional 15 requests per second using another user's token. Account and user limits are handled separately, even if the user is on the account token's account. When a request gets throttled, only requests matching the same token principle will be throttled.

Response
429 Too Many Requests with a Retry-After header indicating how many seconds to wait until re-attempting any request.

Accounts

The Account APIs enable the retrieval of information about a Lucid account.

Resources

Basic information about an account.

Account Information Resource
{ "id": 100, "name": "John's Account" }
Property Description
id Number
The unique ID for the authenticated account.
name String | null
The name assigned to the account. This field is null if no name has been assigned. Names are usually set by an admin and can be a helpful way to orient a user by informing them about which account an app will interact with.

Get Account Information

Request
curl 'https://api.lucid.co/accounts/me' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "id": 100000950, "name": "LucidCustomerAccount" }

https://api.lucid.co/accounts/me

Retrieves basic information about the authenticated account.

Valid Access Token Types

Account
User

Valid Access Scopes

account.info

Response
200 Ok with an Account information resource containing information about the authenticated account.

Collaboration

Collaborators are users who have access to view, edit, or manage access to a document or folder. Each collaborator has a Collaborator Role which determines what actions they can execute on the document or folder they have access to.

Collaborator grants can be given to both users and groups of users. Group membership is managed by admins through the UI or the Group APIs. When a group is made a collaborator of a document or folder, all users who are actively in that group will have that level of access to the document. Users being added to or removed from a group will result in those users' access to documents or folders being updated in real time. Any users who have access to a document or folder directly and through a group will see their effective access as the greater of the two collaborator grants.

Collaboration access is inherited through folders. If a user is a collaborator on a document directly, that direct access will always take priority. Otherwise, the user's effective access level will be the greatest access from all folders the document is a descendent of in the folder tree, recursively.

It is possible for shortcuts to a document to live in other folders. These shortcut document entries do not grant any collaborator access, no matter what access a user has to the folder containing it.

Collaborator Roles

Roles determine what actions a collaborator can execute on a document or folder. Collaborators with a role on a document only have the specified level of access to just that one document, but collaborators on a folder have that level of access to all of the folder's contents, recursively.

Role Description
owner The owner of the document or folder, with all permissions. Cannot be changed by Collaborator APIs
editandshare View, comment on, edit, and control which users can access the document or folder
edit View, comment on, and edit the document or folder
comment View the document or folder. Leave comments on the document
view View the document or folder. View basic information about the contents of a folder

Documents

Resources

Document User Collaborator
Document User Collaborator
{ "documentId": "110808fd-4553-4316-bccf-4f25ff59a532", "userId": 1298, "role": "owner", "created": "2021-08-24T22:42:28Z" }
Property Description
documentId UUID
Document ID
userId Number
User ID
role Role
The Collaborator Role this user has on the document
created DateTime
Date and time when the collaboration was created

Get Document User Collaborator

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/users/1298' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "documentId": "001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "userId": 1298, "role": "owner", "created": "2021-08-24T22:42:28Z" }

https://api.lucid.co/documents/:id/shares/users/:userId

Gets information about the user's collaboration access to the provided document.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content.share.collaborator:readonly lucidchart.document.app.picker.share.collaborator:readonly lucidchart.document.app.folder lucidscale.document.content.share.collaborator:readonly lucidscale.document.app.picker.share.collaborator:readonly lucidscale.document.app.folder lucidspark.document.content.share.collaborator:readonly lucidspark.document.app.picker.share.collaborator:readonly lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document.
userId Number
ID of the user to retrieve collaborator settings for.
Response
200 Ok with a Document User Collaborator Resource containing information about the user's collaboration settings.
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted, or does not exist.
404 Not Found when a user with the specified ID can not be found or does not have collaborator access to the document.

List Document User Collaborators

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/users' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' }
Response
HTTP/1.1 200 OK Content-Type: application/json Link: https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/users?pageSize=20&pageToken=eyJvIjoiMSIsImUiOjE2Mjg2OTc3OTF9; rel="next" [ { "documentId": "001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "userId": 1001, "role": "editandshare", "created": "2021-01-11T20:05:00Z", }, { "documentId": "001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "userId": 1002, "role": "view", "created": "2021-01-11T20:07:03Z", }, ]

https://api.lucid.co/documents/:id/shares/users

A paginated endpoint that retrieves information about all collaborators on the provided document. For more information, see Pagination.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content.share.collaborator:readonly lucidchart.document.app.picker.share.collaborator:readonly lucidchart.document.app.folder lucidscale.document.content.share.collaborator:readonly lucidscale.document.app.picker.share.collaborator:readonly lucidscale.document.app.folder lucidspark.document.content.share.collaborator:readonly lucidspark.document.app.picker.share.collaborator:readonly lucidspark.document.app.folder

Request Parameters

Note: See Pagination for optional pagination parameters.

Path
id UUID
ID of the document.
Response
200 Ok with an array of Document User Collaborator Resources for the document's collaborators.
403 Forbidden if the token does not have permission to the document, or if the document has been deleted or does not exist.

Create/Update Document User Collaborator

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/users/1268' \ --request 'PUT' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \ --data-raw '{ "role": "comment" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "documentId": "001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "userId": 1298, "role": "comment", "created": "2021-08-24T22:42:28Z" }

https://api.lucid.co/documents/:id/shares/users/:userId

Update the collaborator role for a user. If the user did not have access to the document before, they will be granted access and a new Document User Collaborator Resource will be created.

Important: Collaborators cannot be given the role owner, and the role of the document's owner can not be modified.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content.share.collaborator lucidchart.document.app.picker.share.collaborator lucidchart.document.app.folder lucidscale.document.content.share.collaborator lucidscale.document.app.picker.share.collaborator lucidscale.document.app.folder lucidspark.document.content.share.collaborator lucidspark.document.app.picker.share.collaborator lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document.
userId Number
ID of the user whose role to create or modify.
Body
role Role
The Collaborator Role to assign to the user for this document.
Response
200 Ok when updating an existing Document User Collaborator. Contains the updated Document User Collaborator Resource.
201 Created when creating a new Document User Collaborator. Contains the new Document User Collaborator Resource.
403 Forbidden if the token does not have permission to the document, or if the document has been deleted or does not exist.

Delete Document User Collaborator

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/users/1268' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \
Response
HTTP/1.1 204 No Content Content-Length: 0

https://api.lucid.co/documents/:id/shares/users/:userId

Revoke all collaborator access to a document for the given user. The user may still have access to the document through other means such as shared folders.

Important: Cannot be used to revoke collaborator access to the document owner.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content.share.collaborator lucidchart.document.app.picker.share.collaborator lucidchart.document.app.folder lucidscale.document.content.share.collaborator lucidscale.document.app.picker.share.collaborator lucidscale.document.app.folder lucidspark.document.content.share.collaborator lucidspark.document.app.picker.share.collaborator lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document.
userId Number
ID of the user to delete collaborator settings for.
Response
204 No Content the user's collaborator record on the document was successfully deleted.
403 Forbidden
  • if the token does not have permission to the document, or if the document has been deleted or does not exist.
  • when attempting to revoke the collaboration for the document owner.

Folders

Resources

Folder User Collaborator
Folder User Collaborator
{ "folderId": 10745, "userId": 89763, "role": "edit", "created": "2038-01-19T03:14:08Z" }
Property Description
folderId Number
Folder ID
userId Number
User ID
role Role
The Collaborator Role this user has on the folder
created DateTime
Date and time when the collaboration was created
Folder Group Collaborator
Folder Group Collaborator
{ "folderId": 10745, "groupId": 200363, "role": "edit", "created": "2038-01-19T03:14:08Z" }
Property Description
folderId Number
Folder ID
groupId Number
Group ID
role Role
The Collaborator Role this group has on the folder
created DateTime
Date and time when the collaboration was created

Get Folder User Collaborator

Request
curl 'https://api.lucid.co/folders/2304/shares/users/1298' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "folderId": 2304, "userId": 1298, "role": "owner", "created": "2021-08-24T22:42:28Z" }

https://api.lucid.co/folders/:id/shares/users/:userId

Get information about a user's direct collaborator access to a given folder. A user having access to a folder through one of the folder's ancestors will not be shown through this API.

Valid Access Token Types

User

Valid Access Scopes

folder:readonly

Request Parameters
Path
id Number
ID of the folder.
userId Number
ID of the user to retrieve collaborator settings for.
Response
200 Ok with a Folder User Collaborator Resource containing information about the user's collaboration settings.
403 Forbidden if the app making the request does not have permission to the folder, or if the folder has been deleted, or does not exist.
404 Not Found when a user with the specified ID can not be found or does not have collaborator access to the folder.

List Folder User Collaborators

Request
curl 'https://api.lucid.co/folders/1211/shares/users' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json Link: https://api.lucid.co/folders/1211/shares/users?pageSize=20&pageToken=eyJvIjoiMSIsImUiOjE2Mjg2OTc3OTF9; rel="next" [ { "folderId": 1211, "userId": 1001, "role": "editandshare", "created": "2021-01-11T20:05:00Z", }, { "folderId": 1211, "userId": 1002, "role": "view", "created": "2021-01-11T20:07:03Z", }, ]

https://api.lucid.co/folders/:id/shares/users

Lists all users that have direct collaborator access to a given folder. A user having access to a folder through one of the folder's ancestors will not be shown through this API.

This endpoint is paginated. For more information, see Pagination.

Valid Access Token Types

User

Valid Access Scopes

folder:readonly

Request Parameters

Note: See Pagination for optional pagination parameters.

Path
id Number
ID of the folder.
Response
200 Ok with an array of Folder User Collaborator Resources for the folder's collaborators.
403 Forbidden if the token does not have permission to the folder, or if the folder has been deleted or does not exist.

Create/Update Folder User Collaborator

Request
curl 'https://api.lucid.co/folders/8211/shares/users/1268' \ --request 'PUT' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \ --data-raw '{ "role": "comment" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "folderId": 8211, "userId": 1268, "role": "comment", "created": "2021-08-24T22:42:28Z" }

https://api.lucid.co/folders/:id/shares/users/:userId

Update the collaborator role for a user. If the user did not have access to the folder before, they will be granted access and a new Folder User Collaborator Resource will be created.

Important: Collaborators cannot be given the role owner, and the role of the folder's owner can not be modified.

Valid Access Token Types

User

Valid Access Scopes

folder

Request Parameters
Path
id Number
ID of the folder.
userId Number
ID of the user whose role to create or modify.
Body
role Role
The Collaborator Role to assign to the user for this folder.
Response
200 Ok when updating an existing Folder User Collaborator. Contains the updated Folder User Collaborator Resource.
201 Created when creating a new Folder User Collaborator. Contains the new Folder User Collaborator Resource.
403 Forbidden if the token does not have permission to the folder, or if the folder has been deleted or does not exist.

Delete Folder User Collaborator

Request
curl 'https://api.lucid.co/folders/3910/shares/users/1268' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \
Response
HTTP/1.1 204 No Content Content-Length: 0

https://api.lucid.co/folders/:id/shares/users/:userId

Revoke all collaborator access to a folder for the given user. The user may still have access to the folder through other means such as shared folders.

Important: Cannot be used to revoke collaborator access to the folder owner.

Valid Access Token Types

User

Valid Access Scopes

folder

Request Parameters
Path
id Number
ID of the folder.
userId Number
ID of the user to delete collaborator settings for.
Response
204 No Content the user's collaborator record on the folder was successfully deleted.
403 Forbidden
  • if the token does not have permission to the folder, or if the folder has been deleted or does not exist.
  • when attempting to revoke the collaboration for the folder owner.

Get Folder Group Collaborator

Request
curl 'https://api.lucid.co/folders/13562/shares/groups/200951' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 Ok Content-Type: application/json { "folderId": 13562, "groupId": 200951, "role": "editandshare", "created": "2022-04-29T11:22:59Z" }

https://api.lucid.co/folders/:id/shares/groups/:groupId

Get information about a group's direct collaborator access to a given folder. A group having access to a folder through one of the folder's ancestors will not be shown through this API.

Valid Access Token Types

User

Valid Access Scopes

folder folder:readonly

Request Parameters
Path
id Number
Folder ID
groupId Number
Group ID
Response
200 Ok with a Folder Group Collaborator Resource containing information about the group's collaboration access on the folder
403 Forbidden if the token does not have access to the folder, or if the folder has been deleted or does not exist
404 Not Found when the group does not have direct collaborator access to the folder

List Folder Group Collaborators

Request
curl 'https://api.lucid.co/folders/13562/shares/groups' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 Ok Content-Type: application/json Link: https://api.lucid.co/folders/13662/shares/groups?pageSize=20&pageToken=eyJvIjoiMSIsImUiOjE2Mjg2OTc3OTF9; rel="next" [ { "folderId": 13562, "groupId": 200951, "role": "editandshare", "created": "2022-04-29T11:22:59Z" }, { "folderId": 13562, "groupId": 200954, "role": "view", "created": "2020-03-14T01:51:03Z" } ]

https://api.lucid.co/folders/:id/shares/groups

Lists all groups that have direct collaborator access to a given folder. A group having access to a folder through one of the folder's ancestors will not be shown through this API.

This endpoint is paginated. For more information, see Pagination.

Valid Access Token Types

User

Valid Access Scopes

folder folder:readonly

Request Parameters

Note: See Pagination for optional pagination parameters.

Path
id Number
Folder ID
Response
200 Ok with an array of Folder Group Collaborator Resources containing the folder's collaborators, as well as Pagiation headers
403 Forbidden if the token does not have access to the folder, or if the folder has been deleted or does not exist

Create/Update Folder Group Collaborator

Request
curl 'https://api.lucid.co/folders/13562/shares/groups/200951' \ --request 'PUT' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \ --data-raw '{ "role": "edit" }'
Response
HTTP/1.1 200 Ok Content-Type: application/json { "folderId": 13562, "groupId": 200951, "role": "edit", "created": "2022-05-03T12:29:51Z" }

https://api.lucid.co/folders/:id/shares/groups/:groupId

Grant a group direct collaborator access to a given folder, or update the group's role on the folder. See the Collaborator section overview for details about how folder and document access to groups and users are inherited and interact with each other to become a user's effective access to a folder or document.

Valid Access Token Types

User

Valid Access Scopes

folder

Request Parameters
Path
id Number
Folder ID
groupId Number
Group ID
Body
role Role
The Collaborator Role to assign to the group for this folder
Response
200 Ok when updating an existing Folder Group Collaborator. Contains the updated Folder Group Collaborator Resource
201 Created when creating a new Folder Group Collaborator. Contains the new Folder Group Collaborator Resource
403 Forbidden if the token does not have permission to the folder, or if the folder or group have been deleted or do not exist

Delete Folder Group Collaborator

Request
curl 'https://api.lucid.co/folders/13562/shares/groups/200951' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \
Response
HTTP/1.1 204 No Content Content-Length: 0

https://api.lucid.co/folders/:id/shares/groups/:groupId

Revoke any direct collaborator access a group has to the given folder. See the Collaborator section overview for details about how the group may still have access to the folder through other means.

Valid Access Token Types

User

Valid Access Scopes

folder

Request Parameters
Path
id Number
Folder ID
groupId Number
Group ID
Response
204 No Content the groups's collaborator record on the folder was successfully deleted
403 Forbidden the token does not have permission to the folder, or if the folder has been deleted or does not exist

Documents

The Documents APIs allow for the manipulation of all types of Lucid diagrams. For simplicity of use, all Lucid diagrams are accessible under the same endpoints. Where applicable, the Document APIs take a Product field to identify which product type to manipulate.

Resources

Document
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, "created": "2019-04-22T13:47:23Z", "creatorId": 12345, "lastModified": "2020-06-26T16:29:37Z", "lastModifiedUserId": 54321, "customAttributes": [...], "customTags": ["in progress"], "product": "lucidchart", "status": "COMPLETE", "trashed": null, "parent": null, "owner": { "id": "123456", "type": "user", "name": "John Doe" } }

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

Property Description
documentId UUID
Unique ID of the document
title String
Title of the document
editUrl URI
Link to edit the document
viewUrl URI
Link to view the document
version Number
Most recent version
pageCount Number
Number of pages within the document
canEdit Boolean
If requesting user can edit the document
created DateTime
Date and time of when the document was created
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
customAttributes Array[CustomAttribute]
List of any custom attributes belonging to the document
Populated for Enterprise Accounts only
Learn more about Custom Attributes here
customTags Array[String]
List of any custom tags assigned to the document
product Product
The Lucid suite product of the document
status String
Current assigned status of the document
Learn more about Status here
trashed DateTime
If defined, the timestamp when the document was moved to the trash
parent Number
ID of the parent folder
owner Document Owner Resource
Information about the owner of the document. This data is only returned from the Get Document endpoint.
Custom Attribute
Custom Attribute Resource
{ "type": "singleLineText", "name": "Sample Label", "value": "This is a sample value for a custom document attribute." }
Custom Attribute Resource -- Unset Attribute Value
{ "type": "singleLineText", "name": "Sample Label", "value": null }
Custom Attribute Resource -- Hierarchical Dropdown Attribute
{ "type": "hierarchicalDropdown", "name": null, "value": [ { "name": "Country", "value": "USA" }, { "name": "City", "value": "New York" } ] }

Object representing a custom attribute value for a document

Note: Custom Attributes will only populate for accounts with an enterprise license.

Property Description
type Attribute Type
The custom attribute type
name String
Title of the custom attribute. hierarchicalDropdown attributes do not have names.
value Attribute Value
The value assigned to the custom attribute. The type of this value is determined by the Attribute Type
Custom Attribute Types

Different possible types for a CustomAttribute. The corresponding value of the attribute depends on what the Attribute Type is.

Attribute Type Corresponding Value Type Description
singleLineText String Inputted text as a single line
multiLineText String Inputted text as multiple lines
singleSelectDropdown String Selected option from the dropdown box
multiSelectDropdown Array[String] Array of all selected options from the multi-select dropdown box
webLink String Inputted url
numericalRange Number Inputted numerical value
hierarchyDropdown Array[DataPair] Array of DataPair resources ordered by the hierarchy definition (top level hierarchy dropdown values are first)
Document Content
Document Content Resource
{ "id": "8e7b19ec-27ff-40e3-beb8-03f51b1661b2", "title": "document title", "product": "lucidchart", "pages": [...], "data": { "collections": [...] } }

Object representing the contents of a Lucidchart document

Property Description
id UUID
Document ID
title String
Title of the document
product Product
The Lucid suite product of the document
pages Array[Page]
Array of Page resources on the document
data Data
Data contained on the document
Page
Page Resource
{ "id": "YGcM5DNywbTK", "title": "document page title", "index": 0, "items": { "shapes": [...], "lines": [...], "groups": [...], "layers": [...] }, "customData": [...], "linkedData": [...] }

Object representing a single page of a Lucidchart document.

Property Description
id String
Page ID
title String
Title of the page
index Integer
0-Based index of the page in the document
items Items
Shapes, Lines, Groups, and Layers on the page
customData Array[DataPair]
Array of Data Pair resources linked to the page
linkedData Array[LinkedData]
Array of Linked Data resources linked to the page
Items
Items Resource
{ "shapes": [...], "lines": [...], "groups": [...], "layers": [...] }

Individual shapes, lines, groups, and layers all contain a unique ItemId identifying the object.

Property Description
shapes Array[Shape]
Array of Shape resources
lines Array[Line]
Array of Line resources
groups Array[Group]
Array of Group resources
layers Array[Layer]
Array of Layer resources
Shape
Shape Resource
{ "id": "VTAu-oQASzul", "class": "ProcessBlock", "textAreas": [...], "customData": [...], "linkedData": [...] }

Object representing a shape placed on a page of a document. Note that the ItemId of a shape is unique across all groups, layers, shapes, and lines.

Property Description
id ItemId
Shape ID
class String
A unique string representing the type of the shape (e.g. ProcessBlock)
textAreas Array[TextArea]
Array of Text Area resources on the shape
customData Array[DataPair]
Array of Data Pair resources linked to the shape
linkedData Array[LinkedData]
Array of Linked Data resources linked to the shape

Important: The class of a shape is not guaranteed to be stable and may rarely change.

Line
Line Resource
{ "id": "VTAuwAeC0_R1", "endpoint1": { "style": "None", "connectedTo": "VTAuo_Y56.q~" }, "endpoint2": { "style": "Arrow", "connectedTo": "VTAuCB8~evzW" }, "textAreas": [...], "customData": [...], "linkedData": [...] }

Object representing a line on the page of a document. Note that the ItemId of a line is unique across all groups, layers, shapes, and lines.

Property Description
id ItemId
Line ID
endpoint1 Endpoint
First endpoint of a line
endpoint2 Endpoint
Second endpoint of a line
textAreas Array[TextArea]
Array of Text Area resources on the line
customData Array[DataPair]
Array of Data Pair resources linked to the line
linkedData Array[LinkedData]
Array of Linked Data resources linked to the line
Layer
Layer Resource
{ "id": "VTAu-dl6qtyx", "name": "Layer 1", "members": ["VTAuCB8~evzW", "VTAuo_Y56.q~"], "customData": [...], "linkedData": [...] }

Object representing a layer on the page of a document. Note that the ItemId of a layer is unique across all groups, layers, shapes, and lines.

Property Description
id ItemId
Layer ID
name String
The name of the layer
members Array[ItemId]
Array of IDs of shapes, lines, & groups contained within the layer
customData Array[DataPair]
Array of Data Pair resources linked to the layer
linkedData Array[LinkedData]
Array of Linked Data resources linked to the layer
Group
Group Resource
{ "id": "VTAu-dl6qtyx", "members": ["VTAuCB8~evzW", "VTAuo_Y56.q~"], "customData": [...], "linkedData": [...] }

Object representing a group on the page of a document. Note that the ItemId of a group is unique across all groups, layers, shapes, and lines.

Property Description
id ItemId
Group ID
members Array[ItemId]
Array of IDs of shapes, lines, & groups contained within the group
customData Array[DataPair]
Array of Data Pair resources linked to the group
linkedData Array[LinkedData]
Array of Linked Data resources linked to the group
Endpoint
Endpoint Resource
{ "style": "Arrow", "connectedTo": null }

Object representing the endpoint of a Line.

Property Description
style String
Line end style
connectedTo ItemId
Id of shape or line the line is connected to
Text Area
Text Area Resource
{ "label": "Text", "text": "Start here" }

Object representing a text area on a Shape or Line.

Property Description
key String
Text area label
value String
Text displayed in the text area. This is plain text. All formatting has been removed & formulas evaluated.
Data Pair
Data Pair Resource
{ "key": "Property 1", "value": "Value 1" }

Object representing a key-value pair of data.

Property Description
key String
Custom data key
value String
Custom data value
Linked Data
Linked Data Resource
{ "collection_id": "ABAuwlf2BTy8", "data": [...], "primaryKeyValue": "Pkey Value" }

Object representing data linked to a resource on a document.

Property Description
collection_id String
Id of the collection containing the data
data Array[DataPair]
Key-value pairs from the dataset
primaryKeyValue String
The value of the primary key of the dataset
Data
Data Resource
{ "collections": [...] }

Object representing an array of Collections on a document.

Property Description
collections Array[Collection]
Array of collections
Collection
Collection Resource
{ "id": "ABAuwlf2BTy8", "name": "Collection 1", "primaryKey": ["PKey 1"] }

A collection is a container inside of a source of data. 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.

Property Description
id String
Id of the collection
name String
Collection name
primaryKey Array[String]
The primary key column name
Bootstrap Data
Bootstrap Data Resource
{ "packageId": "74672098-cf36-492c-b8e6-2c4233549cd3", "extensionName": "sheets-adapter", "minimumVersion": "1.4.0", "data": { "a": 1, "b": 2 } }

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

Property Description
packageId String
Id of the extension package which will consume this data
extensionName String
Name of the editor extension which will consume this data.
Note: this is the name field of an editor extension found in your manifest.json file.
minimumVersion String
Minimum version of the extension package which will consume this data
data Map[String, String]
Data to provide to the extension package
Document Owner Resource
Document Owner Resource
{ "id": 123456, "type": "user", "name": "John Doe" }

This data is returned in the Document Resource data from the Get Document endpoint. This data contains information about the owner of the document.

Property Description
id Number
Id of either the user or the account, depending on the type of the document user resource.
type String
Specifies if the owner resource is referring to a user or an account. Value will be either "user" or "account".
name String
Full name of the user that owns this document. This field is excluded if this document is owned by an account.

Document Access

For each product, there are three branches of document-related scopes: {product}.document.content, {product}.document.app.folder, and {product}.document.app.picker.

  • The document.content scopes are simplest. They grant access to all of the user's documents.
  • The document.app.folder scopes create a folder dedicated to your app, and grants access to all documents and subfolders within it.
  • The document.app.picker scopes are the most restrictive. Initially, they don't grant access to any documents. Instead, when your app needs access to a document, you show the user the document picker, and gain access to specific documents selected by the user. Once the user has granted your app access to a document once, your app will retain access to it until the user revokes that access.

Get Document

Request
curl 'https://api.lucid.co/documents/6fe09818-47f0-422f-886d-2e6089696824' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Accept: application/json'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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, "created": "2019-04-22T13:47:23Z", "creatorId": 12345, "lastModified": "2020-06-26T16:29:37Z", "lastModifiedUserId": 54321, "customTags": ["in progress"], "product": "lucidchart", "status": "COMPLETE", "parent": null, "owner": { "id": 123456, "type": "user", "name": "John Doe" } }

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

Retrieves information about the requested document, including information about the document owner in a Document Owner Resource if certain conditions are met. Requires at least read only access to the requested document.

The document owner information is only returned if the requesting user has view access and the document is unpublished. If the document is published, the user must be at least a collaborator on the document. If the document is owned by a user, information about the user is returned. If the document is in an enclosing project/team folder, information about the account is returned instead.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.content:readonly lucidchart.document.app.picker:readonly lucidchart.document.app.folder lucidscale.document.content:readonly lucidscale.document.app.picker:readonly lucidscale.document.app.folder lucidspark.document.content:readonly lucidspark.document.app.picker:readonly lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the 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, or if the document has been deleted or does not exist.

Create Document

Request
curl 'https://api.lucid.co/documents' \ --request 'POST' \ --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", "parent": 173, "template": "023c0ebd-744c-4a44-87b7-f93e07390607", "extensionBootstrapData": { "packageId": "74672098-cf36-492c-b8e6-2c4233549cd3", "extensionName": "sheets-adapter", "minimumVersion": "1.4.0", "data": { "a": 1, "b": 2 } } }'
Response
HTTP/1.1 201 Created Content-Type: application/json { "documentId": "110808fd-4553-4316-bccf-4f25ff59a532", "title": "new 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, "created": "2020-06-26T16:29:37Z", "creatorId": 12345, "lastModified": "2020-06-26T16:29:37Z", "lastModifiedUserId": 54321, "customTags": ["in progress"], "product": "lucidchart", "status": "COMPLETE", "parent": 173 }

https://api.lucid.co/documents

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

Valid Access Token Types

User

Valid Access Scopes

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

Document Creation Location

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

Request Parameters
Body
title String
Title that should be given to the newly created document.
product Product
Product used to create the new document.
parent Number
ID of the folder to create the new document in.
template UUID
ID of the document or template to create from.
extensionBootstrapData Bootstrap Data
Bootstrap data for a specific extension package.
Response
201 Created with Document resource containing information about the newly created document.
403 Forbidden
  • if the user doesn't have access to or permissions to create within the specified parent folder.
  • if the user doesn't have permissions to access the specified template to create from.
  • if the token authorizing the request has the document.app scope with a specified parent folder that is outside the app folder's folder tree.

Copy Document

A document can be copied via the Create Document endpoint. To do so, include the documentId of the desired document to be copied as the template parameter. Note that a document's collaborator permissions are not copied.

Import Document

Request
curl 'https://api.lucid.co/documents' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --form 'file=@location/file.xml;type=x-application/vnd.lucid.drawio'\ --form 'title=My new document'\ --form 'parent=1234'
Response
HTTP/1.1 201 Created Content-Type: application/json { "documentId": "110808fd-4553-4316-bccf-4f25ff59a532", "title": "My new document", "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, "created": "2020-06-26T16:29:37Z", "creatorId": 12345, "lastModified": "2020-06-26T16:29:37Z", "lastModifiedUserId": 54321, "customTags": ["in progress"], "product": "lucidchart", "status": "COMPLETE", "parent": 1234 }

https://api.lucid.co/documents

Imports an external non-Lucid file as a new document within Lucid. The file contents and type must be provided within form-data, with the supported types listed in the below chart.

Note: See Document Creation Location for information about the location of created documents. Note: This endpoint has a per account rate limit of 50 requests per minute.

Valid Import Types
Vendor Extensions Type Product
standard (JSON) .lucid x-application/vnd.lucid.standardImport Lucidchart/Lucidspark
draw.io .drawio
.xml		 x-application/vnd.lucid.drawio Lucidchart
visio .vsdx
.vdx		 x-application/vnd.lucid.visio Lucidchart
gliffy .gliffy
.gon
.gxml		 x-application/vnd.lucid.gliffy Lucidchart
board .pdf x-application/vnd.lucid.board Lucidspark

Important:
The board import type only accepts pdfs that are exports of digital whiteboards.
The board import type can only be authorized by users with a Lucidspark Enterprise license.
The board import type is experimental and importing the same board may produce varying results over time.

Note: For more information on the standard import type, see our extensive documentation here.

Valid Access Token Types

User

Valid Access Scopes

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

Request Parameters
Multipart Form Data
file Binary
The file data as multipart/form-data. Generally, the application or client used to make the API request will handle reading in the file data and setting the multi-part boundaries.
type String
The type of file provided for import. See Valid Import Types for options.
product Product
Product used to create the new document (only required for the Lucid Standard Import).
title String
Title that should be given to the newly created document
parent Number
ID of the folder to create the new document in.
Response
201 Created with Document resource containing information about the newly created document.
403 Forbidden
  • if the user doesn't have access to or permissions to create within the specified parent folder.
  • if the token authorizing the request has the document.app scope with a specified parent folder that is outside the app folder's folder tree.
  • if the token does not have the correct scope for the import type.
  • if the token requesting a board import does not have a Lucidspark Enterprise License.
415 Unsupported Media Type The file type provided is not supported.

Export Document

Request
curl 'https://api.lucid.co/documents/7b36f31b-e4c0-4f2b-889f-e309c4108505?page=1&crop=10,30,30,7' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Accept: image/png;dpi=50'
Response
HTTP/1.1 200 OK Content-Type: image/png; dpi=50 -- <binary image data> --

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

Note: This endpoint has a per account rate limit of 75 requests per 5 seconds.

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

Export Document Format

The format of the exported document is set via the Accept header. This header contains up to two parts, separated by a semicolon:

  • A prefix stating which type of image you would like the document exported as. Options are:
    • image/jpeg
    • image/png
  • Optionally, you can also supply the dots per inch (DPI) you want the exported image to have. If this value is not provided, a default of 170 will be used.
Accept Header Value Result
Accept: image/png;dpi=256 A png image with a DPI of 256
Accept: image/jpeg A jpeg image with a DPI of 170
Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content:readonly lucidchart.document.app.folder lucidchart.document.app.picker:readonly lucidscale.document.content:readonly lucidscale.document.app.folder lucidscale.document.app.picker:readonly lucidspark.document.content:readonly lucidspark.document.app.folder lucidspark.document.app.picker:readonly

Request Parameters
Headers
Accept The format of the document to export. See Export document format for options.
Path
id UUID
ID of the document to be exported.
Query
page Number
1-Based page index of the document to export. Defaults to first page.
pageId String
Specific page of the document to export. Only a single page is allowed
Example pageId=J~65X_X714o2.
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

Note: Only a single page or pageId can be provided.

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.
400 Bad Request More then one page and/or pageId was provided.
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted or does not exist.
404 Not Found The specified page or pageID could not be found.
406 Not Acceptable The specified image type is not supported.
429 Too Many Requests if the account makes more than 75 requests in 5 seconds

Trash Document

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/trash' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json' \
Response
HTTP/1.1 204 NO_CONTENT Content-Length: 0

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

Moves the specified document to the trash for the requesting user. If the document is shared or part of a team folder, other users will still have access to the document. Requires the user to be the owner of the requested document or have the appropriate team folder permissions.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content lucidchart.document.app.folder lucidscale.document.content lucidscale.document.app.folder lucidspark.document.content lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document to be moved to the trash
Response
204 No Content when the document is successfully moved into the trash or is already trashed
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted or does not exist.

Search Documents

Request
curl 'https://api.lucid.co/documents/search' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": ["lucidchart", "lucidspark"], "createdStartTime": "2020-12-31T15:00:00Z", "createdEndTime": "2021-01-30T15:00:00Z", "lastModifiedAfter": "2021-06-01T15:00:00Z", "keywords": "my document" }'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "documentId": "110808fd-4553-4316-bccf-4f25ff59a532", "title": "My document", "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, "created": "2020-12-31T18:47:23Z", "creatorId": 12345, "lastModified": "2021-06-25T16:29:37Z", "lastModifiedUserId": 54321, "customTags": ["in progress"], "product": "lucidchart", "status": "COMPLETE", "parent": 1234 }, { "documentId": "ace0736e-83bc-41bc-b5f6-ce0202b5e8bf", "title": "My document 2", "editUrl": "https://lucid.app/lucidspark/ace0736e-83bc-41bc-b5f6-ce0202b5e8bf/edit", "viewUrl": "https://lucid.app/lucidspark/ace0736e-83bc-41bc-b5f6-ce0202b5e8bf/view", "version": 33, "pageCount": 1, "canEdit": false, "created": "2021-01-22T14:31:57Z", "creatorId": 12345, "lastModified": "2021-11-25T13:34:37Z", "lastModifiedUserId": 54321, "customTags": ["in progress"], "product": "lucidspark", "status": "COMPLETE", "parent": 1234 } ]

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

Retrieves information about documents that the authenticated user has at least read only access to. Additional filtering parameters may be added.

This endpoint is paginated. For more information, see Pagination.

Note: This endpoint has a per account rate limit of 300 requests per 5 seconds.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content:readonly lucidscale.document.content:readonly lucidspark.document.content:readonly

Request Parameters
Body
product Array[Product]
Array of Lucid suite products to filter by. Default value assumes all valid products for the given scopes.
createdStartTime DateTime
Date and time to filter documents that have been created after. Default value assumes the beginning of time.
createdEndTime DateTime
Date and time to filter documents that have been created before. Default value assumes the current instant of time.
lastModifiedAfter DateTime
Date and time to filter documents that have been modified after. Default value assumes the beginning of time.
keywords String
Keywords to search against document content and titles. This field is truncated to 400 characters. When provided, results will be sorted by relevance to keyword search.

Note: This endpoint accepts RFC-3339 datetimes with timezones, but all datetimes will be translated to UTC before filtering and all returned datetimes will be in UTC.

Response
200 Ok with an array of Document Resource objects containing information about documents the authenticated user has access to.
400 Bad Request if the request does not contain a body
403 Forbidden if the product query parameter is used and the token's scopes do not contain the matching readonly scope for each product.
429 Too Many Requests if the account makes more than 300 requests in 5 seconds

Document Contents

A document can be imported with JSON via the Import Document endpoint. To do so, set your file type to be x-application/vnd.lucid.standardImport, which is the Standard Import file type.

For more information on how to use the Standard Import, refer to the extensive reference documentation here.

For examples of how to use the Standard Import, refer to the /standard-import folder in Lucid's repository of Sample Lucid REST Applications. This repo also contains some example .lucid ZIP files you can reference or use in your own projects. These can be found here.

Note: The POST Document Contents endpoint can only create a new document, not modify an existing document's contents. However, it can be used to create either a Lucidchart OR Lucidspark document.

Document Contents

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/contents' --request 'GET' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json' \
Response
HTTP/1.1 200 OK Content-Type: application/json { "id": "001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "title": "Document Title", "product": "lucidchart", "pages": [ { "id": "YGcM5DNywbTK", "title": "Document Page", "index": 0, "items": { "shapes": [ { "id": "VTAu-oQASzul", "class": "ProcessBlock", "textAreas": [ { "label": "Text", "text": "Process block text" } ], "customData": [ { "key": "Property 1", "value": "Value 1" } ], "linkedData": [ { "collection_id": "ABAuwlf2BTy8", "data": [ { "key": "Property 2", "value": "Value 1" } ], "primaryKeyValue": "Pkey Value" } ] }, ... ], "lines": [ { "id": "VTAusy54S7~U", "endpoint1": { "style": "None", "connectedTo": "VTAu-oQASzul" }, "endpoint2": { "style": "Arrow", "connectedTo": "VTAuCB8~evzW" }, "textAreas": [ { "label": "Text", "text": "Line Text" } ], "customData": [ { "key": "Property 1", "value": "Value 1" } ], "linkedData": [ { "collection_id": "ABAuwlf2BTy8", "data": [ { "key": "Property 2", "value": "Value 1" } ], "primaryKeyValue": "Pkey Value" } ] }, ... ], "groups": [ { "id": "F4gAugGKRJW4", "members": [ "A4gAN9tww9u4", "A4gAh91Vnqnz", "A4gAO.9Y-S9I" ], "customData": [...], "linkedData": [...] }, ... ], "layers": [ { "id": "LTAu-dl6qtqx", "name": "Layer 1", "members": ["VTAuCB8~evzW", "VTAuo_Y56.q~"], "customData": [...], "linkedData": [...] }, ... ] }, "customData": [ { "key": "Property 1", "value": "Value 1" } ], "linkedData": [...] } ], "data": { "collections": [ { "id": "ABAuwlf2BTy8", "name": "Collection 1", "primaryKey": ["PKey 1"] }, ... ] } }

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

Retrieves information about the contents of the requested Lucidchart document. Definitions of content returned can be found at Document Content resource

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

Note: This endpoint has a per account rate limit of 100 requests per 5 seconds.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content:readonly lucidchart.document.app.picker:readonly lucidchart.document.app.folder

Request parameters
Path
id UUID
ID of the document to have contents retrieved.
Response
200 Ok with Document Content resource containing information about the requested document's content.
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted or does not exist.
429 Too Many Requests if the account makes more than 100 requests in 5 seconds

Document Embedding

The embedded document experience consists of two major components: document embeds and document viewers. Conceptually, a document embed represents a particular viewable instance of a document, and a document viewer represents a single rendered view of a document that is actively being viewed by a user.

Individual document embeds should be created any time you want to insert a Lucid document in a particular location in your app. A single Lucid document can have many embeds associated with it, each with its own configurations and access permission restrictions.

To embed a Lucid document, you must first generate a short-lived embed session token to be able to embed the document in an <iframe>.

Resources

Embed Owner

The user associated with the user access token will be the owner of the embed. When users who are not the embed owner try to view the embed, the owning user's access token should still be used to access the embed.

Session Config
Properties Description
products Array
A list of Products that a user can choose a document from to be embedded. Defaults to all products.
viewerType.default ViewerType
What type of viewer to load by defaults. If not specified, defaults to rich. Users can change this later.
ui UI
For an existing embed, which interface to show the user first. Defaults to embed viewer first. Formerly called initialState.
customSettings ViewerCustomSettings
Option to allow your app to display a customized settings view.
Viewer Type
Value Description
rich The standard Lucid viewer experience. A fully interactive viewer with zoom, panning, and support for hotspots and other interactive elements.
simple A basic Lucid viewer experience that can be used in place of the rich viewer if there are performance or load time concerns. The simple viewer renders non-interactive raster images instead of a high-fidelity vector experience and is a poorer fit for viewing larger documents.
UI
Value Description
viewer When loading an existing embed, go directly to the standard embedded view of the document.
settings When loading an existing embed, show the user the embed settings interface before taking them to the standard embed view of the document.
Viewer Custom Settings
Value Description
postMessage Display a "Settings for <app>" link in the embed settings view where users can update the settings. When clicked, the OpenCustomSettings postMessage event would be fired so the app can display its own customized settings view.
none "Settings for <app>" link would not be available in the settings editor.

Generate Embed Session Token

Request
curl 'https://api.lucid.co/embeds/token' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "origin": "https://yourapp.example", "sessionConfig": { "products": ["lucidchart", "lucidspark"], "state": "viewer", "customSettings": "postMessage" } }'
Response
HTTP/1.1 200 OK Content-Type: application/jwt Content-Length: 493 "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhcGkubHVjaWQuY28iLCJzY29wZXMiOiJsdWN \ pZGNoYXJ0LmRvY3VtZW50LmFwcC5waWNrZXIuc2hhcmUiLCJjb25maWciOnsicHJvZHVj \ dHMiOlsibHVjaWRjaGFydCIsImx1Y2lkc3BhcmsiXSwic3RhdGUiOiJ2aWV3ZXIiLCJjd \ XN0b21TZXR0aW5ncyI6InBvc3RNZXNzYWdlIn0sInN1YiI6IjhZejNVTGVDYkQ5REJHZE \ dwTFUycWE4SWJoNHVlMHF0T01TNkFhcksiLCJhdWQiOiJodHRwczovL2x1Y2lkcHJlcHJ \ vZC5hcHAiLCJ1c2VySWQiOjIwMTMwMCwiaWF0IjoxNjk1MzM0OTg3LCJleHAiOjE2OTUz \ MzU1ODcsInRva2VuX3R5cGUiOiJlbWJlZCJ9.VkrFVVwd6X3iFMl-8j2h9HIKV2FcmTw0zBUAgufFuas"

https://api.lucid.co/embeds/token

Generates a tightly-controlled, limited scope, short-term temporary access token to allow your app to display embedded Lucid documents in an <iframe>.

The token is short-lived, and allows the embedding website to load the document picker and document viewer, but does not grant access to any additional resource within Lucid.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.app.picker.share.embed lucidscale.document.app.picker.share.embed lucidspark.document.app.picker.share.embed

Request Parameters
Body
embedId UUID
ID of the document embed. This is needed for viewing an existing embed.
origin String
The domain that will be used to host the webpage in which the document picker will be embedded.
sessionConfig Session Config
Configurations for the embed session.
Response
200 Ok Valid token that can be used to embed a document picker or a document viewer.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Access to the embed is forbidden.
404 Not Found The embed id in the parameter is not found.

Embed Viewer

Example Embed
<iframe src="https://lucid.app/embeds?token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhcGkubHVjaWQuY28iLCJzY29wZXMiOiJsdWNpZGNoYXJ0LmRvY3VtZW50LmFwcC5waWNrZXIuc2hhcmUiLCJjb25maWciOnsicHJvZHVjdHMiOlsibHVjaWRjaGFydCIsImx1Y2lkc3BhcmsiXSwic3RhdGUiOiJ2aWV3ZXIiLCJjdXN0b21TZXR0aW5ncyI6InBvc3RNZXNzYWdlIn0sInN1YiI6IjhZejNVTGVDYkQ5REJHZEdwTFUycWE4SWJoNHVlMHF0T01TNkFhcksiLCJhdWQiOiJodHRwczovL2x1Y2lkcHJlcHJvZC5hcHAiLCJ1c2VySWQiOjIwMTMwMCwiaWF0IjoxNjk1MzM0OTg3LCJleHAiOjE2OTUzMzU1ODcsInRva2VuX3R5cGUiOiJlbWJlZCJ9.VkrFVVwd6X3iFMl-8j2h9HIKV2FcmTw0zBUAgufFuas" ></iframe>
Response
HTTP/1.1 200 OK Content-Type: text/html -- <html data> --

https://lucid.app/embeds?token=:token

Display an embed within an <iframe>.

<iframe src='https://lucid.app/embeds?token=:token' ></iframe>

If no embed id was included when creating the token, the <iframe> first displays a document picker where the user can create and configure a new embed.

If embed id was included, the <iframe> displays an embedded document viewer or an embed configuration page for the associated document.

Request Parameters
Query
token String
The embed session token retrieved from the Generate Embed Session Token endpoint.
Document Embedding Event

Below is a list of possible events via postMessage sent to the parent window:

The EmbedCreated event

Fired when a new embed is created by the user.

Property Description
type String
"LucidEmbedEvent"
event String
"EmbedCreated"
documentId UUID
ID of the selected document.
embedId String
ID of the newly created document embed.
signature String
Signature of the newly created document embed.

The SettingsClosed event

Fired when the embed settings are updated by the user.

Property Description
type String
"LucidEmbedEvent"
event String
"SettingsClosed"
settingsUpdated Boolean
true if the user changed the embed settings.

The OpenCustomSettings event

Fired when the "Settings for <app>" button is clicked by the user.

Property Description
type String
"LucidEmbedEvent"
event String
"OpenCustomSettings"

Folders

The Folder APIs allow for the manipulation of folders and team folders within Lucid.

Resources

Folder

A standard representation of a folder.

Folder Resource
{ "id": 123456789, "type": "folder", "name": "Folder Name", "parent": 123456788, "created": "2020-06-26T16:29:37Z", "trashed": "2022-01-20T12:14:18Z" }
Property Description
id Number
Unique ID of the folder
type FolderType
Type of the folder.
name String
Name of the folder
parent Number
ID of the parent folder
created DateTime
Date and time of when the folder was created
trashed DateTime
Date and time of when the folder was trashed
FolderType
folder Folders can live in other folders, team folders, or the root of a user’s folder manager ("My Documents"). A folder in "My Documents" will have a null parent field.
team Team folders can never live in another folder and are always located in the "Team Folders" section of a user's folder manager. Team folders will not have a parent field. Learn more
Folder Content

A representation of a single item contained in a folder.

Folder Content Resource
{ "id": 123456789, "type": "folder", "name": "Folder Name", "shortcut": false } { "id": 110808fd-4553-4316-bccf-4f25ff59a532, "type": "document", "name": "Document Name", "shortcut": false, "product": "lucidscale" }
Property Description
id Number or UUID
Unique ID of the folder or document being referred to. This field will be a Number for folders and a UUID for documents.
type FolderContentType
Type of the folder contents entry
name String
Name of the folder or document
shortcut Boolean
A boolean value indicating whether or not the folder or document is a shortcut. For more information on shortcuts and permissions see here
product Product
Lucid suite product of the document. Not present for folder entries
FolderContentType
folder Type denoting that the Folder Content Resource is a folder and will have a Number id field and no product field.
document Type denoting that the Folder Content Resource is a document and will have a UUID id field and will contain a product field.

Get Folder

Request
curl 'https://api.lucid.co/folders/123456789' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "id": 123456789, "type": "folder", "name": "Folder Name", "parent": 123456788, "created": "2020-06-26T16:29:37Z", "trashed": "2022-01-20T12:14:18Z" }

https://api.lucid.co/folders/:id

Retrieves information about the requested folder.

Valid Access Token Types

Account
User

Valid Access Scopes

folder:readonly

Request Parameters
Path
id Number
ID of the folder to be retrieved.
Response
200 Ok with a Folder resource containing information about the requested folder.
403 Forbidden if the app making the request does not have permission to the folder, or if the folder has been deleted (trashed is okay) or does not exist.

Create Folder

Request
curl 'https://api.lucid.co/folders' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Folder Name", "type": "folder", "parent": 123456788 }'
Response
HTTP/1.1 201 Created Content-Type: application/json { "id": 123456789, "type": "folder", "name": "Folder Name", "parent": 123456788, "created": "2020-06-26T16:29:37Z", "trashed": null }

https://api.lucid.co/folders

Create a new folder. Folders can contain documents or other folders and can be shared with collaborators.

Valid Access Token Types

User

Valid Access Scopes

folder

Request Parameters
Body
name String
Name of the folder being created.
type FolderType
Type of the folder being created. Note: This endpoint only accepts the folder type
parent Number
Destination folder to create the new folder in. If it is not provided, the folder will be created in the root of the user's folder manager ("My Documents").
Response
201 Created with a Folder resource containing information about the newly created folder.
403 Forbidden if the request is not authorized to create in the specified parent folder.

Update Folder

Request
curl 'https://api.lucid.co/folders/123456789' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --data-raw '{ "name": "New Folder Name", "parent": 123456780 }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "id": 123456789, "type": "folder", "name": "New Folder Name", "parent": 123456780, "created": "2020-06-26T16:29:37Z", "trashed": null }

https://api.lucid.co/folders/:id

Allows the requester to modify certain fields on a folder.

Updating the parent field will cause the folder to be moved into the new folder. The requesting user must have edit and share access to the old and new parent folders or else the entire update will fail. The contents of the folder will remain within it during the move. It is an error to update the parent field on a Team Folder.

Moving folders into or out of a Team Folder can fail for a variety of permission-related reasons. Once within a Team Folder, a folder and all of its descendants can be reorganized within that Team Folder without causing any permission errors.

Valid Access Token Types

User

Valid Access Scopes

folder

Request Parameters
Path
id Number
ID of the folder to be updated.
Body
name String
New name for the folder being updated.
parent Number
New parent for the folder being updated. Causes the folder to be moved into another folder if an ID is provided or into the user's root folder ("My Documents") if null is provided. If the parent field is not included in the request, the folder will not be moved. Cannot be provided for Team Folders.
Response
200 Ok with a Folder resource containing information about the updated folder.
400 Bad Request if the parent field is included in a request for a team folder, or if invalid input types are provided for id, name, or parent.
403 Forbidden if the app making the request does not have permission to the folder, the folder has been deleted or does not exist, or the request was not authorized to move the folder.

Trash Folder

Request
curl 'https://api.lucid.co/folders/123456789/trash' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json'
Response
HTTP/1.1 204 No Content Content-Length: 0

https://api.lucid.co/folders/:id/trash

Move the given folder and all of its contents into the trash.

Valid Access Token Types

User

Valid Access Scopes

folder

Request Parameters
Path
id Number
ID of the folder to be moved to the trash
Response
204 No Content when the folder is successfully moved into the trash or is already trashed.
403 Forbidden if the app making the request does not have permission to the folder, or if the folder has been deleted or does not exist.

Restore Folder

Request
curl 'https://api.lucid.co/folders/123456789/restore' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json'
Response
HTTP/1.1 204 No Content Content-Length: 0

https://api.lucid.co/folders/:id/restore

Move the given folder and all of its contents to their original pre-trash locations.

Valid Access Token Types

User

Valid Access Scopes

folder

Request Parameters
Path
id Number
ID of the folder to be restored from the trash
Response
204 No Content when the folder is successfully moved out of the trash or is already not in the trash.
403 Forbidden if the app making the request does not have permission to the folder, or if the folder has been deleted or does not exist.

Search Folders

Request
curl 'https://api.lucid.co/folders/search' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "type": "folder", "keywords": "training material" }'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "id": 123456789, "type": "folder", "name": "Training Material 2023", "parent": null, "created": "2020-05-30T08:16:23Z", "trashed": null }, { "id": 987654321, "type": "folder", "name": "October Training", "parent": 123456789, "created": "2020-06-26T16:29:37Z", "trashed": null }, ]

https://api.lucid.co/folders/search

Retrieves information about folders the authenticated user has at least read only access to. Additional filtering parameters may be added.

This endpoint is paginated. For more information, see Pagination.

Note: This endpoint has a per account rate limit of 300 requests per 5 seconds.

Valid Access Token Types

User

Valid Access Scopes

folder:readonly

Request Parameters
Body
type FolderType
FolderType to filter by. Default value assumes all folder types.
keywords String
Keywords to search against folder content and titles. This field is truncated to 400 characters. When provided, results will be sorted by relevance to keyword search.
Response
200 Ok with an array of Folder Resource objects containing information about folders the authenticated user has access to.
400 Bad Request if the request does not contain a body
429 Too Many Requests if the account makes more than 300 requests in 5 seconds

List Folder Contents

Request
curl 'https://api.lucid.co/folders/987654321/contents' \ --request 'GET' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "id": 123456789, "type": "folder", "name": "Folder Name", "shortcut": false }, { "id": "110808fd-4553-4316-bccf-4f25ff59a532", "type": "document", "name": "Document Name", "shortcut": true, "product": "lucidspark" } ]

https://api.lucid.co/folders/:id/contents https://api.lucid.co/folders/root/contents

Retrieves basic information about the contents of a given folder.

This endpoint is paginated. For more information, see Pagination.

Note: Requesting root contents will only return folders that the authenticated token owns.

Valid Access Token Types

User

Valid Access Scopes

folder:readonly

Request Parameters
Path
id Number or root
ID of the folder to retrieve contents of. root can be used in place of an ID to retrieve the contents of the authenticated user's root directory ("My Documents")
Response
200 Ok with an array of Folder Content Resources containing information about the contents of the requested folder.
403 Forbidden if the app making the request does not have permission to the folder, or if the folder has been deleted or does not exist.

Sharing

The Sharing APIs allow for the manipulation and creation of share links to Lucid documents.

Share links are created and defined with a linkSecurity field that contains definitions of how share links are configured for access to their corresponding document. These fields are only configurable for users on accounts with an enterprise license. The allowAnonymous field is only available for Lucidspark and Lucidchart documents and will always be false for other product's documents.

If an expiration time is provided when updating or creating a share link outside of the allowable range by the account the corresponding document is on, the expiration date will be clamped to be within the maximum allowable expiration time.

If the account requires the share link to only be acceptable within the account the document belongs to, the restrictToAccount field will always be set to true regardless of the provided input when creating or updating the share link.

If the document share link belongs to an account without an enterprise license, the default linkSecurity settings of no expiration, no passcode and unrestricted access, and no anonymous guests will be used.

Document Link Security
{ "restrictToAccount": false, "expires": "2023-12-11T21:48:35.293Z", "passcode": "password", "allowAnonymous": false }
Property Description
restrictToAccount Boolean
Whether or not users outside the document's account can accept the share link
expires DateTime
If defined, the date and time the share link expires
passcode String
If defined, the required passcode to accept the share link
allowAnonymous Boolean
Whether or not the share link allows for anonymous guests
Sharing Roles

Roles determine what actions an invitation will grant on a document. Invitations to a document only grant the specified level of access to just that one document.

Role Description
editandshare View, comment on, edit, and control which users can access the document
edit View, comment on, and edit the document
comment View the document. Leave comments on the document
view View the document.

Documents

Resources

Document Share Link
{ "shareLinkId": "inv_8a38797a-e5fc-4479-8492-e000dc93cb60", "documentId": "f6bf19b5-d109-4ef5-92b2-cdaf0de43001", "role": "editandshare", "linkSecurity": { "restrictToAccount": false, "expires": null, "passcode": null, "allowAnonymous": false }, "created": "2022-11-11T21:48:35.293Z", "createdBy": 1280, "lastModified": "2022-11-11T21:48:35.293Z", "acceptUrl": "https://lucid.app/lucidchart/invitations/accept/inv_8a38797a-e5fc-4479-8492-e000dc93cb60" }
Property Description
shareLinkId String
Id of the share link
documentId UUID
Id of the document the share link belongs to
role Role
The Sharing Role the share link grants on the document
linkSecurity Document Link Security
The Document Link Security settings on the share link
created DateTime
The date and time the share link was created
createdBy Number
User Id of the user that created the share link
lastModified DateTime
The date and time the share link was last modified
acceptUrl URI
Link to accept the share link invitation
Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/shareLinks/inv_8a38797a-e5fc-4479-8492-e000dc93cb60' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "shareLinkId": "inv_8a38797a-e5fc-4479-8492-e000dc93cb60", "documentId": "001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "role": "editandshare", "linkSecurity": { "restrictToAccount": false, "expires": null, "passcode": null, "allowAnonymous": false }, "created": "2022-11-11T21:48:35.293Z", "createdBy": 1280, "lastModified": "2022-11-11T21:48:35.293Z", "acceptUrl": "https://lucid.app/lucidchart/invitations/accept/inv_8a38797a-e5fc-4479-8492-e000dc93cb60" }

https://api.lucid.co/documents/:id/shares/shareLinks/:shareLinkId

Gets information about the share link on the provided document.

Note: This endpoint will only retrieve information about share links created by the same OAuth2.0 client

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content.share.link:readonly lucidchart.document.app.picker.share.link:readonly lucidchart.document.app.folder lucidscale.document.content.share.link:readonly lucidscale.document.app.picker.share.link:readonly lucidscale.document.app.folder lucidspark.document.content.share.link:readonly lucidspark.document.app.picker.share.link:readonly lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document.
shareLinkId String
Id of the share link to retrieve information for.
Response
200 Ok with a Document Share Link resource containing information about the requested share link.
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted, or does not exist.
404 Not Found if the share link id with the specified document id does not belong to the document, does not exist, or the requesting app did not create the share link.
Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/shareLinks' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' --data-raw '{ "role": "editandshare", "linkSecurity": { "restrictToAccount": false, "allowAnonymous": true, "passcode": "passcode" } }'
Response
HTTP/1.1 201 Created Content-Type: application/json { "shareLinkId": "inv_8a38797a-e5fc-4479-8492-e000dc93cb60", "documentId": "001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "role": "editandshare", "linkSecurity": { "restrictToAccount": false, "expires": null, "passcode": passcode, "allowAnonymous": true }, "created": "2022-11-11T21:48:35.293Z", "createdBy": 1280, "lastModified": "2022-11-11T21:48:35.293Z", "acceptUrl": "https://lucid.app/lucidspark/invitations/accept/inv_8a38797a-e5fc-4479-8492-e000dc93cb60" }

https://api.lucid.co/documents/:id/shares/shareLinks

Creates a new share link on the provided document with the provided settings

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content.share.link lucidchart.document.app.picker.share.link lucidchart.document.app.folder lucidscale.document.content.share.link lucidscale.document.app.picker.share.link lucidscale.document.app.folder lucidspark.document.content.share.link lucidspark.document.app.picker.share.link lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document.
Body
role Role
The Sharing Role the share link will grant on the document.
invitationSecurity Document Link Security
The Document Link Security settings on the share link.

Note: The invitationSecurity is only configurable for users on accounts with an enterprise license but is still required for team accounts. For more information see here.
Note: If an expiration is provided outside the account defined limits, it will clamp to be the maximum possible time.
Note: If the restrictToAccount field is provided as false and the document's account defined settings do not allow share links outside the account, it will restrict the share link to be within the account.

Response
201 Created with a Document Share Link resource containing information about the created share link.
400 Bad Request if the the document does not belong to an enterprise account and the restrictToAccount is set to true, defines a passcode, or defines an expiration or the allowAnonymous field is set to true on non-Lucidspark/Lucidchart documents.
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted, or does not exist.
Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/shareLinks/inv_8a38797a-e5fc-4479-8492-e000dc93cb60' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' --data-raw '{ "role": "editandshare", "linkSecurity": { "restrictToAccount": false, "allowAnonymous": true, "passcode": "passcode" } }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "shareLinkId": "inv_8a38797a-e5fc-4479-8492-e000dc93cb60", "documentId": "001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "role": "editandshare", "linkSecurity": { "restrictToAccount": false, "expires": null, "passcode": passcode, "allowAnonymous": true }, "created": "2022-11-11T21:48:35.293Z", "createdBy": 1280, "lastModified": "2022-11-11T21:48:35.293Z", "acceptUrl": "https://lucid.app/lucidspark/invitations/accept/inv_8a38797a-e5fc-4479-8492-e000dc93cb60" }

https://api.lucid.co/documents/:id/shares/shareLinks/:shareLinkId

Updates an existing share link to the provided settings. If any settings are omitted, the already existing settings will be used instead.

Note: Share links will only be updatable by the OAuth2.0 client that created them.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content.share.link lucidchart.document.app.picker.share.link lucidchart.document.app.folder lucidscale.document.content.share.link lucidscale.document.app.picker.share.link lucidscale.document.app.folder lucidspark.document.content.share.link lucidspark.document.app.picker.share.link lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document.
shareLinkId String
ID of the share link belonging to the document.
Body
role Role
The Sharing Role the share link will grant on the document.
invitationSecurity Document Link Security
The Document Link Security settings on the share link.

Note: All fields including invitationSecurity and the fields in invitationSecurity are optional.
Note: The invitationSecurity is only configurable for users on accounts with an enterprise license but is still required for team accounts. For more information see here.
Note: If an expiration is provided outside the account defined limits, it will clamp to be the maximum possible time.
Note: If the restrictToAccount field is provided and the document's account defined settings do not allow share links outside the account, it will restrict the share link to be within the account.

Response
200 Created with a Document Share Link resource containing information about the updated share link.
400 Bad Request if the the document does not belong to an enterprise account and the restrictToAccount is set to true, defines a passcode, or defines an expiration or the allowAnonymous field is set to true on non-Lucidspark/Lucidchart documents.
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted, or does not exist.
404 Not Found if the share link id with the specified document id does not belong to the document, does not exist, or the requesting app did not create the share link.
Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/shares/shareLinks/inv_8a38797a-e5fc-4479-8492-e000dc93cb60' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 204 No Content Content-Length: 0

https://api.lucid.co/documents/:id/shares/shareLinks/:shareLinkId

Deletes a share link on a document

Note: This endpoint will only delete share links created by the same OAuth2.0 client

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content.share.link lucidchart.document.app.picker.share.link lucidchart.document.app.folder lucidscale.document.content.share.link lucidscale.document.app.picker.share.link lucidscale.document.app.folder lucidspark.document.content.share.link lucidspark.document.app.picker.share.link lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document.
shareLinkId String
Id of the share link to delete.
Response
204 No Content if the share link was deleted successfully
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted, or does not exist.
404 Not Found if the share link id with the specified document id does not belong to the document, does not exist, or the requesting app did not create the share link.

Transfer Content

Transfer User Content

Request
curl 'https://api.lucid.co/transferUserContent' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' --header 'Content-Type: application/json' \ --data-raw '{ "fromUser": "john.doe@example.com", "toUser": "jane.smith@example.com" }'
Response
HTTP/1.1 204 No Content Content-Length: 0

https://api.lucid.co/transferUserContent

Note: Use of this endpoint can only be authorized by administrators on accounts with Enterprise licenses.
Note: This endpoint has a per account rate limit of 30 requests per 5 seconds.

Transfers ownership of Lucid documents and objects from one user to another. Note that both the fromUser and toUser must be on the same account as the admin authorizing the transfer.

This endpoint transfers the following to the toUser:

  • Documents and folders owned by the fromUser. The toUser will also be given edit and share permissions to any team folder the fromUser has edit and share permissions for.
  • Custom shape libraries
  • Lucidscale objects (3rd party credentials, AWS accounts, GCP projects, and Azure subscriptions)

After the transfer, the fromUser loses ownership of the objects described above. An email is also sent to both the fromUser and the toUser to notify them of the transfer.

Note: This endpoint does not delete or delicense the fromUser.

Valid Access Token Types

Account

Valid Access Scopes

account.user.transfercontent

Request Parameters
Body
fromUser String
Email of the user whose content will be transferred.
toUser String
Email of the user the content will be transferred to.
Response
204 No Content when ownership is successfully transferred.
400 Bad Request when the fromUser and toUser are the same.
403 Forbidden when the users do not exist or are not on the authenticated account.
429 Too Many Requests if the account makes more than 30 requests in 5 seconds

Users

The User APIs enable the manipulation of Lucid users and their administrative roles.

Resources

User

A standard representation of a user.

User Resource
{ "accountId": 100, "email": "john-doe@example.com", "name": "John Doe", "userId": 101, "username": "johndoe", "roles": ["billing-admin", "team-admin"] }
Property Description
accountId Number
The unique ID for the user's account.
email String
The user's email.
name String
The user's full name.
userId Number
The unique ID for the user.
username String
The user's username.
roles Array[String]
A list of administrative roles assigned to the user.
Roles

Assigning a role to a user allows that user to perform administrative actions associated with that role.
billing-admin Billing admins can change payment options for the account.
document-approver Document approvers can approve documents.
team-admin Team admins can access and edit team settings, including user roles and groups.
Profile

The Profile resource contains basic profile information about a user.

Profile Resource
{ "username": "johndoe", "email": "john-doe@example.com", "fullName": "John Doe", "id": 101, "accountId": 100 }
Property Description
accountId Number
The unique ID for the user's account.
username String
Username of the user
email String
Email of the user
fullName String
Full name of the user
id UserId
ID of the user

Get User

Request
curl 'https://api.lucid.co/users/204' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "accountId": 100, "email": "jane-doe@example.com", "name": "Jane Doe", "userId": 204, "username": "janedoe", "roles": [] }

https://api.lucid.co/users/:id

Retrieves information about the requested user. The requested user must be on to the authenticated account.

Valid Access Token Types

Account
User

Valid Access Scopes

account.user:readonly

Request Parameters
Path
id Number
ID of the user to be retrieved.
Response
200 Ok with a User resource containing information about the user.
403 Forbidden if the user does not belong to the authenticated account or if the user does not exist.

List Users

Request
curl 'https://api.lucid.co/users' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json Link: https://api.lucid.co/users?pageSize=20&pageToken=eyJvIjoiMSIsImUiOjE2Mjg2OTc3OTF9; rel="next" [ { "accountId": 100, "email": "john-doe@example.com", "name": "John Doe", "userId": 101, "username": "johndoe", "roles": ["billing-admin", "team-admin"] }, { "accountId": 100, "email": "jane-doe@example.com", "name": "Jane Doe", "userId": 204, "username": "janedoe", "roles": [] } ]

https://api.lucid.co/users

A paginated endpoint that retrieves information about all users on the authenticated account. For more information, see Pagination.

Valid Access Token Types

Account

Valid Access Scopes

account.user:readonly

Request Parameters

Note: See Pagination for optional pagination parameters.

Response
200 Ok with a list of User resources containing information about users on the account.

Search Users By Email

Request
curl 'https://api.lucid.co/users/searchByEmail' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \ --data-raw '{ "emails": [ "john-doe@example.com", "jane-doe@example.com", "not-a-user@example.com" ] }'
Response
HTTP/1.1 200 OK Content-Type: application/json Link: https://api.lucid.co/users/searchByEmail" [ { "accountId": 100, "email": "john-doe@example.com", "fullName": "John Doe", "id": 101, "username": "johndoe" }, { "accountId": 100, "email": "jane-doe@example.com", "fullName": "Jane Doe", "id": 204, "username": "janedoe" } ]

https://api.lucid.co/users/searchByEmail

Retrieves information about all users on the authenticated user's account whose email is provided. Email matching is a case insensitive exact match. Emails that do not exactly match a user on the account will be disregarded.

Valid Access Token Types

User

Valid Access Scopes

account.user:readonly

Request Parameters
Body
emails Array[String]
List of User emails to search for. Limited to 200 items.
Response
200 Ok with a list of Profile resources containing information about users on the account. Emails that could not be matched are not included.
400 Bad Request if the request body emails exceed 200 items.
400 Bad Request if any of the strings in the request body can not be parsed into the email format.

Get Profile

Request
curl 'https://api.lucid.co/users/me/profile' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "username": "johndoe", "email": "john-doe@example.com", "fullName": "John Doe", "id": 101 }

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

Retrieves basic information about the authenticated user.

Valid Access Token Types

User

Valid Access Scopes

user.profile

Response
200 Ok with a Profile resource containing information about the requesting user.

Create User

Request
curl 'https://api.lucid.co/users' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "john-doe@example.com", "firstName": "John", "lastName": "Doe", "username": "john-doe@example.com", "password": "`.~b"J<CA95m`bV@", "roles": ["billing-admin", "team-admin"] }'
Response
HTTP/1.1 201 Created Content-Type: application/json { "accountId": 100000950, "email": "john-doe@example.com", "name": "John Doe", "userId": 2283, "username": "john-doe@example.com", "roles": ["billing-admin", "team-admin"] }

https://api.lucid.co/users

Note: Use of this endpoint can only be authorized by administrators on accounts with Enterprise licenses.

Creates a new user and adds them to the authenticated account. Licenses are granted to the user based on the authenticated account's auto licensing settings. Learn more.

Valid Access Token Types

Account

Valid Access Scopes

account.user

Request Parameters
Body
email String
The user's email
firstName String
The user's first name
lastName String
The user's last name
username String
The user's username. If not provided the email will be used as the username.
password String
The user's password.
roles Array[String]
A list of roles assigned to the user.
Response
201 Created with a User resource containing information about the created user.
400 Bad Request if any input field is invalid.
403 Forbidden
  • if the app making the request does not have permission to create users
  • if the email domain is under domain control by a different account. Learn more.
  • if the token requesting to create a user is not on an Enterprise account
409 Conflict if a user with the same email or username already exists.

Unfurling

The Unfurling APIs allow for the manipulation of links in Lucid to provide the ability to easily embed and view Lucid documents.

Resources

Resource representing information contained in a Lucid link

Link Resource
{ "document": { "documentId": "110808fd-4553-4316-bccf-4f25ff59a532", "page": null, "product": "lucidspark" } "invitation": { "invitationId": "inv_288b9365-685b-4bf2-9f6f-8aa9e2082542", } }
Property Description
document Link-Document
Information about the Document contained in the link if it exists
invitation Link-Invitation
Information about the Invitation contained in the link if it exists

Resource representing document information contained in a Lucid link

Link Document Resource
{ "documentId": "110808fd-4553-4316-bccf-4f25ff59a532", "page": null, "product": "lucidspark", "basicEmbed": "https://lucid.app/documents/110808fd-4553-4316-bccf-4f25ff59a532/viewer?authType=local" }
Property Description
documentId UUID
ID of the document contained in the link if it exists
page String
Document page contained in the link if it exists
product Product
Lucid suite product contained in the link if it exists
basicEmbed URI
Link to iframeable embed using cookie based authentication

Resource representing invitation information contained in a Lucid link

Link Invitation Resource
{ "invitationId": "inv_288b9365-685b-4bf2-9f6f-8aa9e2082542", }
Property Description
invitationId String
Id of the invitiation contained in the link if it exists

Direct Embed

Example Embed
<iframe src="https://lucid.app/embeds/link?clientId=FNvGih-a3gx3MC_FsM1Wo-obFxgIRQ74dyySsoyg&document=https://lucid.app/lucidchart/fb892462-7199-4daa-a7d1-b76ea7a0e267/edit?from_internal=true" ></iframe>
Response
HTTP/1.1 200 OK Content-Type: text/html -- <html data> --

https://lucid.app/embeds/link?document=:document&clientId=:clientId

Display an embed within an <iframe>.

<iframe src='https://lucid.app/embeds/link?document=:document&clientId=:clientId' ></iframe>

If the clientId is valid with the registered embed domain in the developer portal, the <iframe> displays a login page or an embedded document viewer based on the user's authorization cookie.

This endpoint does not require OAuth2 authentication and utilizes browser cookies instead.

Request Parameters
Query
document The url of the Lucid document link or the documentId retrieved from the Describe Link endpoint
clientId The client ID obtained during App registration
Request
curl 'https://api.lucid.co/describeLink' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Lucid-Api-Version: 1' \ --data-raw '{ "url": "https://lucid.app/lucidchart/90e5f020-0f26-4d15-8955-d96dca8bf9a4/edit?page=K2hT2&invitationId=inv_74610d09-7f84-496b-8aa6-5599782176a6#" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "document": { "documentId": "90e5f020-0f26-4d15-8955-d96dca8bf9a4", "page": "K2hT2", "product": "lucidchart" "basicEmbed": "https://lucid.app/documents/90e5f020-0f26-4d15-8955-d96dca8bf9a4/viewer?page=K2hT2&authType=local" }, "invitation": { "invitationId": "inv_74610d09-7f84-496b-8aa6-5599782176a6", } }

https://api.lucid.co/describeLink

Parses and retrieves information from the provided Lucid document link. This does not confirm that the document or resource exists.

Valid Access Token Types

Account User

Valid Access Scopes

Unrestricted

Request Parameters
Body
url String
The url of the Lucid document link to parse information from
Response
200 Ok with a Link resource containing information about the document link.
403 Forbidden if the url is not a valid Lucid link.

Embedding Utils

The following APIs for programatically manipulating document embeds might be helpful, but they are not necessary for basic use cases. The process for creating embeds and updating embed settings are handled by the APIs in the Document Embedding section.

Resources

Embed resource
Embed Resource
{ "embedId": "298f9a4a-09b5-440c-b95e-4d5c2d1aaf49", "documentId": "71608643-765a-4b44-ae64-4f44425b395e", "embedVersion": "latest-version", "created": "2021-06-26T16:29:37Z", "modified": "2021-08-02T04:16:52Z" }
Property Description
embedId UUID
Unique ID associated with the embed
documentId UUID
ID of the document
embedVersion DocumentEmbedVersion
"latest-version" or "snapshot-version"
created DateTime
Date and time of when the embed was created
modified DateTime
Date and time of when the embed was last modified

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

Embed document resource
Embed Document Resource
{ "embedId": "298f9a4a-09b5-440c-b95e-4d5c2d1aaf49", "documentId": "71608643-765a-4b44-ae64-4f44425b395e", "pageCount": 2, "title": "Example Document", }
Property Description
embedId UUID
Unique ID associated with the embed
documentId UUID
ID of the document
pageCount Integer
Number of pages in the embedded document
title String
Title of the embedded document

Important: If the embed is a snapshot-version embed, the title and pageCount fields of this resource will contain the title and page count of the document at the moment the snapshot embed was created.

Document Embed Version
Value Description
latest-version The embed will always show the latest version of the document.
snapshot-version Takes a snapshot of the document when the embed is created. The embed will always show that snapshot.

Get Document Embed

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/embeds/ec890631-c150-461c-992f-b96533aa05f4' \ --request 'GET' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Accept: application/json'
Response
HTTP/1.1 200 Ok Content-Type: application/json { "embedId":"ec890631-c150-461c-992f-b96533aa05f4", "documentId":"001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "embedVersion":"snapshot-version", "created":"2021-10-01T20:49:36.169Z", "modified":"2021-10-01T20:49:36.169Z" }

https://api.lucid.co/documents/:documentId/embeds/:embedId

Retrieves information about the requested document embed.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.content.share.embed:readonly lucidchart.document.app.picker.share.embed:readonly lucidscale.document.content.share.embed:readonly lucidscale.document.app.picker.share.embed:readonly lucidspark.document.content.share.embed:readonly lucidspark.document.app.picker.share.embed:readonly

Request Parameters
Path
documentId UUID
ID of the embedded document to retrieve
embedId UUID
ID of the document embed to retrieve
Response
200 Ok with Document Embed Resource containing information about the requested document embed.
403 Forbidden when the authorized token does not have permission to access the requested document or embed, or when the requested document or embed does not exist.

Get Document Embed Document

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/embeds/ec890631-c150-461c-992f-b96533aa05f4/document' \ --request 'GET' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>'
Response
HTTP/1.1 200 Ok Content-Type: application/json { "embedId":"ec890631-c150-461c-992f-b96533aa05f4", "documentId":"001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "pageCount":5, "title":"Documentation example document", }

https://api.lucid.co/documents/:documentId/embeds/:embedId/document

Retrieves limited metadata about the embedded document. If the embed is a snapshot-version embed, the metadata will be drawn from the state of the document at the time that the snapshot was created.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.content.share.embed:readonly lucidchart.document.app.picker.share.embed:readonly lucidscale.document.content.share.embed:readonly lucidscale.document.app.picker.share.embed:readonly lucidspark.document.content.share.embed:readonly lucidspark.document.app.picker.share.embed:readonly

Request Parameters
Path
documentId UUID
ID of the embedded document to retrieve
embedId UUID
ID of the document embed to retrieve
Response
200 Ok with Document Embed Document Resource containing the title and page count of the requested document embed.
403 Forbidden when the authorized token does not have permission to access the requested document or embed, or when the requested document or embed does not exist.

Create Document Embed

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/embeds' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "embedVersion": "snapshot-version" }'
Response
HTTP/1.1 201 Created Content-Type: application/json { "embedId":"ec890631-c150-461c-992f-b96533aa05f4", "documentId":"001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "embedVersion":"snapshot-version", "created":"2021-10-01T20:49:36.169Z", "modified":"2021-10-01T20:49:36.169Z" }

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

Creates an embed resource associated with a particular document. The request must be authenticated with an OAuth2 token that has access to the document.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.content.share.embed lucidchart.document.app.picker.share.embed lucidscale.document.content.share.embed lucidscale.document.app.picker.share.embed lucidspark.document.content.share.embed lucidspark.document.app.picker.share.embed

Request Parameters
Path
id UUID
ID of the document to be embedded
Body
embedVersion DocumentEmbedVersion
Determines what version of the document will be loaded in the document viewer.
Response
201 Created with Document Embed Resource containing information about the newly created document embed.
400 Bad Request if the embed version provided in the request body is invalid.
403 Forbidden when the access token isn't allowed to create an embed for this document.

Change Document Embed Version

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/embeds/298f9a4a-09b5-440c-b95e-4d5c2d1aaf49/changeVersion' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "embedVersion": "latest-version" }'
Response
HTTP/1.1 201 Created Content-Type: application/json { "embedId":"298f9a4a-09b5-440c-b95e-4d5c2d1aaf49", "documentId":"001bd56d-1b10-4196-8ac6-45e3c22bd1c6", "embedVersion":"latest-version", "created":"2021-10-01T20:49:36.169Z", "modified":"2021-10-01T20:49:36.169Z" }

https://api.lucid.co/documents/:documentId/embeds/:embedId/changeVersion

Updates the version type of an existing document embed. Calling this endpoint with an embedVersion of "snapshot-version" will associate the existing embed with a snapshot of the current state of the document, even if the embed was already associated with an older snapshot of the document.

Important: Updating the version of an existing document embed with version type snapshot-version can't be undone! There is no way to revert an embed to a previous snapshot version.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.content.share.embed lucidchart.document.app.picker.share.embed lucidscale.document.content.share.embed lucidscale.document.app.picker.share.embed lucidspark.document.content.share.embed lucidspark.document.app.picker.share.embed

Request Parameters
Path
documentId UUID
ID of the document
embedId UUID
ID of the document embed
Body
embedVersion DocumentEmbedVersion
Determines what version of the document will be loaded in the document viewer.
Response
200 Ok with Document Embed Resource containing information about the updated document embed.
400 Bad Request if the embed version provided in the request body is invalid.
403 Forbidden when the access token isn't allowed to change the embed version.

Delete Document Embed

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/embeds/298f9a4a-09b5-440c-b95e-4d5c2d1aaf49' \ --request 'DELETE' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>'
Response
HTTP/1.1 204 No Content Content-Length: 0

https://api.lucid.co/documents/:documentId/embeds/:embedId

Deletes an existing document embed.

Important: This will cause the document viewer to fail when attempting to load this document embed.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.content.share.embed lucidchart.document.app.picker.share.embed lucidscale.document.content.share.embed lucidscale.document.app.picker.share.embed lucidspark.document.content.share.embed lucidspark.document.app.picker.share.embed

Request Parameters
Path
documentId UUID
ID of the document
embedId UUID
ID of the document embed
Response
204 No Content when the document embed is deleted successfully.
403 Forbidden when the access token isn't allowed to delete the embed.

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.

Note: Only user OAuth 2.0 tokens are valid when using OAuth 2.0 authentication for the Data API.

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

Request
curl 'https://data.lucid.app/rateLimits' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "userHardRefreshInterval": 30, "userSoftRefreshInterval": 30, "userApiCallRate": 750, "fileSizeLimit": 3 }

https://data.lucid.app/rateLimits

See what your current rate limits are.

Valid OAuth2 Access Scope

data-service.admin

Response
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.

For most API use cases a data set is not needed since a data source can be used without a data set.

Resources

Data Set
Data Set Resource
{ "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" }
Property Description
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
Paginated List Resource
{ "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" }
Property Description
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 Total Data Sets Count

Request
curl 'https://data.lucid.app/dataSets' \ --request 'HEAD' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK lucid-datasets-total: 123 Content-Length: 0

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

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

Get Data Set

Request
curl 'https://data.lucid.app/dataSets/2168' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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" }

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

Gets a specific existing data set from Lucid

Valid OAuth2 Access Scope

data-service.admin

Request Parameters
Path
id Number
ID of data set to be retrieved
Response
200 Ok with Data Set

Get All Data Sets

Request
curl 'https://data.lucid.app/dataSets?start=1&end=100' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "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" } ]

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 Parameters
Query
start Number
Starting 1-based index of data sets to retreive. Defaults to 1.
end Number
Ending index of data sets to retreive. Defaults to 100.
Response
200 Ok with paginated list of Data Sets

Create Data Set

Request
curl 'https://data.lucid.app/dataSets' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "name": "Data Set Name", "properties": { "Color": "green", "AuthoredBy": "Lucidchart" } }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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" }

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 Parameters
Body
name String
Name to give to new data set
properties Map[String,JsValue]
Used to create the data set properties for the new data set.
Response
200 Ok with Data Set

Update Data Set Name

Request
curl 'https://data.lucid.app/dataSets/2168' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "name": "New Data Set Name", }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/dataSets/2168", "name": "New 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" }

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 Parameters
Body
name String
Name to give to existing data set
Response
200 Ok with Data Set

Delete Data Set

Request
curl 'https://data.lucid.app/dataSets/435' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
id Number
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
Data Set Grant Resource
{ "uri": "https://data.lucid.app/dataSetGrants/8", "dataSet": "https://data.lucid.app/dataSets/435", "permissionType": "account", "identifier": "1234", "role": "edit" }
Property Description
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 Data Set Grant

Request
curl 'https://data.lucid.app/dataSetGrants/435' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/dataSetGrants/435", "dataSet": "https://data.lucid.app/dataSets/8", "permissionType": "account", "identifier": "1234", "role": "edit" }

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 Parameters
Path
id Number
ID of data set grant to be retrieved
Response
200 Ok with Data Set Grant

Get All Data Set Grants

Request
curl 'https://data.lucid.app/dataSetGrants?dataSet=https://data.lucid.app/dataSets/435' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "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" } ]

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 Parameters
Query
dataSet URI
Data set to find all grants for.
Response
200 Ok with Array[Data Set Grant]

Create Data Set Grant

Request
curl 'https://data.lucid.app/dataSetGrants' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "dataSet": "https://data.lucid.app/dataSets/8", "permissionType": "account", "identifier": "1234", "role": "edit" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/dataSetGrants/8", "dataSet": "https://data.lucid.app/dataSets/435", "permissionType": "account", "identifier": "1234", "role": "edit" }

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 Parameters

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
Body
dataSet URI
Data set to add grant to.
permissionType String
Type of permission being given. Valid values are "account", "document" or "user".
identifier String
Identifier for permission type.
role String
Role being given. Valid values are "view" and "edit".
Response
200 Ok with Data Set Grant

Delete Data Set Grant

Request
curl 'https://data.lucid.app/dataSetGrants/26' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
id Integer
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

Request
curl 'https://data.lucid.app/dataSets/435/properties' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "backgroundColor": "blue", "font": "Times New Roman" }

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 Parameters
Path
id Number
ID of data set to get properties for
Response
200 Ok with Map[String,JsValue] of properties on the specified data set

Update Data Set Properties

Request
curl 'https://data.lucid.app/dataSets/184/properties' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "backgroundColor": "blue", "font": "Times New Roman" } }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "backgroundColor": "blue", "font": "Times New Roman" }

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 Parameters
Path
id Number
ID of data set to update properties for
Body
Map[String,JsValue] Properties to update or add to specified data set
Response
200 Ok with list of properties that were affected

Delete Data Set Properties

Request
curl 'https://data.lucid.app/dataSets/435/properties?properties=prop1,prop2' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
id Number
ID of data set for properties to be deleted from
Query
properties Array[String]
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
Data Source Resource
{ "uri": "https://data.lucid.app/dataSources/2967", "name": "Internal Org Chart", "product": "chart", "sourceGrants": "https://data.lucid.app/sourceGrants?dataSource=https://data.lucid.app/dataSources/2967", "adapterType": "DATA_API", "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 }
Property Description
uri URI
Link to get self
name String
Name of data source
sourceGrants URI
Link to get grants specific to this data source
adapterType Adapter Type
Type of the data source
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
Link to get any parameters used for linking the data to it's source
deleted DateTime
Timestamp of when this data source was deleted
Adapter Type
CSV Mimics settings within Lucidchart editor as if it was a CSV file upload.
DATA_API Created with the Data API, sources of this type can get automatic updates within the Lucidchart data linking panel.
UNKNOWN Default if not provided.
Paginated List
Paginated List Resource
{ "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" }
Property Description
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 Total Data Sources Count

Request
curl 'https://data.lucid.app/dataSources' \ --request 'HEAD' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK lucid-datasources-total: 123 Content-Length: 0

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

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

Get Data Source

Request
curl 'https://data.lucid.app/dataSources/123' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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 }

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 Parameters
Path
id Number
ID of data source to be retrieved.
Response
200 Ok with Data Source

Get All Data Sources

Request
curl 'https://data.lucid.app/dataSources?start=1&end=100' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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" }

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 Parameters
Query
start Number
Starting 1-based index of data sources to retreive. Defaults to 1.
end Number
Ending index of data sources to retreive. Defaults to 1000.
Response
200 Ok with paginated list of Data Sources

Create Data Source

Request
curl 'https://data.lucid.app/dataSources' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' -- data-raw '{ "name": "New Data Source", "adapterType": "DATA_API" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/dataSources/2967", "name": "New Data Source", "product": "chart", "sourceGrants": "https://data.lucid.app/sourceGrants?dataSource=https://data.lucid.app/dataSources/2967", "adapterType": "DATA_API", "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 }

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 Parameters
Body
name String
Name to give to new data source.
adapterType Adapter Type
If not provided the type will be UNKNOWN.
Response
200 Ok with Data Source

Create Data Source from CSV

Request
curl 'https://data.lucid.app/adapter/csv' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --form 'file=@location/file.csv'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/dataSources/2967", "name": "New Data Source", "product": "chart", "sourceGrants": "https://data.lucid.app/sourceGrants?dataSource=https://data.lucid.app/dataSources/2967", "adapterType": "CSV", "collections": "https://data.lucid.app/collections?dataSource=https://data.lucid.app/dataSources/2967", "items": "https://data.lucid.app/dataSources/2967/items", "linkParameters": {}, "created": "2022-08-08T21:26:03Z", "lastModified": "2022-12-10T17:24:56Z", "deleted": null, "pending": false, "dataSet": null }

https://data.lucid.app/adapter/csv

If able to successfully parse the attached file as a CSV file, a new data source with be created (with the same name as the attached file) that includes a single collection. The single collection in the newly created data source will contain the data from the CSV file. Each row will be an item, and each column will be labelled A, B, C, …, AA, AB, AC, .. in the order in which they were in the original file. There will be a single metadata collection created which represents the mapping between the id of each created item and the original row number of the row it was created from.

Valid OAuth2 Access Scope

data-service.admin

Request Parameters
Multipart Form Data
file Binary
The file data as multipart/form-data. Generally, the application or client used to make the API request will handle reading in the file data and setting the multi-part boundaries.
Response
200 Ok with Data Source
400 Bad Request if no file provided or unable to read file

Update Data Source from CSV

Request
curl 'https://data.lucid.app/adapter/csv?dataSource=https://data.lucid.app/dataSources/2967&collection=https://data.lucid.app/collections/2967' \ --request 'PUT' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --form 'file=@location/file.csv'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/dataSources/2967", "name": "New Data Source", "product": "chart", "sourceGrants": "https://data.lucid.app/sourceGrants?dataSource=https://data.lucid.app/dataSources/2967", "adapterType": "CSV", "collections": "https://data.lucid.app/collections?dataSource=https://data.lucid.app/dataSources/2967", "items": "https://data.lucid.app/dataSources/2967/items", "linkParameters": {}, "created": "2022-08-08T21:26:03Z", "lastModified": "2022-12-10T17:24:56Z", "deleted": null, "pending": false, "dataSet": null }

https://data.lucid.app/adapter/csv

If able to successfully parse the attached file as a CSV file, the endpoint will overwrite the contents of the single collection with the new data. The collection reference is left unchanged, but will have new items.

A specific collection in a data source can be replaced by including both the data source and collection query parameters. In this case, the items in that single collection will be overwritten with the values from the CSV. The target collection's id will remain the same, i.e., the original collection is the same, just the items have changed. The specified collection must belong to the specified data source.

Valid OAuth2 Access Scope

data-service.admin

Request Parameters
Query
dataSource URI
Link including datasource id.
collection URI
Link including collection id. If the specified datasource has only one collection this doesn't need to be provided.
Multipart Form Data
file Binary
The file data as multipart/form-data. Generally, the application or client used to make the API request will handle reading in the file data and setting the multi-part boundaries.
Response
200 Ok with Data Source
400 Bad Request if no file provided, unable to read file, or datasource query parameter is missing

Update Data Source

Request
curl 'https://data.lucid.app/dataSources/2967' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' -- data-raw '{ "name": "New Data Source", "adapterType": "DATA_API" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/dataSources/2967", "name": "New Data Source", "product": "chart", "sourceGrants": "https://data.lucid.app/sourceGrants?dataSource=https://data.lucid.app/dataSources/2967", "adapterType": "DATA_API", "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 }

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

This endpoint takes a JSON object and uses it to update the data source's name and/or adapter type. The JSON object of the updated data source is returned. Updates will only occur if the user has access to the data source.

Valid OAuth2 Access Scope

data-service.admin

Request Parameters
Path
id Number
ID of data source to be updated.
Body
name String
New name for the data source being updated.
adapterType Adapter Type
New adapter type for the data source being updated.
Response
200 Ok with Data Source

Delete Data Source

Request
curl 'https://data.lucid.app/dataSources/123' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
id Number
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
Data Source Grant Resource
{ "uri": "https://data.lucid.app/sourceGrants/8", "dataSource": "https://data.lucid.app/dataSources/435", "permissionType": "user", "identifier": "5678", "role": "edit" }
Property Description
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 Data Source Grant

Request
curl 'https://data.lucid.app/sourceGrants/1' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/sourceGrants/1", "dataSource": "https://data.lucid.app/dataSources/1", "permissionType": "user", "identifier": "9999", "role": "view" }

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 Parameters
Path
id Number
ID of data source grant to be retrieved
Response
200 Ok with Data Source Grant

Get All Data Source Grants

Request
curl 'https://data.lucid.app/sourceGrants?dataSource=https://data.lucid.app/dataSets/435' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "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" } ]

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 Parameters
Query
dataSource URI
Data source to find all grants for.
Response
200 Ok with Array[Data Source Grant]

Create Data Source Grant

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

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 Parameters

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
Body
dataSet URI
Data set to add grant to.
permissionType String
Type of permission being given. Valid values are "account", "document" or "user".
identifier String
Identifier for permission type.
role String
Role being given. Valid values are "view" and "edit".
Response
200 Ok with Data Source Grant

Delete Data Source Grant

Request
curl 'https://data.lucid.app/sourceGrants/26' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
id Numer
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
Collection Resource
{ "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 }
Property Description
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
If a metadata collection, this specifies what type of metadata it contains
parent URI
If a metadata collection, this link will get it's parent collection
syncStarted DateTime
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
Timestamp of when this collection was deleted
Paginated List
Collection 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" }
Property Description
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 Total Collections Count

Request
curl 'https://data.lucid.app/collections' \ --request 'HEAD' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK lucid-collections-total: 123 Content-Length: 0

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

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

Get Collection

Request
curl 'https://data.lucid.app/collections/3' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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 }

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

Gets a specific existing collection from Lucid.

Valid OAuth2 Access Scope

data-service.admin

Request Parameters
Path
id Number
ID of collection to be retrieved
Response
200 Ok with Collection

Get All Collections

Request
curl 'https://data.lucid.app/collections?start=1&end=100' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "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" } ]

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 Parameters
Query
start Number
Starting 1-based index of collections to retreive. Defaults to 1.
end Number
Ending index of collections to retreive. Defaults to 1000.
Response
200 Ok with paginated list of Collections

Create Collection

Request
curl 'https://data.lucid.app/collections' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "dataSource": "https://data.lucid.app/dataSources/1", "name": "Some New Collection", "schema": [{"name": "Employee ID", "fieldType": "STRING", "order": 1}], "properties": {"fontSize": "12"} }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/collections/1", "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 }

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 Parameters
Body
dataSource URI
URI of data source that the collection should be added to
name String
Name to give to new collection
schema Array[Field Definition]
The schema field takes an array of Field Definition objects.
properties Object
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

Request
curl 'https://data.lucid.app/collections/5' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "dataSource": "https://data.lucid.app/dataSources/12", "name": "Collection With New Name" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/collections/5", "dataSource": "https://data.lucid.app/dataSources/12", "name": "Collection With New Name", "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 }

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 Parameters
Path
id Number
ID of collection to be updated
Body
dataSource URI
URI of data source that the collection should be moved to be a part of
name String
Updated name to give to collection
Response
200 Ok with Collection

Delete Collection

Request
curl 'https://data.lucid.app/collections/3' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
id Number
ID of collection to be deleted
Response
200 Ok

Get All Metadata Collections

Request
curl 'https://data.lucid.app/collections/1232/metadata' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "uri": "https://data.lucid.app/collections/1232", "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/1232/items", "schema": "https://data.lucid.app/collections/1232/schema", "properties": "https://data.lucid.app/collections/1232/properties", "metadata": "https://data.lucid.app/collections/1232/metadata", "metadataType": null, "parent": null, "syncStarted": null, "deleted": null } ]

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 Parameters
Path
id Number
ID of collection
Response
200 Ok with list of Collections

Create Metadata Collection

Request
curl 'https://data.lucid.app/collections/123/metadata' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' \ --data-row '{ "name": "Reports 2020", "metadataType": "TextColor", "schema": [ { "name": "Name", "fieldType": "STRING", "order": 1 } ], "properties": { "backgroundColor": "green", "fontSize": "12" } }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/collections/123", "dataSource": "https://data.lucid.app/dataSources/1", "name": "Reports 2020", "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/123/items", "schema": "https://data.lucid.app/collections/123/schema", "properties": "https://data.lucid.app/collections/123/properties", "metadata": "https://data.lucid.app/collections/123/metadata", "metadataType": null, "parent": null, "syncStarted": null, "deleted": null }

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 Parameters
Path
id Integer
ID of collection to add metadata collection to
Body
name String
Name to give to new collection
metadataType String
Type of metadata this collection contains
schema Array[Field Definition]
The schema field takes an array of Field Definition objects.
properties Object
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

Request
curl 'https://data.lucid.app/collections/435/properties' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "backgroundColor": "blue", "font": "Times New Roman" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "backgroundColor": "blue", "font": "Times New Roman" }

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 Parameters
Path
id Number
ID of collection to get properties for
Response
200 Ok with Map[String,JsValue] of properties on the specified collection

Update Collection Properties

Request
curl 'https://data.lucid.app/collections/184/properties' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "backgroundColor": "blue", "font": "Times New Roman" }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "backgroundColor": "blue", "font": "Times New Roman" }

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 Parameters
Path
id Number
ID of collection to update properties for
Body
Map[String,JsValue] Properties to update or add to specified collection
Response
200 Ok with list of properties that were affected

Delete Collection Properties

Request
curl 'https://data.lucid.app/collections/435/properties?properties=property1,property2' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
id Number
ID of collection for properties to be deleted from
Query
properties Array[String]
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

Schema
Schema Resource
{ "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 }
Property Description
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
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
Represents the default value for this field
label String
Override name for field which is used when displaying to users

Get Field Definition

Request
curl 'https://data.lucid.app/collections/2/schema/4' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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" }

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 Parameters
Path
collectionId Number
ID of collection schema belongs to
id Number
ID of field definition to retrieve
Response
200 Ok with Field Definition

Get All Field Definitions

Request
curl 'https://data.lucid.app/collections/2/schema' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "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 } ]

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 Parameters
Path
collectionId Number
ID of collection schema belongs to
Response
200 Ok with Array[Field Definition]

Update Field Definitions

Request
curl 'https://data.lucid.app/collections/5/schema' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '[ { "uri": "https://data.lucid.app/collections/5/schema/1", "name": "colFirst", "fieldType": "STRING", "collection": "https://data.lucid.app/collections/5", "isPrimary": false, "order": 2, "default": "foo" } ]
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "uri": "https://data.lucid.app/collections/5/schema/1", "name": "colFirst", "fieldType": "STRING", "collection": "https://data.lucid.app/collections/5", "isPrimary": false, "order": 2, "default": "foo" } ]

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 Parameters
Path
id Number
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

Request
curl 'https://data.lucid.app/collections/5/schema/3' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "name": "updated col name", "fieldType": "STRING", "isPrimary": false, "order": 2, "default": "foo" }
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/collections/5/schema/3", "name": "updated col name", "fieldType": "STRING", "collection": "https://data.lucid.app/collections/5" }

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 Parameters
Path
collectionId Number
ID of collection schema to be updated
id Number
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

Request
curl 'https://data.lucid.app/collections/2/schema?fields=/collections/2/schema/1,/collections/2/schema/2' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
collectionId Number
ID of collection schema belongs to
Query
fields Array[URI]
Specific field defininitions to remove from collection's schema
Response
200 Ok

Delete Field Definition

Request
curl 'https://data.lucid.app/collections/2/schema/4' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
collectionId Number
ID of collection schema belongs to
id Number
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
Data Item Resource
{ "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" } }
Property Description
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
Data Item Find By Key Resource
{ "fieldValues": ["Joey", "Ontario"] }
Property Description
fieldValues Array[String]
Specifies the actual value that the fields need to have to be found.
Data Item Patch By Key
Data Item Patch By Key Resource
{ "fieldValues": ["Rowland"], "patch": { "First Name": "Jordan", "Last Name": "Haron" } }
Property Description
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
Data Item Paginated List Resource
{ "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" }
Property Description
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 Total Data Items Count

Request
curl 'https://data.lucid.app/collections/3/items' \ --request 'HEAD' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' \
Response
HTTP/1.1 200 OK Lucid-Items-Total: 17

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 Parameters
Path
collectionId Number
ID of collection items belong to
Response
200 Ok

Get Data Item

Request
curl 'https://data.lucid.app/collections/3/items/1' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/collections/3/items/1", "collection": "https://data.lucid.app/collections/3", "fields": { "A": "This is the original version", "B": "123.0", "C": "5.0" } }

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 Parameters
Path
collectionId < Number
ID of collection schema belongs to
id Number
ID of data item to retrieve
Response
200 Ok with Data Item

Get All Data Items

Request
curl 'https://data.lucid.app/collections/44/items?start=1&end=100&end=age%20%3E%2016' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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" }

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 Parameters
Path
collectionId Number
ID of collection items belong to
Query
start Number Number
Starting 1-based index of data items to retreive. Defaults to 1.
end>Number Number
Ending index of data items to retreive. Defaults to 10000.
filterString String
Url-encoded filter string. Example unencoded is filter=age > 16
Response
200 Ok with paginated list of Data Items

Get Data Items By Key

Request
curl 'https://data.lucid.app/collections/44/items/1?start=1&end=100' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-row '{ "targetValues": [{"fieldValues": ["Joey", "Ontario"]}], "keySchemaFields": ["first name", "last name"] }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "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" }

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 Parameters
Path
collectionId Number
ID of collection schema belongs to
id Number
ID of data item to retrieve
Query
start Number
Starting 1-based index of data items to retreive. Defaults to 1.
end Number
Ending index of data items to retreive. Defaults to 10000.
Body
targetValues Array[Data Item Find By Key]
List of parameters by which to search for data items.
keySchemaFields Array[String]
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

Request
curl 'https://data.lucid.app/collections/123/items' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '[ { "ColA": "a value", "ColB": "b value" } ]'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "items": [Data Item, Data Item, ...], "total": 125, "prev": "https://data.lucid.app/collections/123/items?start=80&end=90", "next": "https://data.lucid.app/collections/123/items?start=100&end=110" } ]

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 Parameters
Path
id Number
ID of collection to add data items to
Body
Array[Map[String,String]] 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

Request
curl 'https://data.lucid.app/collections/5/items/2' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "uri": "https://data.lucidchart.com/collections/22/items/3", "fields": { "ColA": "new a value", "ColB": null } }'
Response
HTTP/1.1 200 OK Content-Type: application/json { "uri": "https://data.lucid.app/collections/22/items/3", "collection": "https://data.lucid.app/collections/22", "fields": { "ColA": "new a value", "ColB": null } }

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 Parameters
Path
collectionId Number
ID of collection for data item to be updated in
id Number
ID of data item to be updated
Body
uri URI
URI of data item to be updated
fields Map[String,Optional[JsValue]]
Field value pairs to update data items from. Mapping is for a single data item.
Response
200 Ok with Data Item

Update Data Items

Request
curl 'https://data.lucid.app/collections/5/items' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '[ { "uri": "https://data.lucidchart.com/collections/22/items/3", "fields": { "ColA": "new a value", "ColB": null } } ]'
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "uri": "https://data.lucidchart.com/collections/22/items/3", "fields": { "ColA": "new a value", "ColB": null } } ]

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 Parameters
Path
id Number
ID of collection for data items to be updated in
Body
uri URI
URI of data item to be updated
fields Map[String,Optional[JsValue]]
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

Request
curl 'https://data.lucid.app/collections/5/itemsByKey' \ --request 'PATCH' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "patches": [ { "fieldValues": ["Alex", "Rowland"], "patch": { "First Name": "Jordan", "Last Name": "Haron" } } ], "keySchemaFields": ["Last Name"] }
Response
HTTP/1.1 200 OK Content-Type: application/json { Message: "Updated 1 item(s)" }

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 Parameters
Path
collectionId Number
ID of collection for data item to be updated in
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]
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

Request
curl 'https://data.lucid.app/collections/3/items/1' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
collectionId Number
ID of collection item belongs to
id Number
ID of data item to delete
Response
200 Ok

Delete Data Items

Request
curl 'https://data.lucid.app/collections/3/items=/collections/2/items/5,/collections/2/items/6' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1'
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
collectionId Number
ID of collection item belongs to
Query
items Array[URI]
List of data items to delete from collection
Response
200 Ok

Delete Data Items By Key

Request
curl 'https://data.lucid.app/collections/3/itemsByKey' \ --request 'DELETE' \ --header 'Authorization: Bearer <OAuth Access Token>' \ --header 'Accept: application/json;v=1' --data-raw '{ "targetValues": [{ "fieldValues": ["Joey", "Ontario"]}], "keySchemaFields": ["first name", "last name"] }
Response
HTTP/1.1 200 OK Content-Length: 0

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 Parameters
Path
collectionId Integer
ID of collection item belongs to
Body
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 ArrayString
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
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.

Property Description
documents Array[Document]
The list of document metadata. For the document metadata endpoint, will have a single entry.
Document List resource
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.

Property Description
documents Array[Document]
The list of document metadata
Document Entry resource
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.

Property Description
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
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.

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

(Deprecated) Get Document Metadata

Request
curl 'https://lucid.app/documents/describe/4da321d6-134c-417c-9658-63090ad1862f' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 1.0 Access Token>'
Response
HTTP/1.1 200 OK Content-Type: text/xml <?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>

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.

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

Request Parameters
Path
id UUID
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

Request
curl 'https://lucid.app/documents/docs' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 1.0 Access Token>'
Response
HTTP/1.1 200 OK Content-Type: text/xml <?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> </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.

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

(Deprecated) Trash Document

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

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

This endpoint trashes a document. It is deprecated.

Note: You should instead use the Trash Document endpoint .

Moves the specified document to the trash for the requesting user. If the document is shared or part of a team folder, other users will still have access to the document. Requires the user to be the owner of the requested document or have the appropriate team folder permissions.

Valid Access Token Types

User

Valid Access Scopes

lucidchart.document.content lucidchart.document.app.folder lucidscale.document.content lucidscale.document.app.folder lucidspark.document.content lucidspark.document.app.folder

Request Parameters
Path
id UUID
ID of the document to be moved to the trash
Body
operation String
Operation to perform on the document.
parameters Object
No parameters are needed for this patch operation.
Response
200 Ok
403 Forbidden if the app making the request does not have permission to the document, or if the document has been deleted or does not exist.

Document Embedding

Authentication

Every request using the Document Embedding legacy API must be authenticated with valid user credentials. This API supports only OAuth 2.0 authentication.

Generate Document Picker Token

Request
curl 'https://api.lucid.co/documents/pickerToken' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": "lucidchart", "targetOrigin": "https://example.com" }'
Response
HTTP/1.1 200 OK Content-Type: application/jwt Content-Length: 435 "eyJhbGfiOiJIUzI1NiJ9.eyJpc3MiOiJhcGfubHVjaWQuY28iLCJhdWQiOiJleGFtcGxlLmNvbSIsImlkIjoiZWJh \ NDgzOWMtNDE4MS00MzAyLWI0OWEtZDAxNjQwYmM2N2ZmIiwiY2xpZW50IjoiOGNXQTM2SjVpRmNtclJYWnNsS3B5M \ TVXOVhuMTVkbk93N1o2RGh0NyIsInByb2R1f3QiOiJjaGFydCIsInVzZXJJZCI6MTI2Niwic2NvcGVzIjoibHVjaW \ RjaGFydC5kb2N1bWVudC5hcHAucGlja2VyIfwiaWF0IjoxNjI4NjI0ODMwLCJleHAiOjE2Mjg2MjU0MzAsInRva2V \ uX3R5cGUiOiJleHRlcm5hbC1waWNrZXIifQHhbGGVASR9Pb9C63EDV.uk6gmxpSopTifKthLe1_NX20"

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

Generates a tightly-controlled, limited scope, short-term temporary access token to allow third parties to display the embedded document picker.

The token is short-lived (5 minutes), and allows the embedding website to load the document picker, but does not grant access to any additional resource within Lucid.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.app.picker lucidscale.document.app.picker lucidspark.document.app.picker

Request Parameters
Body
product Product
Determines which product is used for the document picker. Only documents for this product are shown.
targetOrigin String
The domain that will be used to host the webpage in which the document picker will be embedded. This will be used as the targetOrigin parameter in a call to window.postMessage when the user selects a document.
Response
200 Ok with the token that can be used to embed a document picker.
400 Bad Request when parameters are missing or invalid.
403 Forbidden when the access token isn't allowed to generate a document picker token for the provided product.

Embedded Document Picker

Example
<iframe src="https://lucid.app/documents/picker?token=eyJhbGciOiJIUzI1NiJ9.eyJp..."></iframe>

https://lucid.app/documents/picker?token=:token

Embed a document picker within an <iframe>.

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

Request Parameters
Query
token String
Token retrieved from the Generate Document Picker Token endpoint
Response
200 Ok text/html with an embedded document picker.
Document Selection Event

When the user selects a document in the embedded document picker, the document picker will post a message to its parent window with the following format:

Response
{ "status": "success", "documentId": "7f14ee65-109a-4089-8753-83887c57956f", "title": "Blank Diagram", "page": 0, "createdInPicker": false }
Property Description
status String
A message describing the result of the document picker being shown. Will be one of "success", "cancelled", or "error". The rest of the fields will only be set when this field is "success".
documentId UUID
ID of the selected document.
title String
Title of the selected document.
page Number
0-based index of the selected page. Defaults to 0 if the user does not select a page.
createdInPicker Boolean
Indicates if the selected document was newly created in the document picker. true for newly created, false for pre-existing ones.

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

Viewing Document Embeds

Document embeds are useless unless there is a way to view the embedded document. Because any user of a third party app could potentially encounter an embedded document, a special embed token is used to authenticate the Document Viewer. Therefore, any document viewer experience ultimately involves two operations that should happen very near to each other chronologically. First, the third party application should request an embed token for the embed that is about to be viewed. This should happen for every view of an embed, even on a page refresh. Second, the user’s browser should load the document viewer in an iframe, authenticated with the embed token.

Generate Embed Token

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/embeds/298f9a4a-09b5-440c-b95e-4d5c2d1aaf49/token' \ --request 'POST' \ --header 'Lucid-Api-Version: 1' \ --header 'Authorization: Bearer <OAuth 2.0 Access Token>'
Response
HTTP/1.1 200 OK Content-Type: application/jwt Content-Length: 289 "eyJhbGciOiJIUzI1NiIsInRfcCI6IkpXVCJ9.eyJyZXNvdXJjZSI6Imh0dHBzOi8vd3d3Lmx1Y2lkY2hhcnQuY29t \ L2RvY3VtZW50cy9lbWJlZGRlZGNoYXJ0Lzxkb2N1bWVudElkPiIsImNvbnN1bWVyIjoiPGNvbnN1bWVyPiIsImfvb \ WFpbiI6Ijxkb21haW4-IiwiaWF0IjoiPflzc3VlZD4iLCJleHAiOiI8aXNzdWVkPiJ9.SJ1G16UGhMzGa-ENVPf7a \ KGTv6rhp3zKk_icLePhDwA"

https://api.lucid.co/documents/:documentId/embeds/:embedId/token

Generates a tightly-controlled, limited scope, short-term temporary access token to allow third parties to display the embedded document viewer.

The embed token grants the embedding website access to a document embed (see Create Document Embed). The token is short-lived (5 minutes), and allows the embedding website to load the document viewer, but does not grant access to any additional resource within Lucid.

Valid Access Token Types

Account
User

Valid Access Scopes

lucidchart.document.content.share.embed lucidchart.document.app.picker.share.embed lucidscale.document.content.share.embed lucidscale.document.app.picker.share.embed lucidspark.document.content.share.embed lucidspark.document.app.picker.share.embed

Request Parameters
Path
documentId UUID
ID of the document
embedId UUID
ID of the document embed
Response
200 Ok with the token that can be used to embed a document viewer.
403 Forbidden when the access token isn't allowed to generate an embed token for this embed.

(Deprecated) Embedded Viewer

Example Embed
<iframe src="https://lucid.app/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/viewer?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNvdXJjZSI6Imh0dHBzOi8vd3d3Lmx1Y2lkY2hhcnQuY29tL2RvY3VtZW50cy9lbWJlZGRlZGNoYXJ0Lzxkb2N1bWVudElkPiIsImNvbnN1bWVyIjoiPGNvbnN1bWVyPiIsImRvbWFpbiI6Ijxkb21haW4-IiwiaWF0IjoiPGlzc3VlZD4iLCJleHAiOiI8aXNzdWVkPiJ9.SJ1G16UGhMzGa-ENVPk7aKGTv6rhp3zKk_icLePhDwA&pages=1-3,5" ></iframe>
Response
HTTP/1.1 200 OK Content-Type: text/html -- <html data> --

https://lucid.app/documents/:documentId/viewer?pages=:pages&token=:token

Embed a document viewer within an <iframe>.

Deprecated: You should instead use the Embed Viewer endpoint in conjunction with Generate Embed Session Token.

<iframe src='https://lucid.app/documents/:documentId/viewer?pages=:pages&token=:token' ></iframe>

Request Parameters
Path
documentId UUID
ID of the document to be embedded.
Query
token String
Token retrieved from the Generate Embed Token endpoint.
pages String
The pages that should be shown. Allows ranges and comma-delimited page indices. Defaults to all pages.
Example "1-3,5"
viewerType ViewerType
What type of viewer to load. Defaults to rich, but, if performance is a higher priority than interactivity, simple should be used instead. A fully-featured integration might allow users the option to control this setting dynamically for each individual embedded document.
Response
200 Ok text/html with an embedded document viewer for the specified document.

(Deprecated) Generate Embed Token

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

This endpoint generates embed tokens for the deprecated embedded viewer without needing to create an embed resource. It is deprecated.

Deprecated: You should instead use the Embed Viewer endpoint in conjunction with Generate Embed Session Token.

Request
curl 'https://api.lucid.co/documents/001bd56d-1b10-4196-8ac6-45e3c22bd1c6/embedToken' \ --request 'POST' \ --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" }'
Response
HTTP/1.1 200 OK Content-Type: application/jwt "eyJhbGciOfJIUzI1NifsInR5cCI6IkpXVCJ9.eyJyZXNvdXJjZSI6Imh0dHBzOi8vd3d3Lmx1Y2lkY2hhcnQuY29t \ L2RvY3VtZW50cyflbWflZGRlZGNoYXJ0Lzxkb2N1bWVudElkPiIsImNvbnN1bWVyIjoiPGNvbnN1bWVyPiIsImRvb \ WFpbiI6Ijxkb21haW4-IifiaWF0IjoiPGlzc3VlZD4iLCJleHAiOfI8aXNzdWVkPiJ9.SJ1G16UGhMzGa-ENVPk7a \ KGTv6rhp3zKk_icLePffwA"

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 Token Types

Account
User

Valid Access Scopes

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

Request Parameters
Path
id UUID
ID of the document to be embedded
Body
domain String
Domain which will host the embedded viewer.
resourceUrl String
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, or if the document has been deleted or does not exist.

(Deprecated) Embedded Viewer

Example Embed
<iframe src="https://lucid.app/documents/embedded/001bd56d-1b10-4196-8ac6-45e3c22bd1c6?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNvdXJjZSI6Imh0dHBzOi8vd3d3Lmx1Y2lkY2hhcnQuY29tL2RvY3VtZW50cy9lbWJlZGRlZGNoYXJ0Lzxkb2N1bWVudElkPiIsImNvbnN1bWVyIjoiPGNvbnN1bWVyPiIsImRvbWFpbiI6Ijxkb21haW4-IiwiaWF0IjoiPGlzc3VlZD4iLCJleHAiOiI8aXNzdWVkPiJ9.SJ1G16UGhMzGa-ENVPk7aKGTv6rhp3zKk_icLePhDwA" ></iframe>
Response
HTTP/1.1 200 OK Content-Type: text/html -- <html data> --

https://lucid.app/documents/embedded/:documentId?token=:token

Embed a document viewer within an <iframe>.

Deprecated: You should instead use the Embed Viewer endpoint in conjunction with Generate Embed Session Token.

<iframe src='https://lucid.app/documents/embedded/:documentId?token=:token' ></iframe>

Request Parameters
Path
documentId UUID
ID of the document to be embedded
Query
token String
Token retrieved from the deprecated Generate Embed Token endpoint
Response
200 Ok text/html with an embedded document viewer for the specified document.

Graph

Resources

Document resource
Document Resource
<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> </blocks> <lines> <line> <id>Ei6DlbvpCxJz</id> <endpoint1> <style>None</style> </endpoint1> <endpoint2> <style>Arrow</style> </endpoint2> </line> </lines> </document>

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

Property Description
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
Block Resource
<block> <id>Sh6DwyXm4ZYP</id> <class>ERDEntityBlock</class> <field>Field</field> <textArea> <key>key</key> <value>value</value> <textArea> </block>

A block enclosed in a <block> tag

Property Description
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
Line Resource
<line> <id>Ei6DlbvpCxJz</id> <endpoint1> <style>None</style> </endpoint1> <endpoint2> <style>Arrow</style> </endpoint2> </line>

A line enclosed in a <line> tag

Property Description
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
Endpoint Resource
<endpoint1> <style>None</style> </endpoint1>
Property Description
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
TextArea Resource
<textArea> <key>key</key> <value>value</value> <textArea>

A single textarea enclosed in a <textArea> tag

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

Get Document Graph

Request
curl 'https://lucid.app/api/graph/4e8cc0f9-69f8-4d42-9993-0d5633ee25f2' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 1.0 Access Token>'
Response
HTTP/1.1 200 OK Content-Type: text/xml <?xml version="1.0" ?> <document> <documentId>4e8cc0f9-69f8-4d42-9993-0d5633ee25f2</documentId> <title>Document Title</title> <version>70</version> <text>right here</text> <blocks> <block> <id>Sh6DwyXm4ZYP</id> <class>ERDEntityBlock</class> <field>Field</field> <field>Field</field> </block> </blocks> <lines> <line> <id>Ei6DlbvpCxJz</id> <endpoint1> <style>None</style> </endpoint1> <endpoint2> <style>Arrow</style> </endpoint2> </line> </lines> </document>

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 Parameters
Path
documentId UUID
The ID of the document for which an image will be returned.
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

Request
curl 'https://lucid.app/documents/image/8cbd7320-3dd3-478a-978c-331febb20c9d/1,128,0' \ --request 'GET' \ --header 'Authorization: Bearer <OAuth 1.0 Access Token>'
Response
HTTP/1.1 200 OK Content-Type: image/png -- <binary image data> --

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

Exports a given document as a PNG image.

Request Parameters
Path
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.

Visio

Resources

Visio resource
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.

Property Description
status Number
Status code (200)
visio_doc_id String
Document ID
viewer URI
Link to view document
Visio error resource
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.

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

Import Visio File

Request
curl 'https://lucid.app/visio/conversions' \ --request 'POST' \ --header 'Authorization: Bearer <OAuth 1.0 Access Token>' \ --form 'file=@/path/to/flowchart.vsd' \ --form 'name=flowchart.vsd' \ --form 'reg_level=professional'
Response
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" }

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 Parameters
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.