OneNote JavaScript API programming overview

OneNote introduces a JavaScript API for OneNote add-ins on the web. You can create task pane add-ins, content add-ins, and add-in commands that interact with OneNote objects and connect to web services or other web-based resources.


If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

Components of an Office Add-in

Add-ins consist of two basic components:

  • A web application consisting of a webpage and any required JavaScript, CSS, or other files. These files are hosted on a web server or web hosting service, such as Microsoft Azure. In OneNote on the web, the web application displays in a browser control or iframe.

  • An XML manifest that specifies the URL of the add-in's webpage and any access requirements, settings, and capabilities for the add-in. This file is stored on the client. OneNote add-ins use the same manifest format as other Office Add-ins.

Office Add-in = Manifest + Webpage

An Office Add-in consists of a manifest and webpage

Using the JavaScript API

Add-ins use the runtime context of the host application to access the JavaScript API. The API has two layers:

  • A host-specific API for OneNote-specific operations, accessed through the Application object.
  • A Common API that's shared across Office applications, accessed through the Document object.

Accessing the host-specific API through the Application object

Use the Application object to access OneNote objects such as Notebook, Section, and Page. With host-specific APIs, you run batch operations on proxy objects. The basic flow goes something like this:

  1. Get the application instance from the context.

  2. Create a proxy that represents the OneNote object you want to work with. You interact synchronously with proxy objects by reading and writing their properties and calling their methods.

  3. Call load on the proxy to fill it with the property values specified in the parameter. This call is added to the queue of commands.


    Method calls to the API (such as context.application.getActiveSection().pages;) are also added to the queue.

  4. Call context.sync to run all queued commands in the order that they were queued. This synchronizes the state between your running script and the real objects, and by retrieving properties of loaded OneNote objects for use in your script. You can use the returned promise object for chaining additional actions.

For example:

function getPagesInSection() { (context) {

        // Get the pages in the current section.
        var pages = context.application.getActiveSection().pages;

        // Queue a command to load the id and title for each page.

        // Run the queued commands, and return a promise to indicate task completion.
        return context.sync()
            .then(function () {

                // Read the id and title of each page.
                $.each(pages.items, function(index, page) {
                    var pageId =;
                    var pageTitle = page.title;
                    console.log(pageTitle + ': ' + pageId);
            .catch(function (error) {
                app.showNotification("Error: " + error);
                console.log("Error: " + error);
                if (error instanceof OfficeExtension.Error) {
                    console.log("Debug info: " + JSON.stringify(error.debugInfo));

You can find supported OneNote objects and operations in the API reference.

OneNote JavaScript API requirement sets

Requirement sets are named groups of API members. Office Add-ins use requirement sets specified in the manifest or use a runtime check to determine whether an Office host supports APIs that an add-in needs. For detailed information about OneNote JavaScript API requirement sets, see OneNote JavaScript API requirement sets.

Accessing the Common API through the Document object

Use the Document object to access the Common API, such as the getSelectedDataAsync and setSelectedDataAsync methods.

For example:

function getSelectionFromPage() {
        { valueFormat: "unformatted" },
        function (asyncResult) {
            var error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            else $('#input').val(asyncResult.value);

OneNote add-ins support only the following Common APIs:

API Notes
Office.context.document.getSelectedDataAsync Office.CoercionType.Text and Office.CoercionType.Matrix only
Office.context.document.setSelectedDataAsync Office.CoercionType.Text, Office.CoercionType.Image, and Office.CoercionType.Html only
var mySetting = Office.context.document.settings.get(name); Settings are supported by content add-ins only
Office.context.document.settings.set(name, value); Settings are supported by content add-ins only

In general, you use the Common API to do something that isn't supported in the host-specific API. To learn more about using the Common API, see Office JavaScript API object model.

OneNote object model diagram

The following diagram represents what's currently available in the OneNote JavaScript API.

OneNote object model diagram

See also