Quick Way to Create a Page in a Specific Section

  • Article

I'm excited to announce yet another new feature to our API. As mentioned in our Notebook Hierarchy Recall Preview and OneNote API Near-Term Roadmap blog posts, we are already working on enabling developers to get a list of a user's Notebooks and Sections and choose specific locations to create new pages in. However, we are excited to announce a new feature today that is lighter-weight, yet still meets a need that many of you have sent us feedback about.

We now support a sectionName query parameter on our ~/pages endpoint. This allows you to specify a section name that you want the page created in within the user's default notebook. (If you don't specify a section name, the page will be created in the default location.)

The idea here is that in your app's code, you can choose a specific section to create all of your pages in. For example: if you are writing an app about collecting recipes, you may want all of the pages to go to a section called "Recipes" and would call ~/pages?sectionName=Recipes.

To use this new feature, just append the sectionName query term to the ~/pages endpoint. An example would look like:

 POST https://www.onenote.com/api/v1.0/pages?sectionName=Foo

You can also try out this feature now in our APIGee Console.

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.
  • A 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 one of the OneNote clients, 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.

Stay tuned for more new features and announcements!