OneNote API

  • Article

Please use our new documentation site. It contains content for working with consumer and enterprise OneNote APIs.

Applies to: OneNote service

Welcome to our API! Microsoft OneNote API enables developers to write apps on many different platforms and device-types that create and manipulate user's information stored in Microsoft OneNote. This topic presents a running list of recent updates we've made to the API and documentation.

If you have any questions or other input on the API or documentation, please feel free to come join us in the communities listed at the bottom of the Getting started with the OneNote API topic. We look forward to hearing from you, and hope you find the API and documentation useful.

Note

Subscribe to the OneNote page on API Changelog and stay up-to-date with changes to our API and documentation.

OneNote documentation and API changes

September, 2015

The maximum number of pages returned in a GET pages request using the $top query option changed from 500 to 100.

July, 2015

Released two OneNote REST API explorer sample apps:

Released DELETE pages to production.

Updated the root service URL in the how-to topics to use the new, recommended /me/notes/ route: https://www.onenote.com/api/v1.0/me/notes/

June, 2015

Published the Use note tags topic.

May, 2015

Refactored error codes and updated the Error and warning codes topic.

  Removed: 20103, 20104, 20105, 20114, 20116, 20118
  Added: 20150, 20151, 20152, 20153, 20154, 20155, 20156, 20157, 20158
  Changed: 20115 (changed set of invalid characters for a notebook name)

If you're handling errors related to entity name validation, this may be a breaking change. The following table shows how to handle the changes.

In your code, replace this error code ...

with this error code

20105 (SectionNameEmpty)
20116 (NameEmpty)

20152 (EntityNameEmpty)

20104 (SectionNameInvalidChar)

20153 (EntityNameInvalidChar)

20118 (SectionNameInvalidStart)

20154 (EntityNameInvalidStart)

20103 (SectionNameTooLong)
20114 (NotebookNameTooLong)

20155 (EntityNameTooLong)

April, 2015

Released PATCH to production. Published the Update page content topic.

February, 2015

Released the following APIs to production:

  • Page query

  • Full-text search

  • Retrieve page content

  • Create absolutely positioned elements

Published the Input and output HTML for OneNote pages and Create pages with absolutely positioned elements articles and updated Get OneNote content and structure. Posted related information on the OneNote Developer Blog and OneNote API interactive reference.

January, 2015

Posted the Windows Universal app sample on GitHub. Released the business card, recipe URL, and product URL extraction API and expand query string option support. Published the Enrich captured content and Retrieve objects in the notebook hierarchy articles.

October, 2014

We moved the reference documentation to our new OneNote API interactive console.

July, 2014

We added these references for additional capabilities:

  • OneNote GET sections

  • OneNote GET sections/id

  • OneNote GET sectiongroups

  • OneNote GET sectiongroups/id

  • OneNote GET notebooks

  • OneNote GET notebooks/id

  • OneNote POST notebooks

  • OneNote POST notebooks/id/sections

  • OneNote API error and warning codes

June, 2014

Revamped format for OneNote API Reference section.

Week of April 29, 2014, minor update

In our first update, we've completed a couple of handy features for developers writing apps that work with PDF documents or that want captures to go to a specific notebook section:

  • PDF rendering as images directly on the OneNote page. With this update, when you add an <img data-render-src="name:BlockOfPDFData"/> the OneNote API will render the PDF pages as images, and insert them onto the page. Common practice is to also embed the PDF file onto the page, and you can do that with the <object data-render-src="name:BlockOfPDFData"/> tag. You can even reference the same BlockOfPDFData for both tags. Prior to this update, you could embed the file on the page, but not yet render the images from the same PDF data. For more, see the article on how to Capture and embed PDF files with the OneNote API.

  • Create pages in specific sections by including the sectionName query parameter in your pages POST requests. If the top-level section name you provide doesn't exist, the API will create it. With this new feature, your app can store captures in an easily-recognized section. You can learn more at Capture pages in a specific section using the OneNote API.

We made these updates to the documentation:

March 17, 2014, Initial Release

Here are the current highlights of the OneNote API:

  • The API version 1.0 is now available for your use! The main REST endpoint is https://www.onenote.com/api/v1.0. The only resource path available now is /pages, but we've got big plans for more!

  • At initial release, the API supports creating new OneNote pages using HTML to define the page. You can include images, and embed other binary file types (up to 25MB per file, 75MB per page total) on each OneNote page. The API can take a snapshot of Web pages and include the page as an image on the OneNote page. It also performs OCR on images your app captures.

  • Before your app can work, it needs to have either a client ID, or if you're making a Windows 8 Store app, it needs to have a package ID. You can find full information at Get a client ID for use with the OneNote API.

  • In addition, the OneNote API requires the user of your app have a Microsoft Account. They don't need to be using a Microsoft device, but need a Microsoft account. For more information about using the Windows Live Connect SDK, see Authenticate the user for the OneNote API.

The initial set of documentation includes the following sections:

We're always grateful to hear from you about issues you find in the docs, and whether they give you what you need. The API is intended for both experienced and new app developers, so let us know how we're doing.