Skip to main content

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.

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

HeaderRequiredValue
AuthorizationYesBearer <ACCESS_TOKEN>
Content-TypeYesapplication/json
box-versionYes2026.0

​
Request body

All fields are required.
FieldTypeConstraintsDescription
contentstringMax 1 MBThe Markdown content to convert into a Box Note.
content_formatstringMust be "markdown"The format of the input content.
parentobjectMust contain idThe destination folder in Box.
parent.idstringValid Box folder IDThe ID of the target parent folder.
namestring—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 statusDescriptionCommon cause
400 Bad RequestMalformed request bodyMissing required fields, invalid content_format, or malformed JSON.
403 ForbiddenInsufficient permissionsThe authenticated user does not have upload permissions for the target folder.
404 Not FoundFolder not foundThe parent.id does not correspond to an existing folder.
409 ConflictName collisionA file with the same name already exists in the target folder.
422 Unprocessable EntityValidation failureThe request is syntactically valid but cannot be processed. For example, the user’s storage quota is exceeded.
5xx Server ErrorInternal errorAn 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 -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"
     }'

​
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

The maximum content size is 1 MB. For larger documents, consider splitting content across multiple notes or trimming unnecessary sections before conversion.
Choose descriptive note names that make the content easy to find in Box. Avoid generic names like “Note 1” or “Untitled”.
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.
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.