API docs

Send Markdown text and the API creates a share page that can be read in a browser, with or without an expiry, and returns its URL as JSON. No authentication is needed to create a share. You can delete it later with the delete token returned in the same response.

Overview

The endpoint is POST https://markdown.bz/api/v1/documents. The API version is fixed by v1 in the URL. On success, the API returns 201 Created, and you can get the finished URL from both publicUrl in the response body and the Location header.

A machine-readable specification is available as an OpenAPI 3.1 document. Copy-and-run examples for the CLI, curl, Node.js and GitHub Actions are published in the official examples repository.

Quick start

To send a Markdown file as is, use Content-Type: text/markdown. The share is created with no expiry and no password, and its title is taken from the frontmatter title (or the first heading in the text if there is none).

curl --request POST 'https://markdown.bz/api/v1/documents' \
  --header 'Content-Type: text/markdown; charset=utf-8' \
  --data-binary '@README.md'

Publish with options

To set the expiry, title, viewing password, search engine indexing or design template, send JSON.

curl --request POST 'https://markdown.bz/api/v1/documents' \
  --header 'Content-Type: application/json' \
  --data '{
    "markdown": "# Published via the API\n\nThis is the Markdown body.",
    "title": "Share title",
    "expiryDays": null,
    "allowIndexing": true,
    "theme": "business"
  }'

Response

HTTP/2 201 Created
Location: https://markdown.bz/d/AbCdEf1234567890
Content-Type: application/json

{
  "slug": "AbCdEf1234567890",
  "publicUrl": "https://markdown.bz/d/AbCdEf1234567890",
  "expiresAt": null,
  "deleteToken": "delete token (32 characters)"
}

• slug: A URL-safe string that identifies the share page
• publicUrl: The finished URL, ready to share as is
• expiresAt: For a share with an expiry, the expiry date and time in ISO 8601 format; null for no expiry
• deleteToken: A token for deleting this share. It is only returned in this response and cannot be reissued. Store it separately from the share URL, somewhere private such as your CI secrets

Delete

To delete a share, send its deleteToken (returned when the share was created) in an Authorization: Bearer header. On success, the API returns 204 No Content and the share URL immediately becomes unavailable. Deletion cannot be undone.

curl --request DELETE 'https://markdown.bz/api/v1/documents/AbCdEf1234567890' \
  --header "Authorization: Bearer $MARKDOWNBZ_DELETE_TOKEN"

Delete tokens are only returned for shares created with the API after the feature was added on September 23, 2026. To delete a share created before then, contact us through “Report this page” on the share page.

Errors

On failure, the API returns an HTTP status and JSON that includes a machine-readable code. The message for people is in Japanese by default; send Accept-Language: en to get it in English.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "expiryDays must be null (no expiry), 3, 7, 30, 60 or 100."
  }
}

• 400: Invalid JSON or input values
• 401: When deleting, the Authorization: Bearer header is missing or malformed
• 403: The delete token does not match
• 404: The share to delete does not exist or has already been deleted
• 413: The Markdown or the request exceeds the size limit
• 415: Unsupported Content-Type
• 429: Creation rate limit exceeded (per minute or per day). See the Retry-After header
• 500 / 503: Temporary server error

Limits and notes

• The Markdown text can be up to 1 MB.
• Each source can create up to 600 shares per minute. Vercel Firewall enforces this per IP address.
• Each source (IP address) can create up to 10 shares per day, including shares created in the browser, reset at midnight Japan time. Beyond that, the API returns 429 (RATE_LIMITED) with the seconds until midnight in Retry-After. To enforce this limit, the app stores a hash of the IP address.
• API v1 does not support uploading local images. You can reference external image URLs in the Markdown.
• Anyone with the share URL can open it, but search engine indexing is off by default. Enable allowIndexing only if the content is fine to share with the general public.
• Turning off indexing only keeps the share out of search results. It does not affect viewing by people who know the URL, or link previews such as OGP and X (Twitter) Cards in chats and on social media.
• Shares created with the API cannot be edited or have their expiry extended after publishing. To make changes, create a new share and delete the old one with its delete token.
• No expiry only means the share is not deleted automatically on an expiry date; it does not guarantee permanent storage.
• Do not use the API for personal or confidential information, credentials or documents that need long-term storage.

Before using the API, please also read the Terms of Service and Privacy Policy.