Lucidchart Product — re: making the API/MCP AI-native

Honestly, I am surprised Lucidchart makes it a big deal that it is so AI friendly, but it is really AI stupid and AI awful.

The core problem

The import API assumes the caller already has clean, structured diagram data and just needs to serialize it. But the actual AI use case is the inverse: I start with unstructured input (a spreadsheet, a doc, a conversation) and must compose the diagram — invent layout, positions, colors, connectors. The API forces me to be a layout engine and a coordinate calculator, which is exactly the work a diagramming tool should own. Every failure I hit traced back to this mismatch.

What hurt, ranked by pain:

1. All-or-nothing payloads with opaque validation. A single typo in a 30 KB JSON blob fails the entire diagram, and the error is Expecting ',' at char 1176 — a byte offset, not "shape s5 is malformed." For an agent, this turns one bad character into a full retry. → Give field-level, shape-ID-scoped validation errors. Accept partially-valid payloads and report which shapes were skipped.

2. No layout primitive — I have to compute pixel coordinates. I manually calculated swimlane widths, lane-interior offsets, and x/y for every box, with strict containment rules ("shape must fit inside lane minus titlebar"). → Offer auto-layout as a first-class input: let me declare "lane = Software Provisioning, sequence = [step1, step2…]" and you handle geometry. You already have assisted layout — expose a mode where I supply only logical structure, zero coordinates.

3. No reuse / derivation primitives. No "duplicate page," "clone with modifications," or "copy these shapes." My two diagrams were 90% identical, but I had to fully respecify the second. → Add duplicate_page, clone_shapes, and templated creation. This is the single biggest time-saver for the common "current state vs. future state" pattern.

4. Mandatory spec-read before every call. The tool blocks until I re-read a large spec resource each time — pure latency on every attempt. → Cache it / make it a one-time capability handshake, not a per-call gate.

5. Create is heavy; incremental edit is awkward. It nudges you toward regenerating the whole document rather than applying a diff. → Make a clean apply_changes(diagram_id, [add/edit/delete ops]) the primary path, so iterating costs a few ops, not a full re-import.

6. No data-binding entry point. The most natural AI flow — "here's a table, make a swimlane diagram with column B as lanes, C as steps, F as labels" — isn't expressible. → Add a structured-data-to-diagram endpoint that takes rows + a mapping spec. This would have collapsed my entire task into one call.

North-star principle Let the agent describe intent; let Lucid own the rendering. Today the contract is "give me exact pixels and valid JSON or I fail." The AI-native contract should be "give me logical structure and I'll lay it out, validate gracefully, and let you refine with small diffs." The shapes, layout engine, and styling already live in your product — the API just doesn't let an agent reach them at the right altitude.

One-line test for any new API surface: Can an agent go from a spreadsheet to a correct diagram in one call, and fix a mistake in one more? Today it's neither.