APIドキュメント

Markdown本文を送信すると、ブラウザで閲覧できる無期限または期限付き共有ページを作成し、完成URLをJSONで返します。作成に認証は不要です。作成した共有は、同時に返る削除用トークンで後から削除できます。

概要

エンドポイントは POST https://markdown.bz/api/v1/documents です。APIのバージョンはURLのv1で固定しています。成功時は201 Createdを返し、レスポンス本文のpublicUrlとLocationヘッダーの両方で完成URLを取得できます。

機械可読な仕様はOpenAPI 3.1ドキュメントから取得できます。 コピーして実行できるCLI、curl、Node.js、GitHub Actionsの例は公式サンプルリポジトリで公開しています。

最短の使い方

Markdownファイルをそのまま送る場合はContent-Type: text/markdownを使います。表示期限は無期限、タイトルはfrontmatterのtitle（なければ本文内の最初の見出し）、パスワードなしで作成されます。

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

設定付きで公開

表示期限、タイトル、閲覧パスワード、検索公開、デザインのテンプレートを指定する場合はJSONで送信します。

curl --request POST 'https://markdown.bz/api/v1/documents' \
  --header 'Content-Type: application/json' \
  --data '{
    "markdown": "# APIから公開\n\nMarkdown本文です。",
    "title": "共有タイトル",
    "expiryDays": null,
    "allowIndexing": true,
    "theme": "business"
  }'

レスポンス

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": "削除用トークン（32文字）"
}

• slug: 共有ページを識別するURLセーフな文字列
• publicUrl: そのまま共有できる完成URL
• expiresAt: 有限期限ではISO 8601形式の日時、無期限ではnull
• deleteToken: この共有を削除するためのトークン。このレスポンスでしか取得できず、再発行もできません。共有URLとは別に、CIのsecretsなど人目に触れない場所へ保管してください

削除

作成時のdeleteTokenをAuthorization: Bearerヘッダーで送ると、その共有を削除できます。成功時は204 No Contentを返し、共有URLはすぐに閲覧できなくなります。削除は元に戻せません。

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

削除用トークンは、2026年9月23日の機能追加以降にAPIで作成した共有にだけ返ります。それより前に作成した共有で削除が必要な場合は、共有ページの「このページを報告」から連絡してください。

エラー

失敗時はHTTPステータスと、機械判定用のcodeを含むJSONを返します。

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "expiryDays はnull（無期限）、3、7、30、60、100のいずれかです"
  }
}

• 400: JSONまたは入力値が不正
• 401: 削除時にAuthorization: Bearerヘッダーがない、または形式が不正
• 403: 削除用トークンが一致しない
• 404: 削除対象の共有が存在しない、またはすでに削除済み
• 413: Markdownまたはリクエストサイズが上限超過
• 415: Content-Typeが未対応
• 429: 作成回数の上限超過（1分あたり、または1日あたり）。Retry-Afterヘッダーを参照
• 500 / 503: 一時的なサーバーエラー

制限と注意事項

• Markdown本文は最大1MBです。
• 同一送信元からの作成は1分あたり600回までです。Vercel FirewallがIP単位で判定します。
• 同一送信元（IPアドレス）から1日に作成できる共有は、ブラウザーからの作成と合わせて10件までで、日本時間の0時に戻ります。超えると429（RATE_LIMITED）を返し、Retry-Afterに0時までの秒数を入れます。この判定のため、IPアドレスはハッシュ化して保存します。
• API v1はローカル画像のアップロードに対応しません。外部画像URLはMarkdown内で参照できます。
• 共有URLは誰でもアクセスできますが、検索エンジンへの公開は既定で無効です。一般公開してよい場合だけallowIndexingを有効にしてください。
• 検索非公開は検索結果への掲載だけを制御します。URLを知っている人の閲覧や、チャット・SNSでのOGP・X（Twitter）Cardなどのリンクプレビューには影響しません。
• APIで作成した共有は、公開後の本文編集と期限延長ができません。修正時は新しく作成し、古い共有は削除用トークンで削除してください。
• 無期限は期限による自動削除を行わない設定であり、恒久的な保存を保証するものではありません。
• 個人情報、秘密情報、認証情報、長期保管が必要な文書には使用しないでください。

利用にあたっては利用規約とプライバシーポリシーも確認してください。