[] markdown.page

API

All endpoints are under https://markdown.page/api/.

The API is intentionally forgiving: if you can send text, you can publish markdown. No account, API key, or special header is required.

Publish a page

POST /api/publish
POST /api also works as a short alias.

Send markdown in the request body and get back a permanent URL. The markdown string may be up to 1 MB.

The easiest version works with no explicit content type:

curl https://markdown.page/api/publish --data-binary '# Hello world'

Publish a file:

curl https://markdown.page/api/publish --data-binary @README.md

A plain curl -d also works, even though curl labels it as form data:

curl https://markdown.page/api/publish -d '# Hello world'

Accepted request bodies:

  • raw markdown text, with any content type or no content type
  • text/markdown or text/plain
  • JSON string: "# Hello"
  • JSON object with one of markdown, content, text, or body
  • URL-encoded form with one of markdown, content, text, or body

JSON example:

curl https://markdown.page/api/publish \
  -H 'Content-Type: application/json' \
  -d '{"markdown":"# Hello world"}'

Returns 201 with a Location header and JSON containing slug, url, and raw_url:

{
  "slug": "a3x9k2b7",
  "url": "https://markdown.page/a3x9k2b7",
  "raw_url": "https://markdown.page/a3x9k2b7/raw"
}

If you explicitly ask for plain text, the response body is just the published URL:

curl -H 'Accept: text/plain' https://markdown.page/api/publish --data-binary @README.md

Errors are returned as JSON by default:

{
  "error": "empty_body",
  "message": "Send markdown in the request body.",
  "example": "curl https://markdown.page/api/publish --data-binary '# Hello'"
}

Common statuses:

  • 400 — empty body, invalid JSON, binary body, exceeds 1 MB, or markdown fails validation
  • 403 — cross-origin browser request blocked
  • 415 — multipart upload; send raw markdown instead
  • 429 — fair-use rate limit exceeded
  • 500 — slug allocation failure

Machine-readable docs

GET /api returns human HTML by default.

Ask for JSON:

curl -H 'Accept: application/json' https://markdown.page/api

Ask for plain text:

curl -H 'Accept: text/plain' https://markdown.page/api

Get raw markdown

GET /{slug}/raw

Returns the original markdown source for a published page as text/plain; charset=utf-8. Returns 404 if the page doesn't exist.

Example:

curl https://markdown.page/a3x9k2b7/raw

Markdown rules

Standard markdown plus GFM: headings, bold, italic, strikethrough, lists, task lists, links, images, inline code, fenced code blocks, blockquotes, and tables. Images must use https:// or http:// URLs. Links support https://, http://, and mailto:. Raw HTML, custom CSS, and JavaScript are not accepted. Max document size is 1 MB.