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

# Box Notes API

> Programmatically create Box Notes from Markdown content using the Box Notes API.

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 Box Notes API lets you programmatically convert Markdown content
into native Box Notes (`.boxnote` format) and upload them directly to
the Box filesystem in a single API call. The API handles Markdown
to ProseMirror conversion, preflight validation, and file upload
behind the scenes, so you don't need to construct `.boxnote` files
yourself.

<Note>
  The Box Notes API currently supports creating notes from Markdown
  content only. Reading, updating, listing, and deleting notes are
  managed through the existing
  <Link href="/reference/get-files-id">Box Files API</Link>.
  Additional input formats and operations may be added in the future.
</Note>

## How it works

When you send a request to `POST /2.0/notes/convert`, the API
performs the following steps:

<Steps>
  <Step title="Validate the request">
    The API validates the request body, checking for required
    fields, content size limits, and a valid `content_format`.
  </Step>

  <Step title="Run a preflight check">
    A preflight file-upload check verifies the caller's
    permissions, storage quota, and naming conflicts in the
    target folder.
  </Step>

  <Step title="Convert the content">
    The Markdown content is converted into a Box Notes ProseMirror
    document in `.boxnote` format.
  </Step>

  <Step title="Upload the file">
    The resulting `.boxnote` file is uploaded to the specified
    parent folder.
  </Step>

  <Step title="Return the result">
    The API returns `201 Created` with the new file's `type` and
    `id`.
  </Step>
</Steps>

## Box Notes API version

The Box Notes API is available starting in Box API version `2026.0`.
All API requests to Box Notes API endpoints must include the
`box-version` header set to `2026.0`.

For more details, see
<Link href="/guides/api-calls/api-versioning-strategy">Box API versioning</Link>.

## Supported operations

| Operation        | Supported | Details                                                                     |
| ---------------- | --------- | --------------------------------------------------------------------------- |
| Create (convert) | Yes       | `POST /2.0/notes/convert`                                                   |
| Read             | No        | Use `GET /2.0/files/{file_id}` after creation                               |
| Update           | No        | Not supported in this API                                                   |
| Delete           | No        | Use `DELETE /2.0/files/{file_id}`                                           |
| List             | No        | Use the <Link href="/reference/get-folders-id-items">Box Folders API</Link> |

## Permissions

The Box Notes API uses existing Box file upload permissions. No new
OAuth scopes are required. If the authenticated user has permission
to upload files to the target folder, they can create notes using
this API.

## Limitations

| Constraint              | Limit                          |
| ----------------------- | ------------------------------ |
| Maximum content size    | 1 MB                           |
| Supported input formats | Markdown only                  |
| Maximum conversion time | Up to 30 seconds per request   |
| Response payload        | Minimal - `type` and `id` only |

<Tip>
  To retrieve full file metadata after creating a note, call
  `GET /2.0/files/{file_id}` with the returned `id`.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Get started" icon="rocket" href="/guides/box-notes/get-started">
    Set up authentication and create your first Box Note from
    Markdown.
  </Card>

  <Card title="Convert Markdown to Box Note" icon="file-lines" href="/guides/box-notes/convert-markdown">
    Detailed guide covering request parameters, error handling,
    and code examples.
  </Card>

  <Card title="Use cases" icon="lightbulb" href="/guides/box-notes/use-cases">
    Common scenarios for AI-generated notes, automated reports,
    and third-party content import.
  </Card>
</CardGroup>

<RelatedLinks
  title="RELATED APIS"
  items={[
{ label: translate("Convert Markdown to Box Note"), href: "/reference/v2026.0/post-notes-convert", badge: "POST" },
{ label: translate("Get file information"), href: "/reference/get-files-id", badge: "GET" },
{ label: translate("Upload file"), href: "/reference/post-files-content", badge: "POST" }
]}
/>