Capture pages in a specific section using the OneNote API

This topic shows how to specify the OneNote notebook section for pages POSTed using the Microsoft OneNote API.

Last modified: January 22, 2016

Applies to: OneNote service

Note Note

See this content on our new documentation site for consumer and enterprise OneNote APIs.

The OneNote API enables apps to create new OneNote pages with a POST operation to the pages REST resource. By default the API stores new pages in the QuickNotes section of the user's default notebook on OneDrive. If your app adds the sectionName query parameter and gives a URL-encoded notebook section name, the API will put the new page in it, and will create the new section if it doesn't exist.

Using sectionName is easy: just add it to your POST request as a query parameter, like this:



POST https://www.onenote.com/api/v1.0/me/notes/pages?sectionName=My%20custom%20section%20name

In the above example, sectionName is preceded by "?" because it's the first query parameter. Like with other HTTP query parameters, if this isn't the first one, you'd use "&" before it instead.

The following are some things to keep in mind:

  • Only top-level sections can be created or referenced, and only in the default OneNote notebook. Sections inside OneNote section groups cannot be created, or referenced, even if they already exist.

  • Section will be created if it doesn't exist, so it's safe to use with every page your app creates.

  • Section names are case-insensitive for matching, but the case is preserved when they are created. So "My New Section" will be displayed like that, but "my new section" would also match on subsequent posts.

  • Some characters are not allowed. If you include any of ? * \ / : < > | & # " % ~ you'll receive an error from the API. Single-quotes (apostrophes) are allowed, like in "John's Restaurant Reviews", but double-quotes are not.

  • The new section's name must be URL-encoded. For example, spaces must be %20.

  • Users might rename sections, in which case the API will create a new section with the sectionName you supply. Note that the links returned by the API for pages in the renamed section will still reach those older pages.

Show: