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を使います。表示期限は無期限、タイトルは本文内の最初の見出し、パスワードなしで作成されます。

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
  }'

レスポンス

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

{
  "slug": "AbCdEf1234567890",
  "publicUrl": "https://markdown.bz/d/AbCdEf1234567890",
  "expiresAt": null
}

• slug: 共有ページを識別するURLセーフな文字列
• publicUrl: そのまま共有できる完成URL
• expiresAt: 有限期限ではISO 8601形式の日時、無期限ではnull

エラー

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

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

• 400: JSONまたは入力値が不正
• 413: Markdownまたはリクエストサイズが上限超過
• 415: Content-Typeが未対応
• 429: 作成回数の上限超過。Retry-Afterヘッダーを参照
• 500 / 503: 一時的なサーバーエラー

制限と注意事項

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

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