Get started with Box Notes API

This guide walks you through creating your first Box Note from Markdown using the Box Notes API. By the end, you have a .boxnote file in your Box account created from a single API call.

Prerequisites

Before you begin, make sure you have:

A Box account with file upload permissions.
A configured in the Box Developer Console.
A valid access token for authentication (OAuth 2.0 or JWT).
A target folder ID in Box where you want to create the note.

The Box Notes API requires API version 2026.0. All requests must include the box-version: 2026.0 header.

Step 1: Generate an access token

You need an access token to authenticate your API calls. To generate a developer token for testing:

Go to Developer Console > My Platform Apps.
Click the Options menu button (…) next to your app.
Select Generate Developer Token. The token is automatically copied to your clipboard.

Developer tokens expire after one hour. For production use, implement or .

Step 2: Identify your target folder

You need the folder ID where the new note has been created. To find a folder ID:

Open the folder in the Box web app. The folder ID is the number at the end of the URL: https://app.box.com/folder/123456789.
Alternatively, use the API endpoint.

Use 0 as the folder ID to create the note in the root folder (All Files).

Step 3: Create your first Box Note

Send a POST request to the /2.0/notes/convert endpoint with your Markdown content. The API converts the Markdown to a Box Note and uploads it to the specified folder.

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": "# Welcome\n\nThis is my first **Box Note** created using the API.",
       "content_format": "markdown",
       "parent": {
         "id": "123456789"
       },
       "name": "My First Note"
     }'

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": "# Welcome\n\nThis is my first **Box Note** created using the API.",
    "content_format": "markdown",
    "parent": {"id": "123456789"},
    "name": "My First Note",
}

response = requests.post(url, json=payload, headers=headers)
print(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:
      "# Welcome\n\nThis is my first **Box Note** created using the API.",
    content_format: "markdown",
    parent: { id: "123456789" },
    name: "My First Note",
  }),
});

const data = await response.json();
console.log(data);

A successful request returns 201 Created with the new file’s information:

{
  "type": "file",
  "id": "1234567890"
}

Step 4: Verify the note was created

Use the returned id to retrieve the full file metadata from the Box Files API:

curl -L 'https://api.box.com/2.0/files/1234567890' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'

You can also open the Box web app and navigate to the target folder to confirm the .boxnote file appears.

Next steps

Now that you have created your first Box Note, explore these guides:

​Prerequisites

​Step 1: Generate an access token

​Step 2: Identify your target folder

​Step 3: Create your first Box Note

​Step 4: Verify the note was created

​Next steps

Prerequisites

Step 1: Generate an access token

Step 2: Identify your target folder

Step 3: Create your first Box Note

Step 4: Verify the note was created

Next steps