{"openapi":"3.0.0","info":{"version":"0.1.0","title":"Plain Markdown API"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"},"LicenseKeyAuth":{"type":"apiKey","in":"header","name":"X-License-Key"}},"schemas":{},"parameters":{}},"paths":{"/v1/convert":{"post":{"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://example.com/article"},"response_format":{"type":"string","enum":["markdown","text"],"default":"markdown","example":"markdown"},"include_metadata":{"type":"boolean","default":false,"example":false}},"required":["url"]}}}},"responses":{"200":{"description":"Successfully converted page to Markdown","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"data":{"type":"object","properties":{"content":{"type":"string"},"metadata":{"type":"object","properties":{"title":{"type":"string"},"byline":{"type":"string","nullable":true},"excerpt":{"type":"string","nullable":true},"siteName":{"type":"string","nullable":true},"length":{"type":"integer"},"dir":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"}},"required":["title","byline","excerpt","siteName","length","dir","url"]}},"required":["content"]}},"required":["status","data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"403":{"description":"Target URL is blocked by security policy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"408":{"description":"Upstream fetch or conversion timeout","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"413":{"description":"Request body or upstream response too large","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"415":{"description":"Unsupported request content type","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"422":{"description":"Content extraction failed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"429":{"description":"Server is busy and cannot process conversion right now","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"503":{"description":"Service temporarily unavailable (retry with Retry-After header)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}}}}},"/v1/ai":{"post":{"security":[{"LicenseKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"markdown":{"type":"string","minLength":1,"maxLength":100000,"example":"# My Article\n\nSome content..."},"template":{"type":"string","enum":["answer-core-question","generate-questions","summarize","extract-action-items","simplify","atomic-note"],"example":"summarize"},"custom_prompt":{"type":"string","maxLength":2000,"example":"Translate this to Spanish."}},"required":["markdown"]}}}},"responses":{"200":{"description":"SSE stream of AI output chunks"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"anyOf":[{"type":"integer"},{"type":"string","enum":["ai_quota_exceeded"]}]},"message":{"type":"string"},"reset_at":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"anyOf":[{"type":"integer"},{"type":"string","enum":["ai_quota_exceeded"]}]},"message":{"type":"string"},"reset_at":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"403":{"description":"License key expired or inactive","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"anyOf":[{"type":"integer"},{"type":"string","enum":["ai_quota_exceeded"]}]},"message":{"type":"string"},"reset_at":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"429":{"description":"AI quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"anyOf":[{"type":"integer"},{"type":"string","enum":["ai_quota_exceeded"]}]},"message":{"type":"string"},"reset_at":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"500":{"description":"Internal server error or AI provider error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"anyOf":[{"type":"integer"},{"type":"string","enum":["ai_quota_exceeded"]}]},"message":{"type":"string"},"reset_at":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"anyOf":[{"type":"integer"},{"type":"string","enum":["ai_quota_exceeded"]}]},"message":{"type":"string"},"reset_at":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}}}}},"/v1/license/validate":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"example":"pmpro_abc123"}},"required":["key"]}}}},"responses":{"200":{"description":"License validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"expires_at":{"type":"string"},"tier":{"type":"string","enum":["pro"]},"ai_calls_used":{"type":"integer"},"ai_calls_limit":{"type":"integer"}},"required":["valid"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["status","error"]}}}}}}}}}