API en MCP

De REST API en MCP-server van LetDraw stellen externe tools en AI-clients (Claude, Cursor) in staat om met je diagrammen te werken: opsommen, lezen, aanmaken, bijwerken, een diagram uit code genereren, terug naar code converteren, delen en genereren op basis van een prompt.

Wie kan het gebruiken

De API en MCP zijn beschikbaar voor Pro- en Enterprise-gebruikers. Bij self-hosted installaties kan elk ingelogd lid ze gebruiken. Gratis en gastgebruikers kunnen geen tokens aanmaken.

1. Een token aanmaken

Log in bij LetDraw met een Pro/Enterprise-account.
Ga naar Settings -> Developer.
Maak een token aan: geef het een naam, kies de scopes (zie hieronder), en beperk het eventueel tot één workspace.
De gegenereerde ld_live_... token wordt slechts één keer getoond. Bewaar hem op een veilige plek. Als hij lekt, trek hem dan in via dezelfde pagina.

Scopes

Scope	Rechten
`diagrams:read`	Workspaces, mappen en diagrammen lezen
`diagrams:write`	Diagrammen aanmaken, bijwerken, verwijderen en delen
`export`	Een diagram naar Mermaid/D2-code exporteren
`ai:generate`	Een diagram genereren op basis van een prompt (AI)

2. Authenticatie

Stuur de token als Bearer-waarde in de Authorization-header bij elk verzoek:

Authorization: Bearer ld_live_...

Er is geen extra apikey-header nodig.

REST API

Basis-URL: https://api.letdraw.com/api-v1

Alle responses zijn JSON. Fouten worden geretourneerd met een standaardbody: { "error": { "code", "message" } }.

Methode	Pad	Beschrijving	Scope
GET	`/`	API-info (scopes, endpoints)	any
GET	`/workspaces`	Je workspaces (met rol)	read
GET	`/folders?workspace=<id>`	Mappen in een workspace	read
GET	`/documents?workspace=<id>`	Diagrammen in een workspace (gepagineerd)	read
GET	`/documents?folder=<id>`	Diagrammen in een map (gepagineerd)	read
POST	`/documents`	Een diagram aanmaken	write
GET	`/documents/:id`	Diagram + scene (elementen)	read
PATCH	`/documents/:id`	Naam en/of elementen bijwerken	write
DELETE	`/documents/:id`	Een diagram verwijderen	write
POST	`/documents/from-code`	Een diagram uit code genereren	write
POST	`/documents/generate`	Een diagram genereren op basis van een prompt (AI)	ai:generate
GET	`/documents/:id/export?format=mermaid\|d2`	Een diagram naar code exporteren	export
POST	`/documents/:id/share`	Een publieke alleen-lezen link aanmaken	write
DELETE	`/documents/:id/share`	De publieke link verwijderen	write

Paginering

List-endpoints accepteren ?limit= (1-100, standaard 50) en ?cursor=. De response retourneert een nextCursor; geef die door als cursor om de volgende pagina op te halen.

Snelheidslimiet

120 verzoeken per minuut per token. Overschrijding retourneert 429 rate_limited.

Voorbeelden

# List workspaces
curl -H "Authorization: Bearer ld_live_..." \
  https://api.letdraw.com/api-v1/workspaces

# Generate a diagram from a docker-compose
curl -X POST -H "Authorization: Bearer ld_live_..." -H "Content-Type: application/json" \
  -d '{"workspaceId":"<id>","code":"services:\n  web:\n    image: nginx\n    depends_on: [db]\n  db:\n    image: postgres\n"}' \
  https://api.letdraw.com/api-v1/documents/from-code

# Export a diagram to Mermaid
curl -H "Authorization: Bearer ld_live_..." \
  "https://api.letdraw.com/api-v1/documents/<id>/export?format=mermaid"

MCP-server

Model Context Protocol (MCP)-clients (Claude, Cursor) kunnen verbinding maken met LetDraw en via tools met je diagrammen werken.

URL: https://api.letdraw.com/mcp
Transport: Streamable HTTP (stateless JSON-RPC 2.0)
Auth: Authorization: Bearer ld_live_...

Tools

Tool	Beschrijving
`list_workspaces`	Toegankelijke workspaces
`list_diagrams`	Diagrammen in een workspace/map
`get_diagram`	Diagram + scene
`create_diagram`	Een diagram aanmaken uit een elementen-array (letdraw- of Excalidraw-formaat, automatisch gedetecteerd)
`update_diagram`	Naam/elementen bijwerken
`delete_diagram`	Een diagram verwijderen
`diagram_from_code`	compose, kubernetes, dot, plantuml, terraform, helm, sql -> diagram
`export_to_code`	Diagram -> Mermaid/D2
`share_diagram`	Een publieke link aanmaken
`unshare_diagram`	De publieke link verwijderen
`generate_from_prompt`	Diagram uit natuurlijke taal (AI)

Client-installatie

Je kunt kant-en-klare configuratieblokken met je eigen token kopiëren vanaf de Settings -> Developer-pagina. Vervang ld_live_... hieronder door je eigen token.

Cursor

~/.cursor/mcp.json (globaal) of .cursor/mcp.json in de projectroot:

{
  "mcpServers": {
    "letdraw": {
      "url": "https://api.letdraw.com/mcp",
      "headers": { "Authorization": "Bearer ld_live_..." }
    }
  }
}

Claude Desktop

Claude Desktop maakt verbinding met de externe HTTP-server via de mcp-remote-bridge (Node.js vereist). Configuratiebestand:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "letdraw": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.letdraw.com/mcp",
        "--header", "Authorization:Bearer ld_live_..."
      ]
    }
  }
}

Herstart de client na het opslaan. Voorbeeldprompts:

“List my LetDraw workspaces.”
“Turn this docker-compose into a diagram in letdraw: …”
“Export diagram as Mermaid.”
“Generate an OAuth login flow diagram.”
“Draw this cloud architecture in letdraw: …” (vrije compositie)

De AI vertellen om het “in LetDraw te tekenen”

create_diagram en update_diagram accepteren de elementen-array in twee formaten: het eigen elementschema van LetDraw of het Excalidraw-formaat. Het formaat wordt automatisch gedetecteerd, en Excalidraw-elementen worden aan de serverkant omgezet naar letdraw-elementen (inclusief gekleurde geneste containers, aan vormen gebonden labels, pijlen met bindingen, tekst en frames).

Wat dit betekent: wanneer je ChatGPT, Gemini of Claude vraagt om “deze architectuur in LetDraw te tekenen”, produceert het model de Excalidraw-JSON die het al zeer goed kent uit zijn trainingsdata en stuurt het over MCP; LetDraw tekent het exacte equivalent. Wat de kwaliteit van de lay-out van het model ook is, dat is wat je in LetDraw krijgt.

Een diagram insluiten (render.svg)

Je kunt een publiek gedeeld diagram als SVG insluiten op plekken zoals een README of Notion. Haal eerst een share-token op met share_diagram (of REST .../share), en vervolgens:

https://api.letdraw.com/render-svg?token=<share-token>

Dit endpoint retourneert image/svg+xml en vereist geen API-token (alleen gedeelde diagrammen worden gerenderd), dus je kunt het direct binnen <img src="..."> gebruiken.