API e MCP

L’API REST e il server MCP di LetDraw permettono a strumenti esterni e client AI (Claude, Cursor) di lavorare con i tuoi diagrammi: elencare, leggere, creare, aggiornare, generare un diagramma dal codice, riconvertire in codice, condividere e generare da un prompt.

Chi può usarli

L’API e MCP sono disponibili per gli utenti Pro ed Enterprise. Nelle installazioni self-hosted, ogni membro che ha effettuato l’accesso può usarli. Gli utenti Free e ospiti non possono creare token.

1. Creare un token

1. Accedi a LetDraw con un account Pro/Enterprise.
2. Vai su Settings -> Developer.
3. Crea un token: dagli un nome, scegli gli scope (vedi sotto) e, facoltativamente, limitalo a un singolo workspace.
4. Il token ld_live_... generato viene mostrato una sola volta. Salvalo in un posto sicuro. Se viene divulgato, revocalo dalla stessa pagina.

Scope

Scope	Autorizzazione
diagrams:read	Leggere workspace, cartelle e diagrammi
diagrams:write	Creare, aggiornare, eliminare e condividere diagrammi
export	Esportare un diagramma in codice Mermaid/D2
ai:generate	Generare un diagramma da un prompt (AI)

2. Autenticazione

Invia il token come valore Bearer nell’intestazione Authorization in ogni richiesta:

Authorization: Bearer ld_live_...

Non è necessaria alcuna intestazione apikey aggiuntiva.

API REST

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

Tutte le risposte sono in JSON. Gli errori vengono restituiti con un corpo standard: { "error": { "code", "message" } }.

Metodo	Percorso	Descrizione	Scope
GET	/	Info API (scope, endpoint)	any
GET	/workspaces	I tuoi workspace (con ruolo)	read
GET	/folders?workspace=<id>	Cartelle in un workspace	read
GET	/documents?workspace=<id>	Diagrammi in un workspace (paginati)	read
GET	/documents?folder=<id>	Diagrammi in una cartella (paginati)	read
POST	/documents	Creare un diagramma	write
GET	/documents/:id	Diagramma + scena (elementi)	read
PATCH	/documents/:id	Aggiornare nome e/o elementi	write
DELETE	/documents/:id	Eliminare un diagramma	write
POST	/documents/from-code	Generare un diagramma dal codice	write
POST	/documents/generate	Generare un diagramma da un prompt (AI)	ai:generate
GET	/documents/:id/export?format=mermaid|d2	Esportare un diagramma in codice	export
POST	/documents/:id/share	Creare un collegamento pubblico di sola lettura	write
DELETE	/documents/:id/share	Rimuovere il collegamento pubblico	write

Paginazione

Gli endpoint di elenco accettano ?limit= (1-100, predefinito 50) e ?cursor=. La risposta restituisce un nextCursor; passalo come cursor per ottenere la pagina successiva.

Limite di frequenza

120 richieste al minuto per token. Superarlo restituisce 429 rate_limited.

Esempi

# 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"

Server MCP

I client Model Context Protocol (MCP) (Claude, Cursor) possono connettersi a LetDraw e lavorare con i tuoi diagrammi tramite strumenti.

• URL: https://api.letdraw.com/mcp
• Trasporto: Streamable HTTP (JSON-RPC 2.0 senza stato)
• Auth: Authorization: Bearer ld_live_...

Strumenti

Strumento	Descrizione
list_workspaces	Workspace accessibili
list_diagrams	Diagrammi in un workspace/cartella
get_diagram	Diagramma + scena
create_diagram	Creare un diagramma da un array di elementi (formato LetDraw o Excalidraw, rilevato automaticamente)
update_diagram	Aggiornare nome/elementi
delete_diagram	Eliminare un diagramma
diagram_from_code	compose, kubernetes, dot, plantuml, terraform, helm, sql -> diagramma
export_to_code	Diagramma -> Mermaid/D2
share_diagram	Creare un collegamento pubblico
unshare_diagram	Rimuovere il collegamento pubblico
generate_from_prompt	Diagramma da linguaggio naturale (AI)

Nota

generate_from_prompt richiede una chiave OpenAI o OpenRouter memorizzata sul server sul tuo account (Settings -> API Keys). Senza una chiave restituisce no_ai_key.

Configurazione del client

Puoi copiare blocchi di configurazione pronti con il tuo token dalla pagina Settings -> Developer. Sostituisci ld_live_... qui sotto con il tuo token.

Cursor

~/.cursor/mcp.json (globale) oppure .cursor/mcp.json nella radice del progetto:

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

Claude Desktop

Claude Desktop si connette al server HTTP remoto tramite il bridge mcp-remote (Node.js richiesto). File di configurazione:

• 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_..."
      ]
    }
  }
}

Riavvia il client dopo il salvataggio. Prompt di esempio:

• “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: …” (composizione a forma libera)

Dire all’AI di “disegnarlo in LetDraw”

create_diagram e update_diagram accettano l’array di elementi in due formati: lo schema di elementi proprio di LetDraw oppure il formato Excalidraw. Il formato viene rilevato automaticamente e gli elementi Excalidraw vengono convertiti in elementi LetDraw lato server (compresi contenitori annidati colorati, etichette collegate alle forme, frecce con binding, testo e frame).

Cosa significa questo: quando dici a ChatGPT, Gemini o Claude di “disegnare questa architettura in LetDraw”, il modello produce il JSON Excalidraw che già conosce molto bene dai suoi dati di addestramento e lo invia tramite MCP; LetDraw disegna l’esatto equivalente. Qualunque sia la qualità di layout del modello, è ciò che ottieni in LetDraw.

Nota

Excalidraw è un marchio del team Excalidraw; LetDraw offre solo compatibilità con il formato dei file e non ha alcuna affiliazione con Excalidraw.

Incorporare un diagramma (render.svg)

Puoi incorporare come SVG un diagramma condiviso pubblicamente in luoghi come un README o Notion. Ottieni prima un token di condivisione con share_diagram (o REST .../share), quindi:

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

Questo endpoint restituisce image/svg+xml e non richiede alcun token API (vengono resi solo i diagrammi condivisi), quindi puoi usarlo direttamente dentro <img src="...">.