> ## 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.

# Convert Markdown to Box Note

> Detailed guide for converting Markdown content to a Box Note using the POST /notes/convert endpoint.

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 = href;
  return <a href={localizedHref} className={className} {...props}>
      {children}
    </a>;
};

The `POST /2.0/notes/convert` endpoint converts Markdown content to a
Box Note (`.boxnote`) and uploads it to a specified folder in one
atomic operation. The note is either fully created or an error is
returned.

## Prerequisites

Before you start, make sure you have:

* A valid access token with file upload permissions for the target
  folder.
* The `box-version: 2026.0` header included in your request.
* The folder ID of the target parent folder in Box.

For setup instructions, see the
<Link href="/guides/box-notes/get-started">getting started</Link>
guide.

## Request

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

### Headers

| Header          | Required | Value                   |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <ACCESS_TOKEN>` |
| `Content-Type`  | Yes      | `application/json`      |
| `box-version`   | Yes      | `2026.0`                |

### Request body

All fields are required.

| Field            | Type     | Constraints          | Description                                      |
| ---------------- | -------- | -------------------- | ------------------------------------------------ |
| `content`        | `string` | Max 1 MB             | The Markdown content to convert into a Box Note. |
| `content_format` | `string` | Must be `"markdown"` | The format of the input content.                 |
| `parent`         | `object` | Must contain `id`    | The destination folder in Box.                   |
| `parent.id`      | `string` | Valid Box folder ID  | The ID of the target parent folder.              |
| `name`           | `string` | —                    | The filename for the resulting `.boxnote` file.  |

### Example request

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

## Response

### Success (`201 Created`)

A successful response contains the file type and the Box file ID of
the newly created `.boxnote` file.

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

The response is intentionally minimal. To retrieve full file metadata
(owner, timestamps, size, and more), make a follow-up call to the
<Link href="/reference/get-files-id">Get file</Link> endpoint:

```sh theme={null}
curl -L 'https://api.box.com/2.0/files/1234567890' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

### Errors

The API uses standard HTTP error codes. All errors follow the Box
`HttpError` model.

| HTTP status                | Description              | Common cause                                                                                                   |
| -------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`          | Malformed request body   | Missing required fields, invalid `content_format`, or malformed JSON.                                          |
| `403 Forbidden`            | Insufficient permissions | The authenticated user does not have upload permissions for the target folder.                                 |
| `404 Not Found`            | Folder not found         | The `parent.id` does not correspond to an existing folder.                                                     |
| `409 Conflict`             | Name collision           | A file with the same name already exists in the target folder.                                                 |
| `422 Unprocessable Entity` | Validation failure       | The request is syntactically valid but cannot be processed. For example, the user's storage quota is exceeded. |
| `5xx Server Error`         | Internal error           | An error occurred during conversion or upload. Retry after a brief delay.                                      |

<Note>
  Conversion warnings, such as unsupported Markdown elements that are
  dropped or simplified during conversion, are logged server-side and
  are not returned in the API response.
</Note>

## Markdown support

The API converts standard Markdown syntax into Box Notes format.
Supported elements include:

* **Headings** (`#`, `##`, `###`, etc.)
* **Bold** (`**text**`) and *italic* (`*text*`)
* **Unordered lists** (`-` or `*`)
* **Ordered lists** (`1.`, `2.`, etc.)
* **Links** (`[text](url)`)
* **Code blocks** (fenced with triple backticks)
* **Inline code** (backticks)
* **Blockquotes** (`>`)
* **Horizontal rules** (`---`)

<Tip>
  If your Markdown contains elements that are not supported in Box
  Notes format, those elements may be simplified or omitted during
  conversion. The conversion still succeeds. Warnings are logged
  server-side only.
</Tip>

## Code examples

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

## Handling errors

### Name conflicts (409)

If a file with the same name already exists in the target folder,
the API returns a `409 Conflict` error. To resolve this:

* Choose a different `name` for the note.
* Specify a different `parent.id` (target folder).
* Delete or rename the existing file before retrying.

### Storage quota exceeded (422)

If the user's storage quota has been reached, the API returns a
`422 Unprocessable Entity` error. Free up space in the Box account
or contact an admin to increase the storage allocation.

### Permission errors (403)

Verify that the authenticated user has **Editor** or **Co-Owner**
access to the target folder. **Viewer** and **Previewer** roles do
not have upload permissions.

## Best practices

<AccordionGroup>
  <Accordion title="Keep content within size limits">
    The maximum `content` size is 1 MB. For larger documents,
    consider splitting content across multiple notes or trimming
    unnecessary sections before conversion.
  </Accordion>

  <Accordion title="Use meaningful names">
    Choose descriptive note names that make the content easy to find
    in Box. Avoid generic names like "Note 1" or "Untitled".
  </Accordion>

  <Accordion title="Handle the conversion time">
    Conversion can take up to 30 seconds for large or complex
    Markdown content. Configure your HTTP client timeout accordingly
    and implement retry logic for transient `5xx` errors.
  </Accordion>

  <Accordion title="Retrieve metadata after creation">
    The create response only includes `type` and `id`. If you need
    additional file metadata (timestamps, size, owner), make a
    follow-up `GET /2.0/files/{file_id}` call.
  </Accordion>
</AccordionGroup>

<RelatedLinks
  title="RELATED GUIDES"
  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" }
]}
/>