{"openapi":"3.1.0","info":{"title":"mdapi.io — Markdown Converter API","description":"Convert documents, images and webpages to Markdown.","version":"1.0.0"},"servers":[{"url":"https://mdapi.io","description":"Production"}],"paths":{"/":{"get":{"summary":"Convert URL to Markdown","description":"Fetches a publicly accessible URL and returns clean Markdown. Free tier available. Use POST for file uploads.","operationId":"convertUrl","parameters":[{"name":"url","in":"query","schema":{"type":"string","format":"uri-reference"},"description":"URL to convert to Markdown (supports PDF, DOCX, XLSX, JPG, PNG, WebP, HTML, etc.; required if no text)"},{"name":"text","in":"query","schema":{"type":"string"},"description":"Direct text content to process (alternative to url; HTML, XML, JSON, CSV, TXT; required if no url)"},{"name":"prompt","in":"query","schema":{"type":"string"},"description":"Custom instructions for LLM processing (e.g., 'Summarize this', 'Extract key facts', 'Convert to JSON', 'Analyze')"},{"name":"result","in":"query","schema":{"type":"string","enum":["markdown","prompt","both"]},"description":"Response format: 'markdown' (default) returns raw converted Markdown; 'prompt' returns LLM-processed result only (requires prompt parameter); 'both' returns both raw Markdown and prompt_result"},{"name":"stream","in":"query","schema":{"type":"string","enum":["true"]},"description":"Enable streaming SSE response. Returns chunks as Server-Sent Events with token_info first, then content chunks, ending with [DONE]"},{"name":"token","in":"query","schema":{"type":"string"},"description":"Access token for paid tier (or use Authorization header)"},{"name":"memo","in":"query","schema":{"type":"string","minLength":8,"maxLength":8},"description":"Memo for token activation (required only when activating new token)"},{"name":"Authorization","in":"header","schema":{"type":"string"},"description":"Bearer token authentication (alternative to token query parameter)"},{"name":"X-Token-Required","in":"header","schema":{"type":"string"},"description":"Token required for payment (x402 v1)"},{"name":"PAYMENT-SIGNATURE","in":"header","schema":{"type":"string"},"description":"x402 v2 payment payload signature"},{"name":"PAYMENT-REQUIRED","in":"header","schema":{"type":"string"},"description":"x402 v2 payment requirements"}],"responses":{"200":{"description":"Markdown content - GET always returns text/markdown. Token info is in response headers.","headers":{"X-Token-Balance":{"schema":{"type":"string"},"description":"Remaining token balance for paid tier (e.g., '99')"},"X-Token-Expires":{"schema":{"type":"string"},"description":"Token expiry timestamp for paid tier"},"X-Token-Status":{"schema":{"type":"string","enum":["valid","expired","exhausted","free"]},"description":"Token status"},"X-Resource":{"schema":{"type":"string"},"description":"Original filename or URL"}},"content":{"text/markdown":{"schema":{"type":"string","description":"Converted Markdown content. When result=prompt with prompt parameter, returns LLM-processed result as markdown (not JSON)."}}}},"400":{"description":"Bad request - no url or text provided"},"402":{"description":"Payment required","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string","description":"x402 payment requirements JSON"}},"X-Token-Required":{"schema":{"type":"string","description":"Token required for paid tier"}},"X-Memo-Required":{"schema":{"type":"string","description":"Memo required for new token activation"}},"X-Wallet-Address":{"schema":{"type":"string","description":"Solana wallet address for payment"}},"X-QR-Payment":{"schema":{"type":"string","format":"uri","description":"QR code for payment"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded"}}},"post":{"summary":"Convert URL or upload file","description":"Supports both URL conversion and multipart file upload. Returns JSON with Markdown content.","operationId":"convertPost","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL to convert to Markdown (supports PDF, DOCX, XLSX, JPG, PNG, WebP, SVG, HTML, etc.)"},"text":{"type":"string","description":"Direct text content to process (alternative to url/file; HTML, XML, JSON, CSV, TXT)"},"file":{"type":"string","format":"binary","description":"File to convert (PDF, DOCX, XLSX, ODT, ODS, JPG, PNG, WebP, SVG; max 100MB)"},"token":{"type":"string","description":"Access token for paid tier (or use Authorization header)"},"memo":{"type":"string","description":"Memo for token activation (required only when activating new token)"},"prompt":{"type":"string","description":"Custom instructions for LLM processing (e.g., 'Summarize this', 'Extract key facts', 'Convert to JSON', 'Analyze')"},"result":{"type":"string","enum":["markdown","prompt","both"],"description":"Response format: 'markdown' (default) returns raw converted Markdown; 'prompt' returns LLM-processed result only (requires prompt parameter); 'both' returns both raw Markdown and prompt_result"},"stream":{"type":"string","enum":["true"],"description":"Enable streaming SSE response. Returns chunks as Server-Sent Events with token_info first, then content chunks, ending with [DONE]"}}}},"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL to convert to Markdown"},"text":{"type":"string","description":"Direct text content to process"},"token":{"type":"string","description":"Access token for paid tier"},"memo":{"type":"string","description":"Memo for token activation"},"prompt":{"type":"string","description":"Custom instructions for LLM processing"},"result":{"type":"string","enum":["markdown","prompt","both"],"description":"Response format: 'markdown' (default), 'prompt', or 'both'"}}}}}},"responses":{"200":{"description":"JSON with Markdown content","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether conversion was successful"},"markdown":{"type":"string","description":"Converted Markdown content (present when result=markdown or result=both)"},"prompt_result":{"type":"string","description":"LLM-processed result (present when result=prompt or result=both, requires prompt parameter)"},"resource":{"type":"string","description":"Original URL, 'text', or filename"},"mimetype":{"type":"string","description":"MIME type of source file"},"token_status":{"type":"string","enum":["free","valid","invalid"],"description":"Token status after request"},"token_balance":{"type":"integer","description":"Remaining token balance for paid tier (null for free tier)","nullable":true},"token_expires":{"type":"string","format":"date-time","description":"Token expiry timestamp for paid tier (null for free tier)","nullable":true}}}}}},"400":{"description":"Bad request - no url, text, or file provided"},"402":{"description":"Payment required"},"413":{"description":"File too large (max 100MB)"},"429":{"description":"Rate limit exceeded"}}}},"/v1/chat/completions":{"post":{"summary":"OpenAI-compatible markdown conversion","description":"Converts URLs or files using OpenAI-compatible API. Supports streaming SSE, image_url, file upload, custom LLM instructions, and JSON extraction.","operationId":"openaiConvert","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","default":"markdown-v1","description":"Model identifier (any string accepted for compatibility, result unaffected)"},"messages":{"type":"array","description":"Chat messages with URL, image_url, or file content","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","system","assistant"]},"content":{"oneOf":[{"type":"string","description":"Text content (URLs auto-detected)"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image_url","file"]},"text":{"type":"string"},"image_url":{"type":"object","properties":{"url":{"type":"string","description":"HTTP URL or data URL (data:image/...;base64,...)"}}},"file":{"type":"object","properties":{"data":{"type":"string","description":"Base64 encoded file"},"filename":{"type":"string"}}}}}}]}}}},"stream":{"type":"boolean","default":false,"description":"Enable streaming SSE responses"},"url":{"type":"string","format":"uri","description":"Direct URL to convert (alternative to messages)"},"file":{"type":"object","properties":{"data":{"type":"string","description":"Base64 encoded file"},"filename":{"type":"string","description":"Original filename"}}}},"required":["model"]}}}},"responses":{"200":{"description":"OpenAI-compatible response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique completion ID"},"object":{"type":"string","enum":["chat.completion","chat.completion.chunk"]},"created":{"type":"integer","description":"Unix timestamp"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}},"delta":{"type":"object","properties":{"content":{"type":"string"},"role":{"type":"string"}}},"finish_reason":{"type":"string","enum":["stop","length"]}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}}}}},"400":{"description":"Bad request — no URL or file provided"},"402":{"description":"Payment required"},"405":{"description":"Method not allowed — use POST"},"429":{"description":"Rate limit exceeded"}}}},"/health":{"get":{"summary":"Health check","description":"Public health check endpoint for monitoring. Returns service status and version.","operationId":"healthCheck","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"}}}}}}}}},"/mcp":{"get":{"summary":"MCP server manifest","description":"Returns MCP server manifest with available tools: convert (unified tool for URL and file conversion).","operationId":"mcpManifest","responses":{"200":{"description":"MCP server manifest","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"MCP tool call","description":"Execute MCP tool calls (JSON-RPC tools/call).","operationId":"mcpToolCall","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["tools/call"]},"params":{"type":"object","properties":{"name":{"type":"string","enum":["convert"]},"arguments":{"type":"object"}}}}}}}},"responses":{"200":{"description":"Tool call result","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}},"isError":{"type":"boolean"}}}}}}}}},"/acp/rpc":{"post":{"summary":"ACP RPC endpoint","description":"ACP RPC endpoint supporting tools/list, tools/call, resources/list, resources/read, initialize methods.","operationId":"acpRpc","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string"},"params":{"type":"object"},"id":{"type":"string"}}}}}},"responses":{"200":{"description":"ACP response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request"},"405":{"description":"Method not allowed"}}}},"/llms.txt":{"get":{"summary":"API documentation","description":"Returns condensed API documentation for AI agents.","operationId":"llmsTxt","responses":{"200":{"description":"API documentation (condensed)","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/llms-full.txt":{"get":{"summary":"Full API documentation","description":"Returns full API documentation with all details.","operationId":"llmsFullTxt","responses":{"200":{"description":"API documentation (full)","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/.well-known/ai-discovery.json":{"get":{"summary":"AI discovery","description":"Unified AI agent discovery endpoint combining MCP, ACP, A2A, and other agent protocol manifests.","operationId":"aiDiscovery","responses":{"200":{"description":"AI discovery manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent.json":{"get":{"summary":"AI agent discovery","description":"Returns agent metadata for AI agent frameworks (A2A, MCP, etc.). Includes features, supported formats, payment info, and authentication methods.","operationId":"agentDiscovery","responses":{"200":{"description":"Agent discovery JSON","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent-card.json":{"get":{"summary":"A2A agent card","description":"Returns Google A2A protocol agent card for agent discovery.","operationId":"a2aAgentCard","responses":{"200":{"description":"A2A agent card","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/acp.json":{"get":{"summary":"ACP manifest","description":"Agent Client Protocol manifest for IDE agents (JetBrains, Cursor, VS Code).","operationId":"acpManifest","responses":{"200":{"description":"ACP manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/x402.json":{"get":{"summary":"x402 payment manifest","description":"x402 v2 payment manifest for autonomous agent payments (USDC on Solana, $0.01/conversion).","operationId":"x402Manifest","responses":{"200":{"description":"x402 manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/openapi.json":{"get":{"summary":"OpenAPI specification (JSON)","description":"Returns full OpenAPI specification in JSON format for Swagger, Postman, SDK generation.","operationId":"openApiJson","responses":{"200":{"description":"OpenAPI specification (JSON)","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/openapi.yaml":{"get":{"summary":"OpenAPI specification (YAML)","description":"Returns full OpenAPI specification in YAML format for human-readable editing.","operationId":"openApiYaml","responses":{"200":{"description":"OpenAPI specification (YAML)","content":{"text/yaml":{"schema":{"type":"string"}}}}}}},"/.well-known/mapi.md":{"get":{"summary":"MAPI specification","description":"Returns MAPI (Markdown API) specification in Markdown format with code examples.","operationId":"mapiSpec","responses":{"200":{"description":"MAPI specification","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/.well-known/skill.md":{"get":{"summary":"Skill specification (Markdown)","description":"Returns human-readable skill documentation in Markdown format.","operationId":"skillMd","responses":{"200":{"description":"Skill specification","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"x402Payment":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE"},"xPaymentLegacy":{"type":"apiKey","in":"header","name":"X-PAYMENT"}},"schemas":{"PaymentRequired":{"type":"object","properties":{"code":{"type":"string","enum":["PAYMENT_REQUIRED"]},"message":{"type":"string"},"wallet":{"type":"string","description":"Solana wallet address"},"amount":{"type":"integer","description":"Amount in micro-units (USDC)"},"memo":{"type":"string","description":"Required memo for activation"}},"required":["code","message","wallet","amount"]},"PaymentResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failed","pending"]},"txHash":{"type":"string","description":"Transaction hash"},"token":{"type":"string","description":"Activated token"},"balance":{"type":"integer","description":"Token balance (conversions remaining)"},"expires":{"type":"string","format":"date-time","description":"Token expiry timestamp"}}},"McpToolCall":{"type":"object","properties":{"method":{"type":"string","enum":["tools/call"]},"params":{"type":"object","properties":{"name":{"type":"string","enum":["convert"]},"arguments":{"type":"object"}}}},"required":["method","params"]},"McpToolResult":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}},"isError":{"type":"boolean"}}},"AcpRpcRequest":{"type":"object","properties":{"method":{"type":"string"},"params":{"type":"object"},"id":{"type":"string"}},"required":["method"]},"AcpRpcResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":"string"},"result":{"type":"object"},"error":{"type":"object"}}}}},"security":[{"bearerAuth":[]},{"x402Payment":[]},{"xPaymentLegacy":[]},{}],"tags":[{"name":"conversion","description":"Document and URL conversion"},{"name":"openai","description":"OpenAI-compatible API"},{"name":"discovery","description":"Agent and API discovery"}]}