Upgrade Migration for Lucidchart. Trigger: "lucidchart upgrade migration".
Lucidchart (Lucid) provides a diagramming and visual collaboration platform with APIs for document management, shape manipulation, and data linking. The API uses version headers and evolves its document schema, shape library definitions, and permission models. Tracking API versions is critical because Lucid's document format changes affect embedded diagram exports, shape coordinate systems shift between API versions, and breaking changes to the data linking API can corrupt live-data diagrams connected to external databases.
const LUCID_BASE = "https://api.lucid.co/v1";
async function detectLucidApiVersion(apiKey: string): Promise<void> {
const res = await fetch(`${LUCID_BASE}/documents`, {
headers: {
Authorization: `Bearer ${apiKey}`,
"Lucid-Api-Version": "2",
"Content-Type": "application/json",
},
});
const serverVersion = res.headers.get("x-lucid-api-version") ?? "unknown";
const minSupported = res.headers.get("x-lucid-min-version");
console.log(`Lucid API version: ${serverVersion}, min supported: ${minSupported}`);
// Check if current version header is being accepted or forced up
const requestedVersion = "2";
if (serverVersion !== requestedVersion) {
console.warn(`Requested v${requestedVersion} but server responded with v${serverVersion}`);
}
const deprecation = res.headers.get("x-lucid-deprecation-notice");
if (deprecation) console.warn(`Deprecation: ${deprecation}`);
}
Lucid-Api-Version header in all API calls to target version// Lucid document schema: flat shape list → page-grouped shape hierarchy
interface OldDocument {
id: string;
title: string;
shapes: Array<{ id: string; type: string; x: number; y: number; width: number; height: number; text?: string }>;
lastModified: string;
}
interface NewDocument {
id: string;
title: string;
pages: Array<{
id: string;
title: string;
layers: Array<{
id: string;
shapes: Array<{
id: string;
type: string;
bounds: { x: number; y: number; width: number; height: number };
text?: { content: string; style: Record<string, any> };
}>;
}>;
}>;
lastModified: string;
version: number;
}
function migrateDocument(old: OldDocument): NewDocument {
return {
id: old.id,
title: old.title,
pages: [{
id: "page-1",
title: "Page 1",
layers: [{
id: "layer-1",
shapes: old.shapes.map((s) => ({
id: s.id,
type: s.type,
bounds: { x: s.x, y: s.y, width: s.width, height: s.height },
text: s.text ? { content: s.text, style: {} } : undefined,
})),
}],
}],
lastModified: old.lastModified,
version: 2,
};
}
class LucidClient {
private apiVersion: number;
constructor(private apiKey: string, version: number = 2) {
this.apiVersion = version;
}
async getDocument(docId: string): Promise<any> {
try {
const res = await fetch(`https://api.lucid.co/v1/documents/${docId}`, {
headers: {
Authorization: `Bearer ${this.apiKey}`,
"Lucid-Api-Version": String(this.apiVersion),
},
});
if (!res.ok) throw new Error(`Lucid API ${res.status}`);
return await res.json();
} catch (err) {
if (this.apiVersion > 1) {
console.warn(`Falling back Lucid API from v${this.apiVersion} to v${this.apiVersion - 1}`);
this.apiVersion -= 1;
return this.getDocument(docId);
}
throw err;
}
}
}
| Migration Issue | Symptom | Fix |
|---|---|---|
| API version header missing | 400 with Lucid-Api-Version header required | Add Lucid-Api-Version header to all requests |
| Shape ID format changed | 404 when referencing shapes by old numeric ID | Migrate to new UUID-based shape identifiers |
| Document export dimensions wrong | SVG exports render at unexpected scale | Check if coordinate units changed from points to pixels in new version |
| Data link schema invalid | 422 on data linking update | Re-map external data columns to new document field schema |
| Permission model expanded | 403 on previously accessible documents | Request updated OAuth scopes for new permission levels |
For CI pipeline integration, see lucidchart-ci-integration.