> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

> POST /notes/convertエンドポイントを使用して、マークダウンコンテンツをBox Noteに変換するための詳細ガイド。

# マークダウンをBox Noteに変換

export const RelatedLinks = ({title, items = []}) => {
  const getBadgeClass = badge => {
    if (!badge) return "badge-default";
    const badgeType = badge.toLowerCase().replace(/\s+/g, "-");
    return `badge-${badge === "ガイド" ? "guide" : badgeType}`;
  };
  if (!items || items.length === 0) {
    return null;
  }
  return <div className="my-8">
      {}
      <h3 className="text-sm font-bold uppercase tracking-wider mb-4">{title}</h3>

      {}
      <div className="flex flex-col gap-3">
        {items.map((item, index) => <a key={index} href={item.href} className="py-2 px-3 rounded related_link hover:bg-[#f2f2f2] dark:hover:bg-[#111827] flex items-center gap-3 group no-underline hover:no-underline border-b-0">
            {}
            <span className={`px-2 py-1 rounded-full text-xs font-semibold uppercase tracking-wide flex-shrink-0 ${getBadgeClass(item.badge)}`}>
              {item.badge}
            </span>

            {}
            <span className="text-base">{item.label}</span>
          </a>)}
      </div>
    </div>;
};

export const Link = ({href, children, className, ...props}) => {
  const localizedHref = localizeLink(href);
  return <a href={localizedHref} className={className} {...props}>
      {children}
    </a>;
};

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

## 前提条件

始める前に、以下が揃っていることを確認してください。

* ターゲットフォルダへのファイルアップロード権限を持つ有効なアクセストークン。
* リクエストに含まれた`box-version: 2026.0`ヘッダー。
* Box内のターゲット親フォルダのフォルダID。

セットアップの手順については、<Link href="/guides/box-notes/get-started">使い方</Link>ガイドを参照してください。

## リクエスト

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

### ヘッダー

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

### リクエスト本文

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

| フィールド            | 型        | 制約                | 説明                         |
| ---------------- | -------- | ----------------- | -------------------------- |
| `content`        | `string` | 最大1 MB            | Box Noteに変換するマークダウンコンテンツ。  |
| `content_format` | `string` | 必ず`"markdown"`と指定 | 入力コンテンツの形式。                |
| `parent`         | `object` | 必ず`id`を含める        | Box内の宛先フォルダ。               |
| `parent.id`      | `string` | 有効なBoxフォルダID      | ターゲット親フォルダのID。             |
| `name`           | `string` | —                 | 生成される`.boxnote`ファイルのファイル名。 |

### リクエストの例

```sh theme={null}
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が含まれます。

```json theme={null}
{
  "type": "file",
  "id": "1234567890"
}
```

このレスポンスは意図的に最小限の内容となっています。ファイルの完全なメタデータ (所有者、タイムスタンプ、サイズなど) を取得するには、<Link href="/reference/get-files-id">ファイルの取得</Link>エンドポイントに対してフォローアップコールを実行してください。

```sh theme={null}
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`         | 内部エラー            | 変換またはアップロード中にエラーが発生しました。しばらくしてからやりなおしてください。                              |

<Note>
  変換に関する警告 (サポートされていないマークダウン要素など) は、変換中に削除または簡略化されます。サーバー側でログに記録され、APIレスポンスとしては返されません。
</Note>

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

このAPIは、標準的なマークダウン構文をBox Notes形式に変換します。サポートされる要素は以下の通りです。

* **見出し** (`#`、`##`、`###`など)
* **太字** (`**text**`) と*斜体* (`*text*`)
* **順序なしリスト** (`-`または`*`)
* **順序付きリスト** (`1.`、`2.`など)
* **リンク** (`[text](url)`)
* **コードブロック** (前後を3連のバッククォートで囲む)
* **インラインコード** (バッククォート)
* **ブロック引用** (`>`)
* **水平方向の罫線** (`---`)

<Tip>
  Box Notes形式でサポートされていない要素がマークダウンに含まれている場合、変換時にそのような要素が簡略化または省略されることがあります。変換自体は正常に完了します。警告はサーバー側にのみ記録されます。
</Tip>

## コード例

<CodeGroup>
  ```sh cURL theme={null}
  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"
       }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.box.com/2.0/notes/convert"

  headers = {
      "box-version": "2026.0",
      "Authorization": "Bearer <ACCESS_TOKEN>",
      "Content-Type": "application/json",
  }

  payload = {
      "content": (
          "# Project Update\n\n"
          "## Summary\n\n"
          "Sprint 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",
  }

  response = requests.post(url, json=payload, headers=headers)

  if response.status_code == 201:
      note = response.json()
      print(f"Note created with file ID: {note['id']}")
  else:
      print(f"Error {response.status_code}: {response.json()}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.box.com/2.0/notes/convert", {
    method: "POST",
    headers: {
      "box-version": "2026.0",
      Authorization: "Bearer <ACCESS_TOKEN>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: [
        "# Project Update",
        "",
        "## Summary",
        "",
        "Sprint completed on schedule.",
        "",
        "## Tasks",
        "",
        "- [x] Design review",
        "- [x] Backend implementation",
        "- [ ] QA sign-off",
        "",
        "> Next sprint starts Monday.",
      ].join("\n"),
      content_format: "markdown",
      parent: { id: "987654321" },
      name: "Sprint 14 Update",
    }),
  });

  if (response.status === 201) {
    const note = await response.json();
    console.log(`Note created with file ID: ${note.id}`);
  } else {
    const error = await response.json();
    console.error(`Error ${response.status}:`, error);
  }
  ```
</CodeGroup>

## エラー処理

### 名前の競合 (409)

ターゲットフォルダに同じ名前のファイルがすでに存在している場合、APIは`409 Conflict`エラーを返します。これを解決するには、以下の操作を行います。

* メモに対して別の`name`を選択します。
* 別の`parent.id` (ターゲットフォルダ) を指定します。
* 既存のファイルを削除するか名前を変更して、再試行します。

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

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

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

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

## ベストプラクティス

<AccordionGroup>
  <Accordion title="コンテンツのサイズ上限を超えないようにする">
    `content`の最大サイズは1 MBです。それ以上のサイズのドキュメントについては、コンテンツを複数のメモに分割するか、変換前に不要な部分を削除することを検討してください。
  </Accordion>

  <Accordion title="意味のある名前を使用する">
    Box内でコンテンツを簡単に見つけられるように、具体的な名前を付けます。「メモ1」や「無題」といった汎用的な名前は避けてください。
  </Accordion>

  <Accordion title="変換時間を調整する">
    大規模または複雑なマークダウンコンテンツでは、変換に30秒程度の時間がかかることがあります。所要時間に応じてHTTPクライアントのタイムアウト時間を調整し、一過性の`5xx`エラーが発生した際の再試行ロジックを実装してください。
  </Accordion>

  <Accordion title="作成後にメタデータを取得する">
    作成時のレスポンスには、`type`と`id`のみが含まれます。その他のファイルメタデータ (タイムスタンプ、サイズ、所有者) が必要な場合は、`GET /2.0/files/{file_id}`にフォローアップコールを実行してください。
  </Accordion>
</AccordionGroup>

<RelatedLinks
  title="関連するガイド"
  items={[
{ label: translate("Get started with Box Notes API"), href: "/guides/box-notes/get-started", badge: "GUIDE" },
{ label: translate("Use cases"), href: "/guides/box-notes/use-cases", badge: "GUIDE" },
{ label: translate("Box API versioning"), href: "/guides/api-calls/api-versioning-strategy", badge: "GUIDE" }
]}
/>