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 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.
The Box Notes API currently supports creating notes from Markdown content only. Reading, updating, listing, and deleting notes are managed through the existing . Additional input formats and operations may be added in the future.

​
How it works

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

Validate the request

The API validates the request body, checking for required fields, content size limits, and a valid content_format.
2

Run a preflight check

A preflight file-upload check verifies the caller’s permissions, storage quota, and naming conflicts in the target folder.
3

Convert the content

The Markdown content is converted into a Box Notes ProseMirror document in .boxnote format.
4

Upload the file

The resulting .boxnote file is uploaded to the specified parent folder.
5

Return the result

The API returns 201 Created with the new file’s type and id.

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

​
Supported operations

OperationSupportedDetails
Create (convert)YesPOST /2.0/notes/convert
ReadNoUse GET /2.0/files/{file_id} after creation
UpdateNoNot supported in this API
DeleteNoUse DELETE /2.0/files/{file_id}
ListNoUse the

​
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

ConstraintLimit
Maximum content size1 MB
Supported input formatsMarkdown only
Maximum conversion timeUp to 30 seconds per request
Response payloadMinimal - type and id only
To retrieve full file metadata after creating a note, call GET /2.0/files/{file_id} with the returned id.

​
Next steps

Get started

Set up authentication and create your first Box Note from Markdown.

Convert Markdown to Box Note

Detailed guide covering request parameters, error handling, and code examples.

Use cases

Common scenarios for AI-generated notes, automated reports, and third-party content import.