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

前提条件

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

リクエスト

ヘッダー

リクエスト本文

すべてのフィールドが必須です。

リクエストの例

レスポンス

成功 (201 Created)

成功レスポンスには、新しく作成された.boxnoteファイルのファイルタイプとBoxファイルIDが含まれます。
このレスポンスは意図的に最小限の内容となっています。ファイルの完全なメタデータ (所有者、タイムスタンプ、サイズなど) を取得するには、エンドポイントに対してフォローアップコールを実行してください。

エラー

このAPIでは標準のHTTPエラーコードが使用されます。エラーはすべてBoxのHttpErrorモデルに準拠します。
変換に関する警告 (サポートされていないマークダウン要素など) は、変換中に削除または簡略化されます。サーバー側でログに記録され、APIレスポンスとしては返されません。

マークダウンのサポート

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

コード例

エラー処理

名前の競合 (409)

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

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

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

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

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

ベストプラクティス

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