{"openapi":"3.0.3","info":{"title":"ToMarkdown REST API","version":"1.0.0","description":"Stateless keyless REST API for converting binary and markup documents (PDF, Office, OpenDocument, Apple Numbers, HTML, XML, CSV, JSON up to 10 MiB) into GitHub-Flavored Markdown with token telemetry.","contact":{"name":"CodeAP Studio","url":"https://codeap.com/about"}},"externalDocs":{"description":"Interactive API Playground & Multi-Language SDK Generator","url":"https://markdown.codeap.com/tools/document-to-markdown-api"},"servers":[{"url":"https://markdown.codeap.com","description":"Production Server"},{"url":"/","description":"Current Origin"}],"tags":[{"name":"Conversions","description":"Stateless document-to-Markdown conversion resources."},{"name":"Formats","description":"Supported input document formats, MIME types, and quota limits."},{"name":"System","description":"Service liveness and contract version probes."}],"paths":{"/api/v1/conversions":{"post":{"tags":["Conversions"],"operationId":"createConversion","summary":"Create a document-to-Markdown conversion","description":"Uploads a supported document (max 10 MiB) via multipart/form-data and synchronously returns structured GitHub-Flavored Markdown. Negotiate JSON metadata vs. raw Markdown stream via the `format` query parameter or `Accept` request header. Raster and vector images (.png, .jpg, .webp, .svg) are rejected with HTTP 415.","parameters":[{"$ref":"#/components/parameters/ConversionFormatQuery"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ConversionCreateRequest"}}}},"responses":{"200":{"description":"Document converted to GitHub-Flavored Markdown.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Content-Disposition":{"$ref":"#/components/headers/ContentDisposition"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversion"}},"text/markdown":{"schema":{"type":"string","example":"# Architecture Specification\n\nConverted GitHub-Flavored Markdown..."}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"413":{"$ref":"#/components/responses/PayloadTooLargeError"},"415":{"$ref":"#/components/responses/UnsupportedMediaTypeError"},"429":{"$ref":"#/components/responses/TooManyRequestsError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/formats":{"get":{"tags":["Formats"],"operationId":"listFormats","summary":"List supported document formats and quota limits","description":"Returns the supported input file extensions, associated MIME types, format categories, maximum upload byte ceiling, and per-IP rate limit.","parameters":[{"$ref":"#/components/parameters/FormatCategoryQuery"}],"responses":{"200":{"description":"Supported document formats and service limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatList"}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/api/v1/health":{"get":{"tags":["System"],"operationId":"getHealth","summary":"Get service health status","description":"Lightweight liveness and REST API contract version check.","responses":{"200":{"description":"Service is healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}}}}}},"components":{"parameters":{"ConversionFormatQuery":{"name":"format","in":"query","required":false,"description":"Response representation (`json` metadata envelope or raw `markdown` download). Overrides the `Accept` header when specified.","schema":{"type":"string","enum":["json","markdown"]}},"FormatCategoryQuery":{"name":"category","in":"query","required":false,"description":"Filter supported formats by document family.","schema":{"type":"string","enum":["document","spreadsheet","markup","data"]}}},"headers":{"RateLimitLimit":{"description":"Maximum conversions permitted per 60-second sliding window per client IP.","schema":{"type":"integer","example":15}},"RateLimitRemaining":{"description":"Remaining conversions available in the active 60-second window.","schema":{"type":"integer","example":14}},"RateLimitReset":{"description":"UTC Unix epoch timestamp (seconds) when the sliding window resets.","schema":{"type":"integer","example":1794402060}},"RetryAfter":{"description":"Seconds to wait before retrying after HTTP 429.","schema":{"type":"integer","example":42}},"ContentDisposition":{"description":"RFC 5987 attachment filename header returned when `text/markdown` is negotiated.","schema":{"type":"string","example":"attachment; filename=\"architecture-spec.md\""}}},"schemas":{"ConversionCreateRequest":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Binary or markup document to convert (max 10 MiB; raster/vector images are rejected)."}}},"Conversion":{"type":"object","required":["filename","media_type","size_bytes","token_count","markdown"],"properties":{"filename":{"type":"string","description":"Original uploaded filename.","example":"architecture-spec.pdf"},"media_type":{"type":"string","description":"Detected document MIME type.","example":"application/pdf"},"size_bytes":{"type":"integer","description":"Uploaded file size in bytes.","example":248910},"token_count":{"type":"integer","description":"Estimated BPE token count of the extracted Markdown.","example":1842},"markdown":{"type":"string","description":"Extracted GitHub-Flavored Markdown content.","example":"# Architecture Specification\n\nConverted Markdown content..."}}},"SupportedFormat":{"type":"object","required":["extension","media_types","category"],"properties":{"extension":{"type":"string","description":"Lowercase file extension without leading dot.","example":"pdf"},"media_types":{"type":"array","items":{"type":"string"},"description":"Accepted MIME types associated with this extension.","example":["application/pdf"]},"category":{"type":"string","enum":["document","spreadsheet","markup","data"],"description":"Document format family.","example":"document"}}},"FormatList":{"type":"object","required":["items","total_count","max_upload_bytes","rate_limit_per_minute"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupportedFormat"}},"total_count":{"type":"integer","description":"Number of format descriptors returned.","example":22},"max_upload_bytes":{"type":"integer","description":"Maximum single-file upload size in bytes (10 MiB).","example":10485760},"rate_limit_per_minute":{"type":"integer","description":"Per-IP conversion quota per 60-second window.","example":15}}},"HealthStatus":{"type":"object","required":["status","service","version"],"properties":{"status":{"type":"string","enum":["ok"],"example":"ok"},"service":{"type":"string","example":"tomarkdown-api"},"version":{"type":"string","example":"1.0.0"}}},"ErrorDetail":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","enum":["bad_request","invalid_parameter","not_found","payload_too_large","unsupported_media_type","rate_limit_exceeded","internal_error"],"example":"unsupported_media_type"},"message":{"type":"string","example":"Image and SVG files (.png, .jpg, .webp, .svg) are not supported on this document conversion API."},"status":{"type":"integer","example":415}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}}},"responses":{"BadRequestError":{"description":"Bad Request — missing file, empty upload, or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PayloadTooLargeError":{"description":"Payload Too Large — uploaded file exceeds the 10 MiB limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaTypeError":{"description":"Unsupported Media Type — image/SVG payload or unsupported file extension.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequestsError":{"description":"Too Many Requests — per-IP conversion quota exceeded (15 requests / 60s).","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error — upstream document extraction failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}