{"openapi":"3.1.0","info":{"title":"MarkdownTree API","description":"Public-safe Markdown parsing, graph transformation, outline, stats, export, share, AI degraded-state, and MCP tooling for MarkdownTree.","version":"1.0.0","contact":{"name":"Platphorm News","url":"https://markdown.platphormnews.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://markdown.platphormnews.com","description":"Production"}],"tags":[{"name":"Health","description":"Health and compliance state"},{"name":"Markdown","description":"Markdown parse, outline, stats, and graph operations"},{"name":"Export","description":"Markdown, HTML, JSON, and honest degraded export adapters"},{"name":"AI","description":"Backend model scaffolding and deterministic fallbacks"},{"name":"MCP","description":"JSON-RPC 2.0 MCP endpoint and read-only discovery"},{"name":"Discovery","description":"Public platform discovery files"}],"paths":{"/api/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Public-safe Phase 1 endpoint. PLATPHORM_API_KEY is not required unless PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions.","responses":{"200":{"description":"Service health summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/api/v1/health":{"get":{"tags":["Health"],"summary":"Versioned health check","description":"Public-safe Phase 1 endpoint. PLATPHORM_API_KEY is not required unless PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions.","responses":{"200":{"description":"Service health summary"}}}},"/api/v1/parse":{"post":{"tags":["Markdown"],"summary":"Parse Markdown","description":"Parse Markdown into concrete graph, outline, and stats data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/transform":{"post":{"tags":["Markdown"],"summary":"Transform Markdown to graph","description":"Parse Markdown and return graph nodes, edges, outline, and stats.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/outline":{"post":{"tags":["Markdown"],"summary":"Generate outline","description":"Generate a heading outline from Markdown.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/stats":{"post":{"tags":["Markdown"],"summary":"Get Markdown stats","description":"Count words, lines, headings, links, images, code blocks, nodes, and edges.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/export":{"post":{"tags":["Export"],"summary":"Export Markdown","description":"Export Markdown as markdown, html, json, or return honest degraded state for pdf/png.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/export/html":{"post":{"tags":["Export"],"summary":"Export HTML","description":"Convert Markdown to sanitized standalone HTML.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Sanitized standalone HTML document.","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/api/v1/export/json":{"post":{"tags":["Export"],"summary":"Export JSON","description":"Convert Markdown to structured graph, outline, stats, and source JSON.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/export/pdf":{"post":{"tags":["Export"],"summary":"PDF export degraded state","description":"Server-side PDF export is scaffolded and returns an honest unavailable state until configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/export/png":{"post":{"tags":["Export"],"summary":"PNG export degraded state","description":"Server-side PNG graph export is scaffolded and returns an honest unavailable state until configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/share":{"post":{"tags":["Export"],"summary":"Generate bounded share URL","description":"Generate a public-safe URL with bounded encoded Markdown content. No server persistence is claimed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/ai/status":{"get":{"tags":["AI"],"summary":"Model status","description":"Returns whether backend model integration is configured or degraded.","responses":{"200":{"description":"Model status"}}}},"/api/v1/ai/enhance":{"post":{"tags":["AI"],"summary":"Enhance Markdown","description":"Returns model-backed output when configured, otherwise an honest degraded state.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIEnhanceRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/ai/toc":{"post":{"tags":["AI"],"summary":"Generate table of contents","description":"Generate a deterministic table of contents from real headings; model support may be layered later.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/v1/ai/summarize":{"post":{"tags":["AI"],"summary":"Summarize Markdown","description":"Returns model-backed summary when configured, otherwise an honest degraded state.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownRequest"}}}},"responses":{"200":{"description":"Operation completed or returned an honest degraded state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Invalid request."},"429":{"description":"Rate limited."},"501":{"description":"Feature scaffolded but unavailable in Phase 1."},"503":{"description":"Backend model provider unavailable."}}}},"/api/mcp":{"get":{"tags":["MCP"],"summary":"MCP endpoint metadata","description":"Read-only MCP metadata and JSON-RPC usage.","responses":{"200":{"description":"MCP metadata"}}},"post":{"tags":["MCP"],"summary":"MCP JSON-RPC 2.0","description":"Accepts JSON-RPC 2.0 objects or batches for real Markdown tools and introspection.","responses":{"200":{"description":"JSON-RPC 2.0 response"}}}}},"components":{"securitySchemes":{"platphormApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Future protected-action key. Public-safe Phase 1 endpoints do not require it by default."},"platphormBearer":{"type":"http","scheme":"bearer","bearerFormat":"PLATPHORM_API_KEY","description":"Authorization: Bearer $PLATPHORM_API_KEY for future protected actions."}},"schemas":{"ApiResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean","deprecated":true},"data":{"type":"object"},"error":{"$ref":"#/components/schemas/ApiError"},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["ok"]},"ApiError":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]},"ApiMeta":{"type":"object","properties":{"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"requestId":{"type":"string"}}},"MarkdownRequest":{"type":"object","properties":{"markdown":{"type":"string","maxLength":262144},"options":{"type":"object"}},"required":["markdown"]},"ExportRequest":{"type":"object","properties":{"markdown":{"type":"string","maxLength":262144},"format":{"type":"string","enum":["markdown","json","html","pdf","png"]}},"required":["markdown","format"]},"AIEnhanceRequest":{"type":"object","properties":{"markdown":{"type":"string","maxLength":262144},"action":{"type":"string","enum":["improve","summarize","expand","fix-grammar","generate-toc"]},"context":{"type":"string","maxLength":4096}},"required":["markdown","action"]}}}}