OneNote API for Office 365 is GA

  • Article

Greetings! This is Diane from the OneNote team. In the spring, we announced preview support for personal notebooks on OneDrive for Business and SharePoint site-hosted notebooks. This enterprise support in now generally available, and brings with it some great new features!

  • Support for Office 365 group notebooks. More about group support below.
  • The Notes.Read.All and Notes.ReadWrite.All permission scopes for organization-level access to site and group notebooks. We previously allowed access to site notebooks using the other OneNote scopes, but this is no longer supported.
  • New parentNotebook and parentSection navigation properties for pages. The default page query now returns the id, name, and self properties of the page's parent section. (consumer and enterprise APIs)
  • New level and order properties for pages. These show the indentation level of the page and the order of the page within the parent section. To get them, use the pagelevel parameter in queries for pages in a section or for a specific page, for example: GET ../sections/{id}/pages?pagelevel=true (consumer and enterprise APIs) 

Also, the following APIs moved from preview to production:

POST /sectiongroups/{id}/sections,

  POST /notebooks/{id}/sectiongroups,

    POST /sectiongroups/{id}/sectiongroups   (consumer and enterprise APIs)

CopyNotebook,

  CopyToNotebook,

    CopyToSectionGroup,

      CopyToSection (enterprise API only)

Note the following restrictions for working with the enterprise API:

  • The search query string option is not supported for enterprise notebooks.
  • The POST /notes/pages request which creates a page in the default section of the default notebook is not supported for site or group notebooks.
  • Only the me keyword is supported to access personal notebooks on OneDrive for Business. This represents the current user.
  • Only the myorganization keyword is supported to access site or group notebooks. This represents the tenant that they the current user is logged into.

Check out our new doc site for articles that show how to use the consumer and enterprise OneNote APIs, including app registration, authentication, and permissions. And use our interactive consoles to try out the API on your own consumer notebooks. They don't yet support Office 365 notebooks, but the APIs work the same.

Office 365 groups support

Office 365 groups (also known as unified groups) are part of the Office 365 connected experience. Group members can share files, email, and more. In terms of the OneNote API, groups are another entity that can own OneNote notebooks, like users and SharePoint sites.

To access a group's OneNote content, start with the ../myorganization/groups/{id}/notes/ service root URL, and then navigate to OneNote resources. For example, this URI gets all pages from a particular section:

GET https://www.onenote.com/api/v1.0/myorganization/groups/{id}/notes/sections/{id}/pages

You can use the Azure AD Graph API to get group IDs.

Granting Group permissions

To get group IDs using the Azure AD Graph API, you need User and Group permissions. To access group notebooks, you need permissions to OneNote. You can specify these permissions in the Azure Management Portal when you configure your app.

At the bottom of the app's Configure tab, set these permissions:

For the Windows Azure Active Directory application:

Read all user's basic profiles (User.ReadBasic.All) and

Read all groups (preview) (Read all groups (preview)) Requires administrator consent.

For the OneNote application:

View OneNote notebooks in your organization (Notes.Read.All) or

View and modify OneNote notebooks in your organization (Notes.ReadWrite.All)

For now, you'll need separate OAuth 2.0 access tokens: One to get group information and one to access the group's notebooks.

But you can take advantage of Discovery Service v2.0 to access Office 365 services, including OneNote (as the Notes capability). Your users sign in once, and you can get a token for Discovery Service that you use to get tokens for other services you have access to.

We'd love to hear your suggestions and comments on UserVoice or on twitter @onenotedev. And please post your questions tagged onenote on Stack Overflow.

Edit: 11/18/15 Remove Microsoft Graph references.