メインコンテンツへスキップ
POST /2.0/notes/convertエンドポイントは、1回の操作としてマークダウンコンテンツをBox Note (.boxnote) に変換し、指定したフォルダにアップロードします。メモが正常に作成されなかった場合、エラーが返されます。

​
前提条件

始める前に、以下が揃っていることを確認してください。
  • ターゲットフォルダへのファイルアップロード権限を持つ有効なアクセストークン。
  • リクエストに含まれたbox-version: 2026.0ヘッダー。
  • Box内のターゲット親フォルダのフォルダID。
セットアップの手順については、ガイドを参照してください。

​
リクエスト

POST https://api.box.com/2.0/notes/convert

​
ヘッダー

ヘッダー必須値
AuthorizationはいBearer <ACCESS_TOKEN>
Content-Typeはいapplication/json
box-versionはい2026.0

​
リクエスト本文

すべてのフィールドが必須です。
フィールド型制約説明
contentstring最大1 MBBox Noteに変換するマークダウンコンテンツ。
content_formatstring必ず"markdown"と指定入力コンテンツの形式。
parentobject必ずidを含めるBox内の宛先フォルダ。
parent.idstring有効なBoxフォルダIDターゲット親フォルダのID。
namestring—生成される.boxnoteファイルのファイル名。

​
リクエストの例

curl -L 'https://api.box.com/2.0/notes/convert' \
     -H 'box-version: 2026.0' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{
       "content": "# Meeting Notes\n\nAction items:\n- Follow up with team\n- Review proposal\n\n## Decisions\n\nWe agreed to proceed with **Option A**.",
       "content_format": "markdown",
       "parent": {
         "id": "123456789"
       },
       "name": "Q2 Meeting Notes"
     }'

​
レスポンス

​
成功 (201 Created)

成功レスポンスには、新しく作成された.boxnoteファイルのファイルタイプとBoxファイルIDが含まれます。 
{
  "type": "file",
  "id": "1234567890"
}
このレスポンスは意図的に最小限の内容となっています。ファイルの完全なメタデータ (所有者、タイムスタンプ、サイズなど) を取得するには、エンドポイントに対してフォローアップコールを実行してください。 
curl -L 'https://api.box.com/2.0/files/1234567890' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'

​
エラー

このAPIでは標準のHTTPエラーコードが使用されます。エラーはすべてBoxのHttpErrorモデルに準拠します。
HTTPステータス説明一般的な原因
400 Bad Requestリクエスト本文の形式が正しくない必須フィールドが欠落している、content_formatが無効、またはJSONの形式が正しくありません。
403 Forbidden権限の不足認証済みユーザーにターゲットフォルダに対するアップロード権限がありません。
404 Not Foundフォルダが見つからないparent.idが、既存のフォルダに適合していません。
409 Conflict名前の競合ターゲットフォルダに同名のファイルがすでに存在しています。
422 Unprocessable Entity検証の失敗リクエストは構文的には有効ですが、処理できません。たとえば、このリクエストによってユーザーに割り当てられたストレージ容量を超過する場合などです。
5xx Server Error内部エラー変換またはアップロード中にエラーが発生しました。しばらくしてからやりなおしてください。
変換に関する警告 (サポートされていないマークダウン要素など) は、変換中に削除または簡略化されます。サーバー側でログに記録され、APIレスポンスとしては返されません。

​
マークダウンのサポート

このAPIは、標準的なマークダウン構文をBox Notes形式に変換します。サポートされる要素は以下の通りです。
  • 見出し (#、##、###など)
  • 太字 (**text**) と斜体 (*text*)
  • 順序なしリスト (-または*)
  • 順序付きリスト (1.、2.など)
  • リンク ([text](url))
  • コードブロック (前後を3連のバッククォートで囲む)
  • インラインコード (バッククォート)
  • ブロック引用 (>)
  • 水平方向の罫線 (---)
Box Notes形式でサポートされていない要素がマークダウンに含まれている場合、変換時にそのような要素が簡略化または省略されることがあります。変換自体は正常に完了します。警告はサーバー側にのみ記録されます。

​
コード例

curl -L 'https://api.box.com/2.0/notes/convert' \
     -H 'box-version: 2026.0' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{
       "content": "# Project Update\n\n## Summary\n\nSprint completed on schedule.\n\n## Tasks\n\n- [x] Design review\n- [x] Backend implementation\n- [ ] QA sign-off\n\n> Next sprint starts Monday.",
       "content_format": "markdown",
       "parent": {
         "id": "987654321"
       },
       "name": "Sprint 14 Update"
     }'

​
エラー処理

​
名前の競合 (409)

ターゲットフォルダに同じ名前のファイルがすでに存在している場合、APIは409 Conflictエラーを返します。これを解決するには、以下の操作を行います。
  • メモに対して別のnameを選択します。
  • 別のparent.id (ターゲットフォルダ) を指定します。
  • 既存のファイルを削除するか名前を変更して、再試行します。

​
ストレージ容量の上限超過 (422)

ユーザーに割り当てられているストレージ容量の上限に達した場合、APIは422 Unprocessable Entityエラーを返します。Boxアカウントの空き容量を確保するか、管理者に連絡してストレージ容量の割り当てを増やしてもらいます。

​
権限に関するエラー (403)

認証済みユーザーが、ターゲットフォルダに対して編集者または共同所有者のアクセス権限を持っていることを確認してください。ビューアーおよびプレビューアーのロールには、アップロード権限がありません。

​
ベストプラクティス

contentの最大サイズは1 MBです。それ以上のサイズのドキュメントについては、コンテンツを複数のメモに分割するか、変換前に不要な部分を削除することを検討してください。
Box内でコンテンツを簡単に見つけられるように、具体的な名前を付けます。「メモ1」や「無題」といった汎用的な名前は避けてください。
大規模または複雑なマークダウンコンテンツでは、変換に30秒程度の時間がかかることがあります。所要時間に応じてHTTPクライアントのタイムアウト時間を調整し、一過性の5xxエラーが発生した際の再試行ロジックを実装してください。
作成時のレスポンスには、typeとidのみが含まれます。その他のファイルメタデータ (タイムスタンプ、サイズ、所有者) が必要な場合は、GET /2.0/files/{file_id}にフォローアップコールを実行してください。
最終更新日 2026年7月1日