API ve MCP

LetDraw’ın REST API’si ve MCP sunucusu, dış araçların ve yapay zeka istemcilerinin (Claude, Cursor) senin diyagramlarınla çalışmasını sağlar: listele, oku, oluştur, güncelle, koddan diyagram üret, koda geri çevir, paylaş ve prompt’tan üret.

Kimler kullanabilir

API ve MCP Pro ve Enterprise kullanıcılarına açıktır. Kendinde barındırılan (self-hosted) kurulumlarda giriş yapan her üye kullanabilir. Ücretsiz ve misafir kullanıcılar token oluşturamaz.

1. Token oluştur

1. LetDraw’a Pro/Enterprise bir hesapla giriş yap.
2. Ayarlar → Geliştirici’ye git.
3. Token oluştur: bir ad ver, kapsamları seç (aşağıya bak) ve istersen tek bir çalışma alanına sınırla.
4. Oluşturulan ld_live_... token’ı yalnızca bir kez gösterilir. Güvenli bir yere kaydet. Sızarsa aynı sayfadan iptal et.

Kapsamlar

Kapsam	İzin
diagrams:read	Çalışma alanı, klasör ve diyagramları okuma
diagrams:write	Diyagram oluşturma, güncelleme, silme, paylaşma
export	Diyagramı Mermaid/D2 koduna dışa aktarma
ai:generate	Prompt’tan diyagram üretme (AI)

2. Kimlik doğrulama

Token’ı her isteğe Authorization başlığında Bearer olarak gönder:

Authorization: Bearer ld_live_...

Ek bir apikey başlığı gerekmez.

REST API

Taban adres: https://api.letdraw.com/api-v1

Tüm yanıtlar JSON’dur. Hatalar standart gövdeyle döner: { "error": { "code", "message" } }.

Metot	Yol	Açıklama	Kapsam
GET	/	API bilgisi (kapsamlar, uçlar)	herhangi
GET	/workspaces	Çalışma alanların (rol dahil)	read
GET	/folders?workspace=<id>	Bir çalışma alanının klasörleri	read
GET	/documents?workspace=<id>	Çalışma alanındaki diyagramlar (sayfalı)	read
GET	/documents?folder=<id>	Klasördeki diyagramlar (sayfalı)	read
POST	/documents	Diyagram oluştur	write
GET	/documents/:id	Diyagram + sahne (elements)	read
PATCH	/documents/:id	Ad ve/veya elements güncelle	write
DELETE	/documents/:id	Diyagram sil	write
POST	/documents/from-code	Koddan diyagram üret	write
POST	/documents/generate	Prompt’tan diyagram üret (AI)	ai:generate
GET	/documents/:id/export?format=mermaid|d2	Diyagramı koda dışa aktar	export
POST	/documents/:id/share	Public salt-okunur link oluştur	write
DELETE	/documents/:id/share	Public linki kaldır	write

Sayfalama

Liste uçları ?limit= (1-100, varsayılan 50) ve ?cursor= alır. Yanıt bir nextCursor döndürür; sonraki sayfa için onu cursor olarak gönder.

Hız limiti

Token başına dakikada 120 istek. Aşılırsa 429 rate_limited döner.

Örnekler

# Çalışma alanlarını listele
curl -H "Authorization: Bearer ld_live_..." \
  https://api.letdraw.com/api-v1/workspaces

# Bir docker-compose'dan diyagram üret
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

# Diyagramı Mermaid'e dışa aktar
curl -H "Authorization: Bearer ld_live_..." \
  "https://api.letdraw.com/api-v1/documents/<id>/export?format=mermaid"

MCP sunucusu

Model Context Protocol (MCP) istemcileri (Claude, Cursor) LetDraw’a bağlanıp diyagramlarınla araçlar üzerinden çalışabilir.

• URL: https://api.letdraw.com/mcp
• Taşıma: Streamable HTTP (durumsuz JSON-RPC 2.0)
• Kimlik doğrulama: Authorization: Bearer ld_live_...

Araçlar

Araç	Açıklama
list_workspaces	Erişilebilir çalışma alanları
list_diagrams	Bir çalışma alanı/klasördeki diyagramlar
get_diagram	Diyagram + sahne
create_diagram	Elements dizisiyle diyagram oluştur (LetDraw veya Excalidraw formatı, otomatik algılanır)
update_diagram	Ad/elements güncelle
delete_diagram	Diyagram sil
diagram_from_code	compose, kubernetes, dot, plantuml, terraform, helm, sql → diyagram
export_to_code	Diyagram → Mermaid/D2
share_diagram	Public link oluştur
unshare_diagram	Public linki kaldır
generate_from_prompt	Doğal dilden diyagram (AI)

Not

generate_from_prompt için hesabında sunucu-depolamalı bir OpenAI ya da OpenRouter anahtarı olmalı (Ayarlar → API Anahtarları). Anahtar yoksa no_ai_key döner.

İstemci kurulumu

Config bloklarını Ayarlar → Geliştirici sayfasında kendi token’ınla hazır kopyalayabilirsin. Aşağıdaki ld_live_... yerine kendi token’ını yaz.

Cursor

~/.cursor/mcp.json (global) veya proje kökünde .cursor/mcp.json:

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

Claude Desktop

Claude Desktop uzak HTTP sunucusuna mcp-remote köprüsüyle bağlanır (Node.js gerekir). Config dosyası:

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

Kaydettikten sonra istemciyi yeniden başlat. Örnek istemler:

• “LetDraw çalışma alanlarımı listele.”
• “Şu docker-compose’u LetDraw’da diyagrama çevir: …”
• “Diyagram ‘yi Mermaid olarak ver.”
• “Bir OAuth login akışı diyagramı üret.”
• “Şu cloud mimarisini LetDraw’da çiz: …” (serbest kompozisyon)

AI’ya “LetDraw’da çiz” demek

create_diagram ve update_diagram, elements dizisini iki formatta kabul eder: LetDraw’ın kendi eleman şeması veya Excalidraw formatı. Format otomatik algılanır ve Excalidraw elemanları sunucu tarafında LetDraw elemanlarına çevrilir (renkli iç içe konteynerler, şekle bağlı etiketler, binding’li oklar, metinler, frame’ler dahil).

Bunun anlamı: ChatGPT, Gemini veya Claude’a “bu mimariyi LetDraw’da çiz” dediğinde model, eğitim verisinden zaten çok iyi bildiği Excalidraw JSON’unu üretir ve MCP üzerinden gönderir; LetDraw tarafında birebir karşılığı çizilir. Modelin yerleşim kalitesi neyse LetDraw’daki sonuç da odur.

Not

Excalidraw, Excalidraw ekibinin markasıdır; LetDraw yalnızca dosya formatı uyumluluğu sunar, Excalidraw ile bir bağı yoktur.

Diyagramı gömme (render.svg)

Public paylaşılan bir diyagramı README/Notion gibi yerlere SVG olarak gömebilirsin. Önce share_diagram (veya REST .../share) ile bir paylaşım token’ı al, sonra:

https://api.letdraw.com/render-svg?token=<paylaşım-token'ı>

Bu uç image/svg+xml döndürür ve API token’ı gerektirmez (yalnızca paylaşılan diyagramlar render edilir), böylece doğrudan <img src="..."> içinde kullanılır.