{ "openapi": "3.1.0", "info": { "title": "Markdown to PDF Converter API", "version": "1.0.0", "description": "Generate polished, task-specific PDF documents from Markdown with built-in or saved custom templates.", "x-publication-catalog-version": "2026-07-20.1" }, "externalDocs": { "description": "Guides and API documentation", "url": "https://markdowntopdfconverter.com/api-docs" }, "servers": [ { "url": "https://markdowntopdfconverter.com", "description": "Production" } ], "tags": [ { "name": "PDF generation", "description": "Render Markdown as a styled PDF." }, { "description": "Discover current templates and immutable release identities.", "name": "Template catalog" }, { "description": "Inspect the channel-neutral plan, quota, credit, and successful-render ledger state.", "name": "Entitlements" } ], "paths": { "/api/v1/convert": { "post": { "operationId": "convertMarkdownToPdf", "summary": "Convert Markdown to PDF", "description": "Returns the generated PDF bytes directly with Content-Type application/pdf. Premium templates share the signed-in account's five-export trial allowance across the browser, REST API, and MCP.", "tags": [ "PDF generation" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionRequest" }, "examples": { "executiveBrief": { "summary": "Executive launch brief", "value": { "markdown": "# Q3 Launch Brief\n\n## Decision\nApprove the partner launch window.", "templateId": "executive", "filename": "launch-brief", "options": { "pageNumbers": true } } }, "savedCustomTemplate": { "summary": "Saved branded template", "value": { "markdown": "# Monthly Review\n\n## Highlights\nA polished recurring report.", "templateId": "executive", "customTemplateId": "5eb2d8db-2ad1-4703-847c-d252c36b384d", "filename": "monthly-review" } } } } } }, "responses": { "200": { "description": "The generated PDF.", "headers": { "Content-Disposition": { "description": "Attachment filename derived from the filename request field.", "schema": { "type": "string" } }, "X-Premium-Trial-Remaining": { "description": "Premium exports remaining when a free account uses the premium trial.", "schema": { "type": "integer", "minimum": 0, "maximum": 4 } } }, "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf", "contentEncoding": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/templates": { "get": { "description": "Returns the authoritative versioned template catalog used by the web app, REST API, MCP server, documentation, and sample kits.", "operationId": "listPublicationTemplates", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCatalogResponse" } } }, "description": "The current catalog plus immutable release history." } }, "security": [], "summary": "List publication templates", "tags": [ "Template catalog" ] } }, "/api/v1/entitlements": { "get": { "description": "Returns the API key owner's current plan, cross-channel quota balances, purchased credits, premium-trial balance, grandfathering state, and successful-render ledger reconciliation. Requires the usage:read scope and does not consume conversion quota.", "operationId": "getEntitlementBalance", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementBalanceResponse" } } }, "description": "The account's current entitlement balance." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The API key does not have the usage:read scope." }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get entitlement balance", "tags": [ "Entitlements" ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "mp_live_ API key", "description": "Create and revoke keys in Dashboard > API Keys." } }, "schemas": { "ConversionRequest": { "type": "object", "required": [ "markdown" ], "properties": { "markdown": { "type": "string", "minLength": 1, "maxLength": 200000, "description": "Markdown source to render." }, "templateId": { "type": "string", "enum": [ "clean", "executive", "resume", "resume-ats", "resume-executive", "resume-technical", "resume-product", "resume-consulting", "resume-finance", "resume-clinical", "resume-academic", "resume-graduate", "coverletter", "coverletter-ats", "coverletter-executive", "coverletter-technical", "coverletter-product", "coverletter-consulting", "coverletter-finance", "coverletter-clinical", "coverletter-academic", "coverletter-graduate", "assignment-high-school-essay", "assignment-high-school-lab", "assignment-high-school-project", "assignment-college-essay", "assignment-college-case-study", "assignment-college-lab", "assignment-university-research", "assignment-university-capstone", "assignment-university-problem-set", "proposal-consulting", "proposal-project", "proposal-sales", "proposal-grant", "proposal-sponsorship", "proposal-rfp-response", "proposal-freelance", "proposal-partnership", "proposal-nonprofit-program", "marketing-product-one-pager", "marketing-customer-case-study", "marketing-white-paper", "marketing-company-profile", "marketing-media-kit", "marketing-press-kit", "marketing-product-brochure", "marketing-campaign-report", "marketing-event-program", "academic", "academic-submission", "academic-proceedings", "book-literary", "book-editorial", "book-guide", "legal", "creative" ], "default": "clean", "x-publication-catalog-version": "2026-07-20.1" }, "filename": { "type": "string", "maxLength": 200, "description": "Download filename. The .pdf extension is added when omitted." }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "ja", "zh-CN", "ko", "pt-BR", "ar", "ru", "hi", "it" ], "default": "en" }, "customTemplateId": { "type": "string", "format": "uuid", "description": "ID of a saved custom template owned by the API key's user." }, "options": { "$ref": "#/components/schemas/ConversionOptions" } } }, "ConversionOptions": { "type": "object", "properties": { "pageNumbers": { "type": "boolean" }, "bodyTextColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "examples": [ "#243248" ] }, "headingTextColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "examples": [ "#16243d" ] }, "creativeAccent": { "type": "string", "enum": [ "slate", "purple", "blue", "emerald", "rose", "amber" ] } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "issues": { "type": "array", "items": {} }, "upgrade": { "type": "boolean" } } }, "PublicationTemplate": { "additionalProperties": false, "properties": { "category": { "type": "string" }, "description": { "type": "string" }, "family": { "type": "string" }, "id": { "enum": [ "clean", "executive", "resume", "resume-ats", "resume-executive", "resume-technical", "resume-product", "resume-consulting", "resume-finance", "resume-clinical", "resume-academic", "resume-graduate", "coverletter", "coverletter-ats", "coverletter-executive", "coverletter-technical", "coverletter-product", "coverletter-consulting", "coverletter-finance", "coverletter-clinical", "coverletter-academic", "coverletter-graduate", "assignment-high-school-essay", "assignment-high-school-lab", "assignment-high-school-project", "assignment-college-essay", "assignment-college-case-study", "assignment-college-lab", "assignment-university-research", "assignment-university-capstone", "assignment-university-problem-set", "proposal-consulting", "proposal-project", "proposal-sales", "proposal-grant", "proposal-sponsorship", "proposal-rfp-response", "proposal-freelance", "proposal-partnership", "proposal-nonprofit-program", "marketing-product-one-pager", "marketing-customer-case-study", "marketing-white-paper", "marketing-company-profile", "marketing-media-kit", "marketing-press-kit", "marketing-product-brochure", "marketing-campaign-report", "marketing-event-program", "academic", "academic-submission", "academic-proceedings", "book-literary", "book-editorial", "book-guide", "legal", "creative" ], "type": "string" }, "name": { "type": "string" }, "premium": { "type": "boolean" }, "release": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "version" ], "type": "object" }, "sample": { "additionalProperties": false, "properties": { "downloadable": { "type": "boolean" }, "formats": { "items": { "type": "string" }, "type": "array" } }, "required": [ "downloadable", "formats" ], "type": "object" }, "variant": { "type": [ "string", "null" ] } }, "required": [ "category", "description", "family", "id", "name", "premium", "release", "sample", "variant" ], "type": "object" }, "TemplateCatalogRelease": { "additionalProperties": false, "properties": { "contractSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "current": { "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "published", "deprecated", "retired" ], "type": "string" }, "templateId": { "type": "string" }, "version": { "type": "string" } }, "required": [ "contractSha256", "current", "id", "status", "templateId", "version" ], "type": "object" }, "TemplateCatalogResponse": { "additionalProperties": false, "properties": { "catalogSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "catalogVersion": { "type": "string" }, "defaultLocale": { "enum": [ "en", "es", "fr", "de", "ja", "zh-CN", "ko", "pt-BR", "ar", "ru", "hi", "it" ], "type": "string" }, "families": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "templateIds": { "items": { "enum": [ "clean", "executive", "resume", "resume-ats", "resume-executive", "resume-technical", "resume-product", "resume-consulting", "resume-finance", "resume-clinical", "resume-academic", "resume-graduate", "coverletter", "coverletter-ats", "coverletter-executive", "coverletter-technical", "coverletter-product", "coverletter-consulting", "coverletter-finance", "coverletter-clinical", "coverletter-academic", "coverletter-graduate", "assignment-high-school-essay", "assignment-high-school-lab", "assignment-high-school-project", "assignment-college-essay", "assignment-college-case-study", "assignment-college-lab", "assignment-university-research", "assignment-university-capstone", "assignment-university-problem-set", "proposal-consulting", "proposal-project", "proposal-sales", "proposal-grant", "proposal-sponsorship", "proposal-rfp-response", "proposal-freelance", "proposal-partnership", "proposal-nonprofit-program", "marketing-product-one-pager", "marketing-customer-case-study", "marketing-white-paper", "marketing-company-profile", "marketing-media-kit", "marketing-press-kit", "marketing-product-brochure", "marketing-campaign-report", "marketing-event-program", "academic", "academic-submission", "academic-proceedings", "book-literary", "book-editorial", "book-guide", "legal", "creative" ], "type": "string" }, "type": "array" } }, "required": [ "id", "templateIds" ], "type": "object" }, "type": "array" }, "locales": { "items": { "enum": [ "en", "es", "fr", "de", "ja", "zh-CN", "ko", "pt-BR", "ar", "ru", "hi", "it" ], "type": "string" }, "type": "array" }, "releasedAt": { "format": "date-time", "type": "string" }, "releases": { "items": { "$ref": "#/components/schemas/TemplateCatalogRelease" }, "type": "array" }, "schemaVersion": { "const": 1, "type": "integer" }, "templates": { "items": { "$ref": "#/components/schemas/PublicationTemplate" }, "type": "array" } }, "required": [ "catalogSha256", "catalogVersion", "defaultLocale", "families", "locales", "releasedAt", "releases", "schemaVersion", "templates" ], "type": "object" }, "EntitlementBalanceItem": { "additionalProperties": false, "properties": { "channel": { "enum": [ "all", "api_mcp", "web" ], "type": "string" }, "id": { "enum": [ "web_daily", "premium_trial", "api_monthly", "browser_credits", "api_credits" ], "type": "string" }, "limit": { "minimum": 0, "type": [ "integer", "null" ] }, "period": { "enum": [ "daily", "monthly", "lifetime", "purchase" ], "type": "string" }, "remaining": { "minimum": 0, "type": [ "integer", "null" ] }, "used": { "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "channel", "id", "limit", "period", "remaining", "used" ], "type": "object" }, "EntitlementBalanceResponse": { "additionalProperties": false, "properties": { "asOf": { "format": "date-time", "type": "string" }, "balances": { "items": { "$ref": "#/components/schemas/EntitlementBalanceItem" }, "maxItems": 5, "minItems": 5, "type": "array" }, "contractVersion": { "const": "entitlement.balance.v1", "type": "string" }, "found": { "const": true, "type": "boolean" }, "grandfathering": { "additionalProperties": false, "properties": { "fromPolicy": { "type": [ "string", "null" ] }, "grantedAt": { "format": "date-time", "type": [ "string", "null" ] }, "plan": { "enum": [ "free", "monthly", "yearly", "credits", null ], "type": [ "string", "null" ] }, "until": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "fromPolicy", "grantedAt", "plan", "until" ], "type": "object" }, "plan": { "enum": [ "anonymous", "free", "monthly", "yearly", "credits", "admin" ], "type": "string" }, "policyVersion": { "type": "string" }, "reconciliation": { "additionalProperties": false, "properties": { "ledgerSuccesses": { "minimum": 0, "type": "integer" }, "missingLedgerEvents": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "drift", "not_applicable", "reconciled" ], "type": "string" }, "usageSuccesses": { "minimum": 0, "type": "integer" } }, "required": [ "ledgerSuccesses", "missingLedgerEvents", "status", "usageSuccesses" ], "type": "object" } }, "required": [ "asOf", "balances", "contractVersion", "found", "grandfathering", "plan", "policyVersion", "reconciliation" ], "type": "object" } }, "responses": { "BadRequest": { "description": "Invalid JSON, request body, or template ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "The API key is missing, invalid, or has no user profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PaymentRequired": { "description": "Monthly calls, credits, or the five-export premium trial are exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "The custom template does not exist or is not owned by the API key's user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnsupportedMediaType": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnprocessableContent": { "description": "Conversion options are invalid or an external resource cannot be loaded safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "The user or service rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServerError": { "description": "Account verification or PDF generation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unavailable": { "description": "The rendering cost budget is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }