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