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