{"openapi":"3.1.0","info":{"title":"Markdown Tidy API","version":"v1","description":"The public Markdown Tidy API. Convert / clean / repair markdown into HTML, plain text, PDF, DOCX, or PNG. Authenticate with an `X-API-KEY` header — create one in your dashboard at /account/api-keys. Each successful /convert call debits 1 credit from your wallet."},"servers":[{"url":"https://mdtidy.com","description":"Production"}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Issued via dashboard. Prefix `mt_test_…` for sandbox, `mt_live_…` for production."}},"schemas":{"ConvertRequest":{"type":"object","additionalProperties":false,"required":["markdown","format"],"properties":{"markdown":{"type":"string","minLength":1,"maxLength":1048576,"description":"The markdown source to convert. UTF-8. Hard cap: 1 MB."},"format":{"type":"string","enum":["html","text","pdf","docx","png"],"description":"Output format."},"designSystem":{"type":"string","maxLength":128,"description":"Slug of a built-in design system. Defaults to `minimal-clean`. Known: `minimal-clean`, `executive-report`, `developer-docs`."},"actions":{"type":"array","maxItems":2,"items":{"type":"string","enum":["clean","repair"]},"description":"Optional rule passes to run before rendering. Defaults to `['clean']`."}}},"ConvertResponse":{"type":"object","additionalProperties":false,"required":["format","contentType","byteSize","designSystem","warnings","creditsCharged","creditsRemaining","requestId"],"properties":{"format":{"type":"string","enum":["html","text","pdf","docx","png"]},"contentType":{"type":"string"},"byteSize":{"type":"integer","minimum":0},"designSystem":{"type":"string"},"output":{"type":"string","description":"Inline body for text/HTML outputs."},"outputBase64":{"type":"string","description":"Base64-encoded body for binary outputs (PDF/DOCX/PNG)."},"warnings":{"type":"array","items":{"type":"object","required":["rule","fixes"],"properties":{"rule":{"type":"string"},"fixes":{"type":"integer"}}}},"creditsCharged":{"type":"integer","minimum":0},"creditsRemaining":{"type":"integer","minimum":0},"requestId":{"type":"string"}}},"UsageResponse":{"type":"object","additionalProperties":false,"required":["subscriptionCredits","topupCredits","creditsRemaining","periodEnd","callsThisPeriod","recentCalls"],"properties":{"subscriptionCredits":{"type":"integer","minimum":0},"topupCredits":{"type":"integer","minimum":0},"creditsRemaining":{"type":"integer","minimum":0},"periodEnd":{"type":"string","nullable":true},"callsThisPeriod":{"type":"integer","minimum":0},"recentCalls":{"type":"array","items":{"type":"object","required":["id","endpoint","statusCode","durationMs","format","creditsCharged","errorCode","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"endpoint":{"type":"string"},"statusCode":{"type":"integer"},"durationMs":{"type":"integer"},"format":{"type":"string","nullable":true},"creditsCharged":{"type":"integer"},"errorCode":{"type":"string","nullable":true},"createdAt":{"type":"string"}}}}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}}},"responses":{"InvalidRequest":{"description":"Schema validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"MissingApiKey":{"description":"X-API-KEY header was not supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InvalidApiKey":{"description":"X-API-KEY is malformed, unknown, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"OutOfCredits":{"description":"Wallet has insufficient credits to satisfy the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"PayloadTooLarge":{"description":"Request body exceeds the 1 MB cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"UnsupportedFormat":{"description":"Requested format is not one of the supported outputs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"Per-key rate limit (60/min) exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}},"Retry-After":{"schema":{"type":"integer"}}}},"InternalError":{"description":"Server failed to complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"security":[{"apiKeyAuth":[]}],"paths":{"/api/v1/convert":{"post":{"summary":"Clean, repair, and convert markdown","description":"Runs the markdown through the requested pipeline (clean / repair) and renders to the requested output format. Charges 1 credit per successful render; failures are refunded automatically.","operationId":"convert","tags":["convert"],"security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertRequest"}}}},"responses":{"200":{"description":"Conversion succeeded.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Credits-Remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/OutOfCredits"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnsupportedFormat"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/usage":{"get":{"summary":"Read the caller credit balance and recent usage","description":"Returns the current wallet balance + recent API calls for the authenticated principal. Cheap; suitable for a dashboard widget.","operationId":"usage","tags":["usage"],"security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Wallet balance + recent calls.","headers":{"X-Request-ID":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"$ref":"#/components/responses/MissingApiKey"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}