Convert Markdown to Box Note

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

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

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.

{
  "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 endpoint:

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.

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.

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

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.

Code examples

cURL

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

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()}")

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);
}

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

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.

Use meaningful names

Choose descriptive note names that make the content easy to find in Box. Avoid generic names like “Note 1” or “Untitled”.

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.

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.