Lucidchart Hello World

Overview

Minimal working examples demonstrating core Lucidchart API functionality.

Instructions

Step 1: Create a Document

const doc = await client.documents.create({
  title: 'API Architecture Diagram',
  product: 'lucidchart'  // or 'lucidspark'
});
console.log(`Document: ${doc.documentId}`);
console.log(`Edit URL: ${doc.editUrl}`);

Step 2: Add Shapes via Standard Import

// Lucid Standard Import uses .lucid file format
const importData = {
  pages: [{
    id: 'page1',
    title: 'Main',
    shapes: [
      { id: 's1', type: 'rectangle', boundingBox: { x: 100, y: 100, w: 200, h: 80 },
        text: 'API Gateway', style: { fill: '#4A90D9' } },
      { id: 's2', type: 'rectangle', boundingBox: { x: 100, y: 300, w: 200, h: 80 },
        text: 'Database', style: { fill: '#7B68EE' } }
    ],
    lines: [
      { id: 'l1', endpoint1: { shapeId: 's1' }, endpoint2: { shapeId: 's2' },
        stroke: { color: '#333', width: 2 } }
    ]
  }]
};
await client.documents.import(doc.documentId, importData);

Step 3: Export Document

const png = await client.documents.export(doc.documentId, {
  format: 'png', pageIndex: 0, scale: 2
});
fs.writeFileSync('diagram.png', png);

Error Handling

Resources

• Lucidchart API Docs

Next Steps

See lucidchart-local-dev-loop.

Lucidchart Performance Tuning

Overview

Lucidchart documents can contain thousands of shapes and connectors — a single enterprise diagram may hold 500+ elements across multiple pages, making bulk reads and exports the primary API bottleneck. This skill covers caching document metadata, batching shape operations, and managing Lucid's rate limits to keep integrations responsive.

Instructions

1. Implement Redis caching (or in-memory Map for development) with document-appropriate TTLs
2. Use cursor-based pagination for all document list operations to avoid incomplete results
3. Wrap API calls with the rate limit handler, especially for bulk shape updates and exports
4. Configure connection pooling with extended timeouts for export endpoints

Prerequisites

• Lucid OAuth2 client credentials with lucidchart.document scope
• Redis instance for document/shape metadata caching
• Node.js 18+ with native fetch
• Understanding of Lucid document structure (documents, pages, shapes, lines)

Caching Strategy

import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL);

// Document metadata is stable — cache 15 minutes
// Shape data changes during active editing — cache 1 minute
const TTL = { docList: 900, docMeta: 600, shapes: 60, exports: 300 } as const;

async function getCachedDocument(docId: string): Promise<LucidDocument> {
  const key = `lucid:doc:${docId}`;
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const doc = await lucidApi.getDocument(docId);
  await redis.setex(key, TTL.docMeta, JSON.stringify(doc));
  return doc;
}

async function getCachedShapes(docId: string, pageId: string): Promise<LucidShape[]> {
  const key = `lucid:shapes:${docId}:${pageId}`;
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const shapes = await lucidApi.getShapes(docId, pageId);
  await redis.setex(key, TTL.shapes, JSON.stringify(shapes));
  return shapes;
}

Batch Operations

import pLimit from "p-limit";

const limit = pLimit(4); // Lucid API concurrency — keep conservative

// Paginate through all documents in a workspace
async function fetchAllDocuments(folderId: string): Promise<LucidDocument[]> {
  const docs: LucidDocument[] = [];
  let cursor: string | undefined;

  do {
    const page = await lucidApi.listDocuments(folderId, { cursor, limit: 100 });
    docs.push(...page.documents);
    cursor = page.nextCursor;
  } while (cursor);

  return docs;
}

// Batch shape updates — group by page to minimize API round trips
async function batchUpdateShapes(
  docId: string,
  updates: ShapeUpdate[]
): Promise<void> {
  const byPage = groupBy(updates, (u) => u.pageId);
  for (const [pageId, pageUpdates] of Object.entri

Lucidchart Production Checklist

Overview

Lucidchart integrations interact with collaborative diagrams that may be actively edited by multiple users simultaneously. A production deployment must handle OAuth2 token lifecycle management, respect document-level collaboration locks, and account for export throttling on large diagrams. Failing to version API headers correctly causes silent schema drift, while unbounded export requests can exhaust memory on complex documents. This checklist ensures your Lucidchart integration is resilient to these collaboration and export edge cases.

Prerequisites

• OAuth2 client credentials registered in Lucid developer portal (production app)
• Secrets manager configured (Vault, AWS Secrets Manager, or GCP Secret Manager)
• Monitoring stack operational (Datadog, Grafana, or CloudWatch)
• Test workspace with sample diagrams covering all export formats (PNG, PDF, SVG)

Authentication & Secrets

• [ ] OAuth2 client ID and secret stored in vault/secrets manager (never in code)
• [ ] Token rotation implemented with refresh token flow (access tokens expire in 60 min)
• [ ] Refresh tokens stored encrypted at rest, separate from client credentials
• [ ] Token refresh logic handles concurrent requests (mutex/lock to prevent duplicate refreshes)
• [ ] Scopes restricted to minimum required (lucidchart.document.read, lucidchart.document.export)

API Integration

• [ ] Base URL points to https://api.lucid.co/v1 (production endpoint)
• [ ] Lucid-Api-Version header set explicitly on every request (pin to tested version)
• [ ] Rate limiting enforced client-side with token bucket (respect X-RateLimit-* headers)
• [ ] Pagination implemented for document listing (cursor-based with pageToken)
• [ ] Export requests set Accept header matching desired format (image/png, application/pdf)
• [ ] Large document exports use async polling pattern (POST export, poll status, GET result)
• [ ] Request timeout set to 15 seconds for reads, 120 seconds for diagram exports

Error Handling & Resilience

• [ ] Circuit breaker configured for Lucidchart API calls (open after 5 consecutive failures)
• [ ] Retry logic with exponential backoff for 429 (rate limit) and 5xx responses
• [ ] 409 Conflict responses handled for concurrent document edits (retry with latest version)
• [ ] OAuth2 401 responses trigger automatic token refresh before retry (once per request)
• [ ] Export timeout errors fall back to lower-resolution export or cached version
• [ ] Document collaboration lock detection: skip or queue writes when another user holds the lock
• [ ] Out-of-memory protection: cap export resolution for diagrams exceeding 500 obje

Lucidchart Reference Architecture

Overview

Design a version-controlled integration layer for the Lucidchart diagramming platform. Document versioning is the primary driver, so every shape mutation is tracked for diff, rollback, and branch operations while an async export pipeline renders diagrams without blocking collaboration.

Instructions

1. Provision the prerequisites below and register a Lucidchart OAuth2 application.
2. Deploy the document sync service to reconcile local snapshots with Lucidchart state.
3. Start the collaboration event consumer to capture shape deltas in real time.
4. Configure the export worker pool with deduplication via Redis SETNX.
5. Tune the sync interval and version retention policy for your document volume.

Prerequisites

• Node.js 18+, TypeScript 5, PostgreSQL 15, Redis 7, RabbitMQ or SQS
• Lucidchart OAuth2 credentials with document:read, document:write, export scopes

Architecture Diagram

Client --> API Gateway --> DocumentSyncService --> Lucidchart API
                                  |
                   +--------------+--------------+
                   v              v              v
             Version DB    Collab Event     Export Worker
            (snapshots)     Consumer       (PNG/SVG/PDF)

Service Layer

class DocumentSyncService {
  constructor(
    private api: LucidchartApiClient,
    private versions: VersionStore,
    private events: EventPublisher
  ) {}

  async syncDocument(docId: string): Promise<DocumentSnapshot> {
    const remote = await this.api.getDocument(docId);
    const local = await this.versions.getLatest(docId);
    if (!local || remote.revision > local.revision) {
      const snapshot = await this.versions.save(docId, remote);
      await this.events.publish('document.synced', { docId, revision: remote.revision });
      return snapshot;
    }
    return local;
  }

  async exportDiagram(docId: string, format: ExportFormat): Promise<string> {
    await this.events.publish('export.requested', { docId, format });
    return this.api.requestExport(docId, format);
  }
}

Caching Strategy

class DocumentCache {
  constructor(private redis: RedisClient) {}

  async getMetadata(docId: string): Promise<DocumentMeta | null> {
    const raw = await this.redis.get(`doc:meta:${docId}`);
    return raw ? JSON.parse(raw) : null;
  }

  async setMetadata(docId: string, meta: DocumentMeta): Promise<void> {
    await this.redis.setEx(`doc:meta:${docId}`, 120, JSON.stringify(meta));
  }

  async deduplicateExport(docId: string, format: string): Promise<boolean> {
    const key = `export:lock:${docId}:${format}`;
    return (await this.redis.setNX(key, '1')) =

Lucidchart SDK Patterns

Overview

Lucid's REST API uses OAuth 2.0 with versioned Lucid-Api-Version headers to manage documents, pages, shapes, data-linked fields, and collaborative comments. A structured SDK client is essential because the API requires version negotiation on every request, returns deeply nested shape tree hierarchies, and enforces document-level locking for concurrent edits. These patterns provide OAuth token lifecycle management, typed shape and document models, fluent query building for filtered shape searches, and mock factories for diagramming test scenarios.

Prerequisites

• Node.js 18+, TypeScript 5+
• LUCIDCLIENTID and LUCIDCLIENTSECRET environment variables (OAuth 2.0 app credentials)
• LUCIDACCESSTOKEN or refresh token flow for per-user access
• axios or node-fetch for HTTP transport

Singleton Client

interface LucidConfig {
  clientId: string;
  clientSecret: string;
  accessToken: string;
  apiVersion?: string;
  baseUrl?: string;
}

let client: LucidClient | null = null;

export function getLucidClient(overrides?: Partial<LucidConfig>): LucidClient {
  if (!client) {
    const config: LucidConfig = {
      clientId: process.env.LUCID_CLIENT_ID ?? '',
      clientSecret: process.env.LUCID_CLIENT_SECRET ?? '',
      accessToken: process.env.LUCID_ACCESS_TOKEN ?? '',
      apiVersion: '2',
      baseUrl: 'https://api.lucid.co',
      ...overrides,
    };
    if (!config.accessToken) throw new Error('LUCID_ACCESS_TOKEN is required');
    client = new LucidClient(config);
  }
  return client;
}

Error Wrapper

interface LucidApiError { status: number; errorCode: string; message: string; documentId?: string; }

async function safeLucid<T>(fn: () => Promise<T>): Promise<T> {
  try { return await fn(); }
  catch (err: any) {
    const parsed: LucidApiError = {
      status: err.response?.status ?? 500,
      errorCode: err.response?.data?.errorCode ?? 'INTERNAL',
      message: err.response?.data?.message ?? err.message,
      documentId: err.response?.data?.documentId,
    };
    if (parsed.status === 429) {
      const wait = parseInt(err.response?.headers?.['x-ratelimit-reset'] ?? '10', 10);
      await new Promise(r => setTimeout(r, wait * 1000));
      return fn();
    }
    if (parsed.errorCode === 'DOCUMENT_LOCKED') throw new Error(`Document ${parsed.documentId} is locked by another editor`);
    if (parsed.status === 403) throw new Error(`Insufficient permissions: ${parsed.message}`);
    throw new Error(`Lucid ${parsed.errorCode} (${parsed.status}): ${parsed.message}`);
  }
}

Request Builder

                

                  
                    
                  
                  
                  lucidchart-security-basics
                  SKILL.md
                  View full skill →
                
                

                  
Security Basics for Lucidchart.
                  

                      ReadWriteEdit
                    
                
                

                  
Lucidchart Security Basics
Overview
Lucidchart documents often contain sensitive business diagrams — org charts, network topologies, database schemas, and architecture plans that reveal internal infrastructure. The API uses OAuth2 client credentials, meaning a compromised client secret grants access to every document the integration can reach. Collaboration sharing with granular permission levels (view, edit, owner) must be enforced server-side. API versioning via the Lucid-Api-Version header requires pinning to avoid unexpected schema changes that break validation logic.
Prerequisites

OAuth2 client ID and secret stored in a secrets manager (not environment files)
HTTPS enforced on all redirect URIs and webhook endpoints
Lucid-Api-Version header pinned to a tested version in all requests
.env files in .gitignore — never committed to version control

API Key Management

// OAuth2 client credentials — load from secrets manager at startup
const LUCID_CLIENT_ID = process.env.LUCID_CLIENT_ID;
const LUCID_CLIENT_SECRET = process.env.LUCID_CLIENT_SECRET;

function validateLucidConfig(): void {
  if (!LUCID_CLIENT_ID || !LUCID_CLIENT_SECRET) {
    throw new Error('Missing LUCID_CLIENT_ID or LUCID_CLIENT_SECRET');
  }
}

async function getLucidAccessToken(): Promise<string> {
  const resp = await fetch('https://api.lucid.co/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: LUCID_CLIENT_ID!,
      client_secret: LUCID_CLIENT_SECRET!,
    }),
  });
  if (!resp.ok) throw new Error(`OAuth2 token request failed: ${resp.status}`);
  const { access_token } = await resp.json();
  return access_token;
  // Cache token until expiry — never log it
}

Webhook Signature Verification

import crypto from 'node:crypto';

const LUCID_WEBHOOK_SECRET = process.env.LUCID_WEBHOOK_SECRET!;

function verifyLucidWebhook(payload: string, signature: string): boolean {
  const expected = crypto
    .createHmac('sha256', LUCID_WEBHOOK_SECRET)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post('/webhooks/lucidchart', (req, res) => {
  const sig = req.headers['x-lucid-signature'] as string;
  if (!sig || !verifyLucidWebhook(JSON.stringify(req.body), sig)) {
    return res.status(401).json({ error: 'Invalid webhook signature' });
  }
  // Process verified document change event
});

Input Validation

// Validate document IDs and enforce API version pinning
const