{"openapi":"3.1.0","info":{"title":"Unmarkdown API","version":"1.0.0","description":"Markdown publishing platform API. Turn markdown into beautiful, hosted web pages in one API call. Supports 62 templates, Mermaid diagrams, Chart.js charts, Graphviz graphs, KaTeX math, and more.","contact":{"name":"Unmarkdown","url":"https:\/\/unmarkdown.com\/developers"}},"servers":[{"url":"https:\/\/api.unmarkdown.com\/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"\/convert":{"post":{"operationId":"convertMarkdown","summary":"Convert markdown to destination-specific output","description":"Converts markdown to HTML optimized for a specific destination (Google Docs, Word, Slack, OneNote, Email, or plain text). Does not save the document. Use this when you need formatted output for pasting into other applications.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConvertRequest"},"example":{"markdown":"# Hello World\n\nThis is a **bold** statement.","destination":"google-docs","template_id":"swiss","theme_mode":"light"}}}},"responses":{"200":{"description":"Conversion successful","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConvertResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"500":{"$ref":"#\/components\/responses\/InternalError"}}}},"\/templates":{"get":{"operationId":"listTemplates","summary":"List available templates","description":"Returns all 62 available templates with their IDs, names, categories, and descriptions. Use template IDs in other API calls. This endpoint does not count toward your monthly usage quota.","parameters":[{"name":"category","in":"query","description":"Filter by category","schema":{"type":"string","enum":["free","business","academic","developer","creative","dark","productivity","special"]}}],"responses":{"200":{"description":"Template list","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TemplateListResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/usage":{"get":{"operationId":"getUsage","summary":"Get current API usage statistics","description":"Returns your current monthly API usage, quota limits, and reset date. Supports both API key and session cookie authentication. Does not count toward your monthly usage quota.","responses":{"200":{"description":"Usage statistics","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/UsageResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/documents":{"post":{"operationId":"createDocument","summary":"Create a new document","description":"Creates a new document saved to your account. The document is not published. Use POST \/documents\/{id}\/publish to publish it, or use POST \/documents\/publish to create and publish in one call.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateDocumentRequest"},"example":{"title":"My Document","content":"# Hello\n\nThis is my document.","template_id":"executive","theme_mode":"light"}}}},"responses":{"201":{"description":"Document created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateDocumentResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"500":{"$ref":"#\/components\/responses\/InternalError"}}},"get":{"operationId":"listDocuments","summary":"List your documents","description":"Returns a paginated list of your documents, ordered by most recently updated. Use cursor-based pagination for large document lists. Does not count toward your monthly usage quota.","parameters":[{"name":"limit","in":"query","description":"Max results per page (1-100)","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"ISO timestamp cursor from previous response's next_cursor","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Document list","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DocumentListResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"500":{"$ref":"#\/components\/responses\/InternalError"}}}},"\/documents\/{id}":{"get":{"operationId":"getDocument","summary":"Get a document","description":"Returns a single document with full content. Only returns documents you own. Does not count toward your monthly usage quota.","parameters":[{"$ref":"#\/components\/parameters\/documentId"}],"responses":{"200":{"description":"Document details","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DocumentResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/InternalError"}}},"patch":{"operationId":"updateDocument","summary":"Update a document","description":"Updates one or more fields of an existing document. Only include the fields you want to change.","parameters":[{"$ref":"#\/components\/parameters\/documentId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/UpdateDocumentRequest"},"example":{"title":"Updated Title","content":"# Updated\n\nNew content here."}}}},"responses":{"200":{"description":"Document updated","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/UpdateDocumentResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"500":{"$ref":"#\/components\/responses\/InternalError"}}},"delete":{"operationId":"deleteDocument","summary":"Delete a document","description":"Permanently deletes a document. If the document is published, it will be unpublished first. This action cannot be undone.","parameters":[{"$ref":"#\/components\/parameters\/documentId"}],"responses":{"200":{"description":"Document deleted","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/InternalError"}}}},"\/documents\/{id}\/publish":{"post":{"operationId":"publishDocument","summary":"Publish a document","description":"Publishes an existing document, making it accessible via a public URL. If already published, updates the published version. The document must exist and belong to you.","parameters":[{"$ref":"#\/components\/parameters\/documentId"}],"requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PublishRequest"},"example":{"description":"A guide to getting started","visibility":"link"}}}},"responses":{"200":{"description":"Document published","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PublishResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"409":{"description":"Slug conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"429":{"$ref":"#\/components\/responses\/RateLimited"},"500":{"$ref":"#\/components\/responses\/InternalError"}}},"delete":{"operationId":"unpublishDocument","summary":"Unpublish a document","description":"Removes a document from public access. The document itself is not deleted and can be re-published later.","parameters":[{"$ref":"#\/components\/parameters\/documentId"}],"responses":{"200":{"description":"Document unpublished","content":{"application\/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"is_published":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/InternalError"}}}},"\/documents\/publish":{"post":{"operationId":"createAndPublishDocument","summary":"Create and publish a document in one call","description":"Creates a new document and immediately publishes it. Returns the published URL. This is the most common endpoint for programmatic publishing. Equivalent to calling POST \/documents followed by POST \/documents\/{id}\/publish.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateAndPublishRequest"},"example":{"title":"Weekly Report","content":"# Weekly Report\n\n## Summary\n\nKey highlights from this week...","template_id":"executive","theme_mode":"light"}}}},"responses":{"201":{"description":"Document created and published","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PublishResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"409":{"description":"Slug conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"429":{"$ref":"#\/components\/responses\/RateLimited"},"500":{"$ref":"#\/components\/responses\/InternalError"}}}},"\/demo\/publish":{"post":{"operationId":"demoPublish","summary":"Publish a demo page (no authentication required)","description":"Creates a temporary published page without requiring authentication. Pages expire after 72 hours. Use the returned claim_token with POST \/demo\/claim to permanently save the document to your account. Ideal for LLM agents, quick demos, and try-before-you-sign-up flows.","security":[],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DemoPublishRequest"},"example":{"title":"Quick Demo","content":"# Hello World\n\nThis page was published via the API.","template_id":"github","theme_mode":"light"}}}},"responses":{"201":{"description":"Demo page published","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DemoPublishResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"500":{"$ref":"#\/components\/responses\/InternalError"}}}},"\/demo\/claim":{"post":{"operationId":"claimDemoDocument","summary":"Claim a demo document","description":"Transfers ownership of a demo page to your account, making it permanent. Requires the claim_token returned from POST \/demo\/publish. The document gets a new URL under your username. Supports both API key and session cookie authentication.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ClaimRequest"},"example":{"claim_token":"550e8400-e29b-41d4-a716-446655440000"}}}},"responses":{"200":{"description":"Document claimed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ClaimResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/NotFound"},"410":{"description":"Demo page expired","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"500":{"$ref":"#\/components\/responses\/InternalError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key with um_ prefix. Create keys in Settings > API tab."}},"parameters":{"documentId":{"name":"id","in":"path","required":true,"description":"Document UUID","schema":{"type":"string","format":"uuid"}}},"schemas":{"ConvertRequest":{"type":"object","required":["markdown"],"properties":{"markdown":{"type":"string","description":"Markdown content to convert (max 100KB)"},"destination":{"type":"string","enum":["google-docs","email","word","slack","onenote","plain-text","generic","html"],"default":"generic","description":"Target format for the conversion output"},"template_id":{"type":"string","default":"swiss","description":"Template ID to apply for styling"},"theme_mode":{"type":"string","enum":["light","dark"],"default":"light"}}},"CreateDocumentRequest":{"type":"object","properties":{"title":{"type":"string","description":"Document title"},"content":{"type":"string","description":"Markdown content"},"template_id":{"type":"string","default":"swiss","description":"Template ID"},"theme_mode":{"type":"string","enum":["light","dark"],"default":"light"}}},"UpdateDocumentRequest":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"template_id":{"type":"string"},"theme_mode":{"type":"string","enum":["light","dark"]},"description":{"type":"string","nullable":true},"page_width":{"type":"string","enum":["standard","wide","full"]}}},"PublishRequest":{"type":"object","properties":{"slug":{"type":"string","description":"Custom URL slug (Pro only)"},"description":{"type":"string","description":"SEO description"},"hide_badge":{"type":"boolean","description":"Hide Unmarkdown badge (Pro only)"},"visibility":{"type":"string","enum":["link","public"],"description":"Access level (public is Pro only)"},"page_width":{"type":"string","enum":["standard","wide","full"]}}},"CreateAndPublishRequest":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Markdown content"},"title":{"type":"string","default":"Untitled"},"template_id":{"type":"string","default":"swiss"},"theme_mode":{"type":"string","enum":["light","dark"],"default":"light"},"slug":{"type":"string","description":"Custom URL slug (Pro only)"},"description":{"type":"string"}}},"DemoPublishRequest":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Markdown content (max 100KB)"},"title":{"type":"string","default":"Untitled"},"template_id":{"type":"string","default":"swiss"},"theme_mode":{"type":"string","enum":["light","dark"],"default":"light"}}},"ClaimRequest":{"type":"object","required":["claim_token"],"properties":{"claim_token":{"type":"string","format":"uuid","description":"Token from demo publish response"}}},"ConvertResponse":{"type":"object","properties":{"html":{"type":"string"},"plain_text":{"type":"string"},"destination":{"type":"string"},"template_id":{"type":"string"},"theme_mode":{"type":"string"}}},"TemplateListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"}}}},"total":{"type":"integer"}}},"UsageResponse":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"},"remaining":{"type":"integer"},"month":{"type":"string","example":"2026-02"},"reset_date":{"type":"string","format":"date-time"},"tier":{"type":"string","enum":["free","pro"]}}},"CreateDocumentResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"template_id":{"type":"string"},"theme_mode":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"DocumentListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/DocumentSummary"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","format":"date-time","nullable":true}}},"DocumentSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"template_id":{"type":"string"},"theme_mode":{"type":"string"},"is_published":{"type":"boolean"},"slug":{"type":"string","nullable":true},"page_width":{"type":"string","nullable":true},"word_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"DocumentResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"content":{"type":"string"},"template_id":{"type":"string"},"theme_mode":{"type":"string"},"is_published":{"type":"boolean"},"slug":{"type":"string","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"description":{"type":"string","nullable":true},"page_width":{"type":"string","nullable":true},"visibility":{"type":"string","nullable":true},"word_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"UpdateDocumentResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"template_id":{"type":"string"},"theme_mode":{"type":"string"},"page_width":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"PublishResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"published_url":{"type":"string","format":"uri"},"published_at":{"type":"string","format":"date-time"},"template_id":{"type":"string"},"word_count":{"type":"integer"},"reading_time_minutes":{"type":"integer"}}},"DemoPublishResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"claim_token":{"type":"string","format":"uuid"},"expires_at":{"type":"string","format":"date-time"},"template_id":{"type":"string"},"id":{"type":"string","format":"uuid"}}},"ClaimResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"published_url":{"type":"string","format":"uri"},"slug":{"type":"string"},"template_id":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}}}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"code":"validation_error","message":"markdown field is required","status":400}}}}},"Unauthorized":{"description":"Authentication required","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"Missing Authorization header. Use: Bearer um_your_key","status":401}}}}},"Forbidden":{"description":"Insufficient permissions or tier","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"code":"forbidden","message":"Custom slugs are a Pro feature","status":403}}}}},"NotFound":{"description":"Resource not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Document not found","status":404}}}}},"RateLimited":{"description":"Rate limit or quota exceeded","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Limit: 10 req\/sec","status":429}}}}},"InternalError":{"description":"Internal server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred","status":500}}}}}}}}