{"openapi":"3.1.0","info":{"title":"markdown.page API","version":"1.0.0","summary":"Markdown publishing API","description":"Publish Markdown to a public URL. Public API for publishing immutable pages, reporting abusive pages, and managing paid placements. No account or API key required.","x-guidance":"Use POST /api/publish to publish Markdown for free. Use GET /api/featured/mpp/purchase/{plan} for a quote, then POST the same MPP purchase path; an unpaid POST returns the MPP challenge to authorize and retry.","termsOfService":"https://markdown.page/legal","contact":{"url":"https://markdown.page/api","email":"hello@markdown.page"}},"servers":[{"url":"https://markdown.page"}],"tags":[{"name":"Publishing","description":"Create public Markdown pages that cannot be edited after publishing."},{"name":"Featured promotions","description":"Pricing, validation, checkout, paid agentic purchases, and purchase status."},{"name":"Moderation","description":"Report abusive public pages."},{"name":"Discovery","description":"Machine-readable documentation."}],"paths":{"/api/publish":{"post":{"tags":["Publishing"],"operationId":"publishMarkdown","summary":"Publish markdown","description":"Publish a Markdown page and receive its public URL. Alias: POST /api and POST /api/.","security":[],"requestBody":{"required":true,"content":{"text/markdown":{"schema":{"type":"string","maxLength":1048576},"examples":{"basic":{"value":"# Hello world"}}},"text/plain":{"schema":{"type":"string","maxLength":1048576}},"application/json":{"schema":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/PublishJsonBody"}]}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PublishJsonBody"}}}},"responses":{"201":{"description":"Page published.","headers":{"Location":{"schema":{"type":"string","format":"uri"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishResponse"}},"text/plain":{"schema":{"type":"string","format":"uri"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"Request envelope or Markdown exceeds its size limit."},"415":{"description":"Multipart upload is not supported."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api":{"get":{"tags":["Discovery"],"operationId":"getApiDocs","summary":"Get API documentation","security":[],"responses":{"200":{"description":"HTML or plaintext API documentation.","content":{"text/html":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}}}},"post":{"tags":["Publishing"],"operationId":"publishMarkdownAlias","summary":"Publish markdown","description":"Publish a Markdown page and receive its public URL. Alias: POST /api and POST /api/.","security":[],"requestBody":{"required":true,"content":{"text/markdown":{"schema":{"type":"string","maxLength":1048576},"examples":{"basic":{"value":"# Hello world"}}},"text/plain":{"schema":{"type":"string","maxLength":1048576}},"application/json":{"schema":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/PublishJsonBody"}]}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PublishJsonBody"}}}},"responses":{"201":{"description":"Page published.","headers":{"Location":{"schema":{"type":"string","format":"uri"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishResponse"}},"text/plain":{"schema":{"type":"string","format":"uri"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"Request envelope or Markdown exceeds its size limit."},"415":{"description":"Multipart upload is not supported."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/openapi.json":{"get":{"tags":["Discovery"],"operationId":"getOpenApiSpec","summary":"Get OpenAPI specification","security":[],"responses":{"200":{"description":"OpenAPI 3.1 specification.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/openapi.json":{"get":{"tags":["Discovery"],"operationId":"getRootOpenApiSpec","summary":"Get OpenAPI specification","security":[],"responses":{"200":{"description":"OpenAPI 3.1 specification.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/pricing.json":{"get":{"tags":["Featured promotions"],"operationId":"getPricing","summary":"Get featured-promotion pricing","security":[],"responses":{"200":{"description":"Machine-readable featured pricing.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/featured/validate":{"post":{"tags":["Featured promotions"],"operationId":"validateFeaturedPurchase","summary":"Validate a featured promotion request","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedValidationRequest"}}}},"responses":{"200":{"description":"Request is valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedValidationResponse"}}}},"400":{"description":"Request is invalid; response includes issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedValidationResponse"}}}}}}},"/api/featured/checkout":{"post":{"tags":["Featured promotions"],"operationId":"createStripeFeaturedCheckout","summary":"Create a Stripe checkout for a featured promotion","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedCheckoutRequest"}}}},"responses":{"200":{"description":"Checkout created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedCheckoutResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/featured/purchase/week":{"get":{"tags":["Featured promotions"],"operationId":"getx402FeaturedQuoteWeek","summary":"Get x402 week purchase quote","security":[],"responses":{"200":{"description":"Quote and offer metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticQuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}},"post":{"tags":["Featured promotions"],"operationId":"createx402FeaturedPurchaseWeek","summary":"Create a paid x402 week featured-promotion request","description":"Without payment credentials, returns HTTP 402 with x402 payment challenge headers. Retry with x402 payment credential headers after payment.","security":[{"X402Payment":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"9.00","description":"Featured week promotion on markdown.page."},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseRequest"}}}},"responses":{"201":{"description":"Paid request recorded for admin review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Payment required.","headers":{"Payment-Required":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"}}}},"409":{"$ref":"#/components/responses/Conflict"},"501":{"description":"x402 payments are not configured."}}}},"/api/featured/mpp/purchase/week":{"get":{"tags":["Featured promotions"],"operationId":"getMPPFeaturedQuoteWeek","summary":"Get MPP week purchase quote","security":[],"responses":{"200":{"description":"Quote and offer metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticQuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}},"post":{"tags":["Featured promotions"],"operationId":"createMPPFeaturedPurchaseWeek","summary":"Create a paid MPP week featured-promotion request","description":"Without payment credentials, returns HTTP 402 with an MPP WWW-Authenticate challenge. Retry with Authorization: Payment ... after payment.","security":[{"MppPayment":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"9.00","description":"Featured week promotion on markdown.page."},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000b9537d11c60e8b50"}}],"offers":[{"amount":"9000000","currency":"0x20c000000000000000000b9537d11c60e8b50","description":"Featured week promotion on markdown.page.","intent":"charge","method":"tempo"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseRequest"}}}},"responses":{"201":{"description":"Paid request recorded for admin review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Payment required.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"}}}},"409":{"$ref":"#/components/responses/Conflict"},"501":{"description":"MPP payments are not configured."}}}},"/api/featured/purchase/month":{"get":{"tags":["Featured promotions"],"operationId":"getx402FeaturedQuoteMonth","summary":"Get x402 month purchase quote","security":[],"responses":{"200":{"description":"Quote and offer metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticQuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}},"post":{"tags":["Featured promotions"],"operationId":"createx402FeaturedPurchaseMonth","summary":"Create a paid x402 month featured-promotion request","description":"Without payment credentials, returns HTTP 402 with x402 payment challenge headers. Retry with x402 payment credential headers after payment.","security":[{"X402Payment":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"29.00","description":"Featured month promotion on markdown.page."},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseRequest"}}}},"responses":{"201":{"description":"Paid request recorded for admin review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Payment required.","headers":{"Payment-Required":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"}}}},"409":{"$ref":"#/components/responses/Conflict"},"501":{"description":"x402 payments are not configured."}}}},"/api/featured/mpp/purchase/month":{"get":{"tags":["Featured promotions"],"operationId":"getMPPFeaturedQuoteMonth","summary":"Get MPP month purchase quote","security":[],"responses":{"200":{"description":"Quote and offer metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticQuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}},"post":{"tags":["Featured promotions"],"operationId":"createMPPFeaturedPurchaseMonth","summary":"Create a paid MPP month featured-promotion request","description":"Without payment credentials, returns HTTP 402 with an MPP WWW-Authenticate challenge. Retry with Authorization: Payment ... after payment.","security":[{"MppPayment":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"29.00","description":"Featured month promotion on markdown.page."},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000b9537d11c60e8b50"}}],"offers":[{"amount":"29000000","currency":"0x20c000000000000000000b9537d11c60e8b50","description":"Featured month promotion on markdown.page.","intent":"charge","method":"tempo"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseRequest"}}}},"responses":{"201":{"description":"Paid request recorded for admin review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Payment required.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"}}}},"409":{"$ref":"#/components/responses/Conflict"},"501":{"description":"MPP payments are not configured."}}}},"/api/featured/purchase/quarter":{"get":{"tags":["Featured promotions"],"operationId":"getx402FeaturedQuoteQuarter","summary":"Get x402 quarter purchase quote","security":[],"responses":{"200":{"description":"Quote and offer metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticQuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}},"post":{"tags":["Featured promotions"],"operationId":"createx402FeaturedPurchaseQuarter","summary":"Create a paid x402 quarter featured-promotion request","description":"Without payment credentials, returns HTTP 402 with x402 payment challenge headers. Retry with x402 payment credential headers after payment.","security":[{"X402Payment":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"79.00","description":"Featured quarter promotion on markdown.page."},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseRequest"}}}},"responses":{"201":{"description":"Paid request recorded for admin review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Payment required.","headers":{"Payment-Required":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"}}}},"409":{"$ref":"#/components/responses/Conflict"},"501":{"description":"x402 payments are not configured."}}}},"/api/featured/mpp/purchase/quarter":{"get":{"tags":["Featured promotions"],"operationId":"getMPPFeaturedQuoteQuarter","summary":"Get MPP quarter purchase quote","security":[],"responses":{"200":{"description":"Quote and offer metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticQuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}},"post":{"tags":["Featured promotions"],"operationId":"createMPPFeaturedPurchaseQuarter","summary":"Create a paid MPP quarter featured-promotion request","description":"Without payment credentials, returns HTTP 402 with an MPP WWW-Authenticate challenge. Retry with Authorization: Payment ... after payment.","security":[{"MppPayment":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"79.00","description":"Featured quarter promotion on markdown.page."},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000b9537d11c60e8b50"}}],"offers":[{"amount":"79000000","currency":"0x20c000000000000000000b9537d11c60e8b50","description":"Featured quarter promotion on markdown.page.","intent":"charge","method":"tempo"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseRequest"}}}},"responses":{"201":{"description":"Paid request recorded for admin review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticPurchaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Payment required.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"}}}},"409":{"$ref":"#/components/responses/Conflict"},"501":{"description":"MPP payments are not configured."}}}},"/api/featured/purchases/{id}":{"get":{"tags":["Featured promotions"],"operationId":"getFeaturedPurchaseStatus","summary":"Get featured-purchase status","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Purchase status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedPurchaseStatus"}}}},"404":{"description":"Purchase not found."}}}},"/api/report":{"post":{"tags":["Moderation"],"operationId":"reportPage","summary":"Report a public page","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"}}}},"responses":{"201":{"description":"Report recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Page not found."},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"MppPayment":{"type":"http","scheme":"payment","description":"MPP credential returned after satisfying the WWW-Authenticate: Payment challenge."},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 payment credential. Legacy clients may send X-Payment."}},"responses":{"BadRequest":{"description":"Invalid request."},"Forbidden":{"description":"Forbidden."},"Conflict":{"description":"Conflicting slug, payment, or state."},"RateLimited":{"description":"Rate limit exceeded."},"ServerError":{"description":"Server error."}},"schemas":{"PublishJsonBody":{"type":"object","properties":{"markdown":{"type":"string"},"content":{"type":"string"},"text":{"type":"string"},"body":{"type":"string"}},"additionalProperties":true},"PublishResponse":{"type":"object","properties":{"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"raw_url":{"type":"string","format":"uri"}},"required":["slug","url","raw_url"]},"FeaturedValidationRequest":{"type":"object","properties":{"plan":{"type":"string","enum":["week","month","quarter"]},"articleUrl":{"type":"string"},"pageId":{"type":"string"},"featuredSlug":{"type":"string","pattern":"^[a-z0-9-]+$"}},"required":["featuredSlug"]},"FeaturedValidationResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"issues":{"type":"array","items":{"type":"string"}},"articleExists":{"type":"boolean"},"slugAvailable":{"type":"boolean"},"offer":{"type":"object"},"reviewCriteria":{"type":"array","items":{"type":"string"}}},"required":["ok","issues","articleExists","slugAvailable","offer"]},"FeaturedCheckoutRequest":{"allOf":[{"$ref":"#/components/schemas/FeaturedValidationRequest"},{"type":"object","properties":{"email":{"type":"string","format":"email"},"ui":{"type":"string","enum":["embedded","hosted"]},"returnPath":{"type":"string"}},"required":["plan"]}]},"FeaturedCheckoutResponse":{"oneOf":[{"type":"object","properties":{"clientSecret":{"type":"string"},"purchaseId":{"type":"string"},"publishableKey":{"type":"string"}},"required":["clientSecret","purchaseId","publishableKey"]},{"type":"object","properties":{"checkoutUrl":{"type":"string","format":"uri"},"purchaseId":{"type":"string"}},"required":["checkoutUrl","purchaseId"]}]},"AgenticPurchaseRequest":{"type":"object","properties":{"articleUrl":{"type":"string","format":"uri","description":"Public markdown.page URL for an existing page."},"pageId":{"type":"string","pattern":"^[A-Za-z0-9_-]{4,64}$","description":"ID of an existing markdown.page page."},"featuredSlug":{"type":"string","pattern":"^[a-z0-9-]+$"},"contact":{"type":"string"},"email":{"type":"string","format":"email"},"requestId":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"}},"required":["featuredSlug"],"anyOf":[{"required":["articleUrl"]},{"required":["pageId"]}],"example":{"pageId":"replace-with-existing-page-id","featuredSlug":"my-featured-page","requestId":"agent-request-001"}},"AgenticQuoteResponse":{"type":"object","properties":{"rail":{"type":"string","enum":["x402","mpp"]},"offer":{"type":"object"},"docs":{"type":"string"},"post_for_payment":{"type":"boolean"}},"required":["rail","offer","docs","post_for_payment"]},"PaymentRequiredResponse":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}}},"AgenticPurchaseResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"id":{"type":"string"},"provider":{"type":"string","enum":["x402","mpp"]},"status":{"type":"string"},"pageId":{"type":"string"},"featuredSlug":{"type":"string"},"plan":{"type":"string","enum":["week","month","quarter"]},"durationDays":{"type":"integer"},"approvalRequired":{"type":"boolean"}},"required":["ok","id","provider","status","pageId","featuredSlug","plan","durationDays","approvalRequired"]},"FeaturedPurchaseStatus":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"pageId":{"type":"string"},"articleSlug":{"type":"string"},"featuredSlug":{"type":"string"},"plan":{"type":"string"},"durationDays":{"type":"integer"},"amountTotal":{"type":["integer","null"]},"currency":{"type":["string","null"]},"paidAt":{"type":["integer","null"]},"approvedAt":{"type":["integer","null"]},"launchedAt":{"type":["integer","null"]},"expiresAt":{"type":["integer","null"]},"rejectedAt":{"type":["integer","null"]},"rejectionReason":{"type":["string","null"]},"approvalRequired":{"type":"boolean"},"reviewSla":{"type":"string"},"refundPolicy":{"type":"string"},"refundStatus":{"type":"string"},"refundedAt":{"type":["integer","null"]}}},"ReportRequest":{"type":"object","properties":{"slug":{"type":"string"},"categories":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","enum":["spam","illegal","harassment","phishing","other"]}},"comment":{"type":"string","maxLength":500}},"required":["slug","categories"]}}}}