API i MCP

REST API i serwer MCP LetDraw pozwalają zewnętrznym narzędziom i klientom AI (Claude, Cursor) pracować z Twoimi diagramami: wypisywać, odczytywać, tworzyć, aktualizować, generować diagram z kodu, konwertować z powrotem na kod, udostępniać i generować z podpowiedzi.

Kto może z tego korzystać

API i MCP są dostępne dla użytkowników Pro i Enterprise. W instalacjach samodzielnie hostowanych może z nich korzystać każdy zalogowany członek. Użytkownicy darmowi i goście nie mogą tworzyć tokenów.

1. Utwórz token

1. Zaloguj się do LetDraw kontem Pro/Enterprise.
2. Przejdź do Settings -> Developer.
3. Utwórz token: nadaj mu nazwę, wybierz zakresy (patrz niżej) i opcjonalnie ogranicz go do pojedynczej przestrzeni roboczej.
4. Wygenerowany token ld_live_... jest wyświetlany tylko raz. Zapisz go w bezpiecznym miejscu. Jeśli wycieknie, cofnij go z tej samej strony.

Zakresy

Zakres	Uprawnienie
diagrams:read	Odczyt przestrzeni roboczych, folderów i diagramów
diagrams:write	Tworzenie, aktualizacja, usuwanie i udostępnianie diagramów
export	Eksport diagramu do kodu Mermaid/D2
ai:generate	Generowanie diagramu z podpowiedzi (AI)

2. Uwierzytelnianie

Wysyłaj token jako wartość Bearer w nagłówku Authorization przy każdym żądaniu:

Authorization: Bearer ld_live_...

Dodatkowy nagłówek apikey nie jest potrzebny.

REST API

Bazowy adres URL: https://api.letdraw.com/api-v1

Wszystkie odpowiedzi są w formacie JSON. Błędy zwracane są ze standardowym ciałem: { "error": { "code", "message" } }.

Metoda	Ścieżka	Opis	Zakres
GET	/	Informacje o API (zakresy, punkty końcowe)	dowolny
GET	/workspaces	Twoje przestrzenie robocze (z rolą)	read
GET	/folders?workspace=<id>	Foldery w przestrzeni roboczej	read
GET	/documents?workspace=<id>	Diagramy w przestrzeni roboczej (podzielone na strony)	read
GET	/documents?folder=<id>	Diagramy w folderze (podzielone na strony)	read
POST	/documents	Utwórz diagram	write
GET	/documents/:id	Diagram + scena (elementy)	read
PATCH	/documents/:id	Aktualizuj nazwę i/lub elementy	write
DELETE	/documents/:id	Usuń diagram	write
POST	/documents/from-code	Wygeneruj diagram z kodu	write
POST	/documents/generate	Wygeneruj diagram z podpowiedzi (AI)	ai:generate
GET	/documents/:id/export?format=mermaid|d2	Eksportuj diagram do kodu	export
POST	/documents/:id/share	Utwórz publiczny odnośnik tylko do odczytu	write
DELETE	/documents/:id/share	Usuń publiczny odnośnik	write

Podział na strony

Punkty końcowe list przyjmują ?limit= (1-100, domyślnie 50) i ?cursor=. Odpowiedź zwraca nextCursor; przekaż go jako cursor, aby uzyskać następną stronę.

Limit szybkości

120 żądań na minutę na token. Przekroczenie zwraca 429 rate_limited.

Przykłady

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

Serwer MCP

Klienci Model Context Protocol (MCP) (Claude, Cursor) mogą połączyć się z LetDraw i pracować z Twoimi diagramami za pomocą narzędzi.

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

Narzędzia

Narzędzie	Opis
list_workspaces	Dostępne przestrzenie robocze
list_diagrams	Diagramy w przestrzeni roboczej/folderze
get_diagram	Diagram + scena
create_diagram	Utwórz diagram z tablicy elementów (format LetDraw lub Excalidraw, automatycznie wykrywany)
update_diagram	Aktualizuj nazwę/elementy
delete_diagram	Usuń diagram
diagram_from_code	compose, kubernetes, dot, plantuml, terraform, helm, sql -> diagram
export_to_code	Diagram -> Mermaid/D2
share_diagram	Utwórz publiczny odnośnik
unshare_diagram	Usuń publiczny odnośnik
generate_from_prompt	Diagram z języka naturalnego (AI)

Notatka

generate_from_prompt wymaga przechowywanego na serwerze klucza OpenAI lub OpenRouter na Twoim koncie (Settings -> API Keys). Bez klucza zwraca no_ai_key.

Konfiguracja klienta

Gotowe bloki konfiguracji z własnym tokenem możesz skopiować ze strony Settings -> Developer. Zastąp ld_live_... poniżej własnym tokenem.

Cursor

~/.cursor/mcp.json (globalnie) lub .cursor/mcp.json w katalogu głównym projektu:

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

Claude Desktop

Claude Desktop łączy się ze zdalnym serwerem HTTP przez most mcp-remote (wymagany Node.js). Plik konfiguracji:

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

Uruchom klienta ponownie po zapisaniu. Przykładowe podpowiedzi:

• “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: …” (kompozycja w dowolnej formie)

Polecenie AI, aby “narysowało to w LetDraw”

create_diagram i update_diagram przyjmują tablicę elementów w dwóch formatach: własnym schemacie elementów LetDraw lub formacie Excalidraw. Format jest automatycznie wykrywany, a elementy Excalidraw są konwertowane na elementy LetDraw po stronie serwera (w tym kolorowe zagnieżdżone kontenery, etykiety powiązane z kształtami, strzałki z powiązaniami, tekst i ramki).

Co to oznacza: gdy każesz ChatGPT, Gemini lub Claude “narysuj tę architekturę w LetDraw”, model tworzy Excalidraw JSON, który już bardzo dobrze zna ze swoich danych treningowych, i wysyła go przez MCP; LetDraw rysuje dokładny odpowiednik. Jakakolwiek jest jakość układu modelu, taką otrzymujesz w LetDraw.

Notatka

Excalidraw jest znakiem towarowym zespołu Excalidraw; LetDraw oferuje wyłącznie zgodność formatu plików i nie jest powiązany z Excalidraw.

Osadzanie diagramu (render.svg)

Publicznie udostępniony diagram możesz osadzić jako SVG w miejscach takich jak README czy Notion. Najpierw pobierz token udostępniania za pomocą share_diagram (lub REST .../share), a następnie:

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

Ten punkt końcowy zwraca image/svg+xml i nie wymaga tokenu API (renderowane są tylko udostępnione diagramy), więc możesz użyć go bezpośrednio wewnątrz <img src="...">.