# How to Integrate Retool with Lucidchart

- Tool: Retool
- Difficulty: Beginner
- Time required: 15 minutes
- Last updated: April 2026

## TL;DR

Use Lucidchart with Retool by embedding diagrams as iframes in Retool apps and connecting to the Lucidchart API via a REST API Resource for automated diagram access. Lucidchart is ideal for documenting Retool app architecture — data flows, query chains, and Resource connections — and for embedding architecture diagrams directly into your internal dashboards for live reference.

## Use Lucidchart for Retool Architecture Documentation and Embedded Diagrams

Retool apps can grow complex quickly — especially when combining multiple Resources (databases, REST APIs, SaaS connectors), JavaScript transformers, cross-query event handlers, and multi-tab layouts. Documenting how these pieces fit together is critical for onboarding new team members, debugging unexpected query behavior, and planning future extensions. Lucidchart is the most widely-used tool for this kind of technical documentation, offering purpose-built shapes for API flows, database schemas, and system architecture.

There are two practical integration patterns. First, you can embed Lucidchart diagrams directly into Retool apps using Retool's IFrame component — this is useful for internal tools that serve as reference hubs, where teams expect to see both live data and the architecture context side by side. A Retool DevOps dashboard, for instance, might show live database metrics alongside an embedded Lucidchart diagram of the database schema.

Second, Lucidchart provides a REST API that allows programmatic access to document metadata — listing documents, accessing sharing links, and retrieving document properties. You can build a Retool panel that serves as a searchable index of all architecture documentation across your organization, pulling document metadata from Lucidchart and surfacing links to the relevant diagrams based on the Retool resource or application the user is working with.

## Before you start

- A Lucidchart account with at least one diagram (Team or Enterprise plan recommended for API access and sharing controls)
- Architecture diagrams already created in Lucidchart documenting your Retool apps, data flows, or system design
- Lucidchart API credentials (OAuth 2.0 client ID and secret — available in Lucidchart account settings for API-enabled plans)
- A Retool account with permission to create Resources and build apps
- Basic familiarity with Retool's IFrame component and query editor

## Step-by-step guide

### 1. Publish Lucidchart diagrams for embedding

Before embedding a Lucidchart diagram in Retool, you need to generate an embeddable link from Lucidchart. Open the diagram you want to embed in Lucidchart. Click File → Publish / Share. In the share dialog, navigate to the Embed tab. Lucidchart provides an iframe HTML snippet — copy the src URL from the snippet. It will look like: https://lucid.app/documents/embeddedchart/DOCUMENT_ID.

Ensure the sharing settings allow the appropriate audience to view the document. For internal Retool tools where all users are authenticated with the same domain, set sharing to 'Anyone in my organization can view'. If Retool embeds the diagram for users outside your organization, set it to 'Anyone with the link can view'.

For security-sensitive diagrams (showing production database schemas, authentication flows, etc.), use domain-restricted sharing so only users with your company email can view the embedded document.

Repeat this process for each diagram you want to embed. Collect all the embed URLs in a table — a simple Retool Database table works well for tracking diagram URLs alongside app/resource names and descriptions. This makes it easy to add a dropdown selector in Retool that switches between different architecture diagrams.

**Expected result:** You have embeddable Lucidchart URLs for your architecture diagrams, with appropriate sharing settings configured for your team's access level.

### 2. Embed Lucidchart diagrams in a Retool app using the IFrame component

Open your Retool application in the editor. From the Components panel on the left, drag an IFrame component onto the canvas. Position it to take up the right half or bottom section of your layout — this leaves room for Table or form components on the left.

Select the IFrame component and open its settings in the right panel. Set the Src property to the Lucidchart embed URL you copied. To make the embed dynamic (showing different diagrams based on user selection), bind the Src to a Retool expression:

If you're using a Select component named select_diagram with diagram URLs as option values:
{{ select_diagram.value }}

If you're using a Table with a lucidchart_url column:
{{ table_apps.selectedRow?.data?.lucidchart_url || 'https://lucid.app/documents/embeddedchart/YOUR_DEFAULT_ID' }}

Set the Height of the IFrame component to at least 500px so the diagram is usable — you can also use a full-height container and set the IFrame to 100% height within it.

Optionally, add a fullscreen button next to the IFrame using a Button component. Set its onClick to window.open(select_diagram.value, '_blank') to open the diagram in Lucidchart directly for editing.

If the IFrame shows a blank or 'Refused to display' error, the sharing settings on the diagram need to be updated — ensure the public share or organization share is enabled for the document.

**Expected result:** The Retool app shows a Lucidchart diagram embedded in an IFrame. Selecting different rows in a Table or different options in a dropdown updates the diagram displayed.

### 3. Configure the Lucidchart API Resource in Retool

For programmatic access to your Lucidchart documents (listing all diagrams, getting metadata, searching by title), you can connect to the Lucidchart API via a REST API Resource.

Lucidchart uses OAuth 2.0. To generate an access token: go to your Lucidchart account settings, navigate to the Developer section, and create an OAuth application. Note the Client ID and Client Secret.

To obtain a Bearer token for Retool, use the OAuth 2.0 authorization flow. For a simpler approach with Lucidchart's API v1, some endpoints accept a basic API token that can be generated in account settings — check Lucidchart's current developer documentation for the authentication method available on your plan tier.

In Retool, navigate to the Resources tab and click Add Resource. Select REST API.

Name: Lucidchart API
Base URL: https://api.lucid.app/v1

Headers:
- Key: Authorization | Value: Bearer {{ retoolContext.configVars.LUCIDCHART_TOKEN }}
- Key: Content-Type | Value: application/json
- Key: Lucid-Api-Version | Value: 1

First, store your access token in Retool Settings → Configuration Variables as LUCIDCHART_TOKEN marked as secret.

Click Create Resource. Test with a GET to /documents — if it returns a JSON list of your Lucidchart documents, the API connection is working.

**Expected result:** The Lucidchart API resource is created and a test GET /documents returns a list of your Lucidchart documents with their IDs, titles, and metadata.

### 4. Build a Lucidchart document index in Retool

Create a query named getLucidDocuments. Set the method to GET and path to /documents. Supported query parameters include:
- product: lucidchart (filter to only Lucidchart docs, not Lucidspark)
- folder_id: {{ select_folder.value || '' }} — filter by folder
- max_results: 50

The response includes a collection array where each document has an documentId, title, createdTime, modifiedTime, product, and editUrl.

Create a transformer that maps document objects into flat rows with human-readable dates and constructs the embed URL from the documentId. The embed URL format is: https://lucid.app/documents/embeddedchart/DOCUMENT_ID.

Bind the transformed data to a Table. Configure columns: Title, Owner, Last Modified, and a Type indicator. Add a computed column for the Embed URL.

Add a search Text Input that filters the document list client-side using Retool's built-in Table filtering: bind the Table's filter to title.toLowerCase().includes(textInput_search.value.toLowerCase()).

When a document row is selected, update an IFrame component's Src to show the embedded diagram. This creates a full document browser experience: search for diagrams, preview them in the IFrame, and open the edit URL when you need to update a diagram.

```
// Transformer for Lucidchart documents
const docs = data.collection || [];
return docs.map(doc => ({
  document_id: doc.documentId,
  title: doc.title || '(Untitled)',
  product: doc.product || 'lucidchart',
  created: doc.createdTime ? new Date(doc.createdTime).toLocaleDateString() : '',
  modified: doc.modifiedTime ? new Date(doc.modifiedTime).toLocaleDateString() : '',
  edit_url: doc.editUrl || '',
  embed_url: `https://lucid.app/documents/embeddedchart/${doc.documentId}`
}));
```

**Expected result:** The document index Table shows all Lucidchart diagrams with titles, modification dates, and embed URLs. Selecting a row previews the diagram in the adjacent IFrame.

### 5. Use Lucidchart to document Retool architecture

Beyond embedding, Lucidchart's primary value for Retool teams is as a documentation tool for the Retool apps themselves. Here is a structured approach to documenting Retool architecture in Lucidchart using standard diagram patterns.

For a Retool Resource connection diagram, create a Lucidchart diagram showing: external data sources (databases, REST APIs, SaaS tools) → Retool Resources (labeled boxes) → Retool Apps (labeled with the app name). Use arrows to indicate data flow direction. Lucidchart's AWS and GCP shape libraries have server and database icons that work well for this.

For a query chain diagram, document how queries depend on each other within a Retool app: which queries run on page load, which are triggered by user events (button clicks, table selections), and which are chained via On Success event handlers. Use a flowchart format with decision nodes for conditional query chains.

For a component-query binding diagram, map which Retool components read from which queries: Table → getCampaigns.data, Chart → getAnalytics.data. This is particularly useful when a Retool app has 10+ queries and the bindings become difficult to trace in the editor.

Store these diagrams in a Lucidchart folder named 'Retool Architecture' and embed the folder's document list in a Retool admin dashboard. For complex multi-resource integrations with custom transformers and Workflow automations, RapidDev's team can help create comprehensive architecture documentation.

**Expected result:** You have a structured Lucidchart folder with architecture diagrams documenting your Retool apps, Resources, and query chains — embedded and accessible from a Retool documentation dashboard.

## Best practices

- Use Lucidchart's folder structure to organize diagrams by Retool app or team — create folders like 'CRM Dashboard Architecture', 'Ops Tool Architecture' — and build a Retool document index panel that filters by folder.
- Always use the Embed tab in Lucidchart's share dialog (not the regular share link) when generating URLs for IFrame embedding — the embed URL format is different and handles iframe-specific permissions correctly.
- Update architecture diagrams in Lucidchart whenever you add a new Resource, query, or major component to a Retool app — treat diagram updates as part of your development workflow, not an afterthought.
- Set Lucidchart diagrams to 'Anyone in my organization can view' for internal Retool tools rather than fully public — this maintains access controls while allowing all team members to view embedded diagrams without authentication prompts.
- Use Lucidchart's built-in shape libraries for consistency: the 'Network & Security' library for data flow diagrams, 'Entity Relationships' for database schemas, and 'Flowcharts' for query chain documentation.
- Create a Retool Workflow that runs weekly to fetch the list of Lucidchart documents and compare their modifiedTime against a stored timestamp — this alerts teams when architecture diagrams haven't been updated after recent Retool app changes.
- For Retool apps with complex multi-Resource architectures, embed the relevant architecture diagram in a collapsible panel within the app itself so debugging engineers can reference the data flow without leaving the tool.

## Use cases

### Build a Retool app documentation hub with embedded diagrams

Create a Retool internal documentation panel that lists all your Retool applications alongside their Lucidchart architecture diagrams. Users can select an app from the list, see its data flow diagram embedded as an iframe, and quickly understand which Resources and queries power each feature — ideal for onboarding engineers and for audit reviews.

Prompt example:

```
Build a Retool documentation hub with a Table listing all internal Retool apps. Include columns for app name, description, last updated date, and a link to its Lucidchart diagram. When a row is selected, display the Lucidchart diagram in an IFrame component on the right. Add a search input to filter apps by name or team.
```

### Build a Lucidchart document index panel

Create a Retool admin panel that queries the Lucidchart API to list all architecture diagrams across the organization — organized by team, project, or document type. Engineers can search for diagrams, view metadata, and open documents directly from a centralized index without navigating Lucidchart's folder structure.

Prompt example:

```
Build a Retool document browser for Lucidchart. Show a Table of all Lucidchart documents with title, owner, last modified date, and folder path. Add a search input for filtering by title. When a row is selected, display a preview IFrame showing the public share link. Include a button that opens the document in Lucidchart directly.
```

### Embed architecture context in operational dashboards

Augment existing Retool operational dashboards with relevant architecture diagrams. For example, a database monitoring dashboard that tracks query performance could include an embedded Lucidchart ER diagram showing the schema being monitored — giving engineers immediate context when investigating anomalies without switching to a separate documentation tool.

Prompt example:

```
Enhance a Retool database monitoring dashboard by adding a collapsible panel that embeds the relevant Lucidchart schema diagram for the selected database. Add a Toggle button labeled 'Show Schema' that expands/collapses the IFrame. The IFrame URL should dynamically change based on which database the user is monitoring.
```

## Troubleshooting

### Lucidchart diagram shows blank or 'Refused to Display' in the Retool IFrame

Cause: The Lucidchart document's sharing settings don't allow iframe embedding from external domains, or the document is set to private with no public access.

Solution: Open the Lucidchart document and click File → Publish / Share. Enable the Embed tab and turn on embedding. Set sharing to 'Anyone with the link can view' for public-facing embeds, or 'Anyone in my organization' for internal Retool tools. If your organization restricts iframe embedding via Content Security Policy, you may need to add lucid.app to the allowed origins list in your IT security settings.

### Lucidchart API returns 403 Forbidden on all requests

Cause: The Lucidchart API is only available on Team or Enterprise plans. Free and Individual plans do not include API access. Alternatively, the OAuth token may not have the required scopes.

Solution: Verify your Lucidchart plan includes API access by checking your account billing page or contacting Lucidchart support. If you have API access, regenerate the OAuth token and ensure the offline_access and document:read scopes are included. Check that the Lucid-Api-Version header is set to 1 in your Retool resource headers.

### The embedded Lucidchart diagram doesn't update when selecting different rows in the Retool Table

Cause: The IFrame component's Src property is not bound to a dynamic expression, or the Retool Table's selectedRow data doesn't include the diagram URL field.

Solution: In the IFrame component settings, verify the Src property uses a JavaScript expression (starts with {{ and ends with }}) referencing the Table's selectedRow. Example: {{ table_apps.selectedRow?.data?.embed_url }}. Confirm the embed_url field exists in your transformer output. Use the optional chaining operator ?. to prevent errors when no row is selected.

```
// Correct IFrame Src binding:
{{ table_apps.selectedRow?.data?.embed_url || 'https://lucid.app/documents/embeddedchart/YOUR_DEFAULT_ID' }}
```

## Frequently asked questions

### Can I embed Lucidchart diagrams directly inside a Retool app?

Yes. Use Retool's IFrame component and set the Src property to the Lucidchart embed URL from File → Publish / Share → Embed tab. Set the diagram's sharing to 'Anyone in my organization can view' for internal tools. The IFrame displays a live, interactive version of the diagram — users can pan and zoom without leaving the Retool app.

### Do I need the Lucidchart API to embed diagrams in Retool?

No. The IFrame embedding approach works with just the public embed URL from Lucidchart's share settings — no API credentials are required. The Lucidchart API is only needed if you want to programmatically list documents, search diagrams, or retrieve metadata in a Retool query. Most teams only need the IFrame approach.

### What Lucidchart plan is required for API access?

Lucidchart API access is available on Team and Enterprise plans. Individual and Free plans do not include API access. If you only need to embed diagrams via IFrame (the most common use case with Retool), any Lucidchart plan works — including Free — as long as you enable the document's embed sharing settings.

### How should I use Lucidchart to document Retool apps?

The most useful documentation patterns for Retool apps are: (1) Resource connection diagrams showing which external services connect via which Resource types, (2) query chain flowcharts showing how queries depend on and trigger each other, and (3) component-data binding maps showing which queries feed which Table, Chart, or Form components. Store these in a dedicated Lucidchart folder and embed the index in a Retool admin panel.

### Can multiple people edit a Lucidchart diagram at the same time?

Yes, Lucidchart supports real-time collaborative editing for Team and Enterprise plans. Multiple engineers can simultaneously update an architecture diagram, with changes appearing in real time for all collaborators. This makes Lucidchart effective for collaborative architecture review sessions where the team diagrams a Retool app's structure together before building.

---

Source: https://www.rapidevelopers.com/retool-integrations/lucidchart
© RapidDev — https://www.rapidevelopers.com/retool-integrations/lucidchart