Query pages now in Beta!

Hi guys,

Here at the OneNote API Team we continue working through our feature backlog as fast as possible to bring new APIs to you. Today we are happy to announce we just added support for querying OneNote pages in Beta! You can now call the API to query the pages a user has access to regardless of which notebook or section they are in. Yes, this includes querying for pages in both notebooks owned by and shared with the user in a single call. For instance, you can now use the API to:

  1. Build a list view of pages a user has saved to OneNote via your app and allow them to open the page in OneNote or OneNote Online.
  2. Build a "Save to OneNote" location picker that gives users full context of their notebook hierarchy (notebooks-> section groups-> sections-> pages) when choosing a save location.
  3. Query for pages containing a keyword or phrase in the title. For instance, a news app that saves articles to OneNote could use the API to allow users to search for articles that read "Seattle" in the headline.

We know there are important scenarios that require retrieving the contents of the page. We are working on this as we speak and will be announcing it pretty soon. We also know there are apps out there that just want to make it easy for users to get to the content they saved to OneNote within the context of the app and now they can do just that.

So how do you get started? The easiest way is to type your queries below or use the OneNote API Apigee console. You can quickly get an idea of the shape of the API without writing a line of code.

The OneNote API is built on the OData v4 standard which means that if you are already familiar with OData you don't have to learn a new query language to query pages in OneNote. You can expect OData verbs and functions like $filter, $orderby, and $select to just work. Here are a few page queries you can try out. They are all vanilla HTTP GET requests.

  1. [GET] https://www.onenote.com/api/beta/pages - Returns the first 20 pages a user has access to ordered by creation time desc (the default ordering).
  2. [GET] https://www.onenote.com/api/beta/pages?$skip=20&$top=100 - Returns pages 21 to 120. You can use skip and top to page through results and increase page size. The maximum page size is 100.
  3. [GET] https://www.onenote.com/api/beta/pages?$filter=contains(title, 'Seattle') - Returns the first 20 pages containing "Seattle" in the title. String comparisons are case sensitive.
  4. [GET] https://www.onenote.com/api/beta/pages?$filter=createdTime gt 2014-01-23 &$skip=20 - Returns pages 21 to 40 the user has saved to OneNote since Jan 23, 2014.
  5. [GET] https://www.onenote.com/api/beta/section/{id}/pages - Returns the first 20 pages under a specific section. You can get a list of section IDs with the following request: [GET] https://www.onenote.com/api/beta/sections.
  6. [GET] https://www.onenote.com/api/beta/pages?$select=id,title&$orderby=title asc - Returns the id and the title only the first 20 pages ordered alphabetically by title

The response is a collection of page objects in JSON format with the following structure :

         "id":"{some page id}",
            "id":"{some section id}",
            "name":"Unfiled Notes",
            "id":"{some notebook id}",
            "name":"Personal (Web)",
         "title":"Hello World!",
         "createdByAppId":"WLID-{some app id}"

Supported properties, verbs, operators and functions

For this beta release, we are making the following properties available which you can query using OData syntax (we will be adding more properties soon):

  • Page ID
  • Page Title
  • Page Created time
  • Page CreatedByAppId - This is the Windows Live Client ID of the app that created the page
  • Page link
  • Page OneNote Client link
  • Page OneNote Online link
  • Parent notebook ID
  • Parent notebook name
  • Parent notebook link
  • Parent section ID
  • Parent section name
  • Parent section link

And below is the list of OData operators, verbs and functions (more are coming as well):

Verbs: $filter, $orderby, $select, $top, $skip




Comparison Operators





createdByAppId eq '{AppID}'


Not equal

title ne 'Foo'


Greater than

createdTime gt 2014-02-23


Greater than or equal

createdTime ge 2014-05-05T07:00:00Z


Less than

createdTime lt 2014-02-23


Less than or equal

createdTime le 2014-02-23

Logical Operators




Logical and

createdTime le 2014-01-30 and createdTime gt 2014-01-23


Logical or

createdByAppId eq 'foo' or createdByAppId eq 'bar'


Logical negation

not contains(title,'foo')




String Functions









length(title) eq 19


indexof(title,'foobar') eq 1


substring(title,1) eq 'foobar'


tolower(title) eq 'foobar'


toupper(title) eq 'FOOBAR'


trim(title) eq 'foobar'


concat(title,'- by MyRecipesApp') eq 'Carrot Cake Recipe - by MyRecipesApp'

OAuth scopes

We are introducing 3 new OAuth scopes that you can request within your apps to be able to query pages in OneNote.

  • office.onenote - Grants read permissions to the user's notebooks and pages. Request this scope if your app needs to query pages in any of the user's notebooks.
  • office.onenote_update_by_app - Grants create, read, update, and delete permissions to pages created by the app. Request this scope if your app only needs to query pages the user created through your app.
  • office.onenote _update - Grants full access to the user's notebooks and pages. Request this scope if your app needs to query pages in any of the user's notebooks.

If you notice the actual OneNote REST API is super simple to use. Authorizing the request is perhaps the one tricky thing. We don't want you to spend any time writing boiler plate code so we have posted a few code samples (for all major platforms) on GitHub that take care of this for you so you can get right to business. You can also use the code snippets below if you want to quickly try this within an existing app.


  1. Get a client ID for use with the OneNote API.
  2. Get a Windows Store developer account and register you app with the Windows Store.
  3. Install and add a reference to the Live SDK within your project.
 1: using Microsoft.Live;
 5: private async void QueryPages()
 6: {
 7:    var client = new LiveAuthClient();
 8:    var loginResult = await client.LoginAsync(new string[] { 
 9:              "wl.signin", 
 10:              "office.onenote" });
 12:    if (loginResult.Status == LiveConnectSessionStatus.Connected)
 13:    {
 14:       using (var httpClient = new HttpClient())
 15:       {
 16:          HttpRequestMessage request = new HttpRequestMessage(
 17:                      HttpMethod.Get, "https://www.onenote.com/api/beta/pages");
 18:          request.Headers.Add("Authorization", "Bearer " + loginResult.Session.AccessToken);
 19:          var response = await httpClient.SendAsync(request);
 20:          var content = response.Content.ReadAsStringAsync();
 21:       }
 22:    }
 23: }

Help us make it better
As with the rest of our API features in Beta, we want you to try page queries out in your apps and give us feedback. Tell us what tweaks you think we should make to simplify your code, what things are missing to complete your scenario, what are the things you like that we should leave untouched, and if you think we just got it plain wrong we want to hear that too :)! Help us make the API better for you and the rest of the OneNote developer community so once it sticks it sticks for good. We are planning to leave this feature in Beta for at least one month (possibly more) for you to try it out and post your suggestions. We will iterate on your feedback and release to production soon after.

Please post your recommendations as comments to this post. for feature requests you can add to the list or vote on UserVoice. Finally, if you have any problems with the OneNote API in general please post your questions to stackoverflow.

Look out for more updates coming soon and happy coding.

- Omar

Comments (13)
  1. Roy says:

    parentSection used to work until a few days ago, but very recently (days ago?) the API stopped returning it again. Any idea what that might be?

  2. Omar Venado says:

    Hi Steven,

    If you want to import data from the OneNote API into Excel your best bet at the moment would be Power Query. Even with Power Query you will have to workaround it a bit as they do not currently support  Microsoft Account as a first class authentication mechanism (which the OneNote API depends on). However, you can still import your OneNote data into Excel. You just have to do a couple of extra steps. Here's how:

    1) Install Power Query

    2) From the PQ ribbon: From Other Sources -> Blank Query

    3) Open the "Advanced Editor" and type in the following:


       Source = Web.Contents("https://www.onenote.com/api/v1.0/pages",

                [Headers =

                  [Authorization="Bearer <xxxx>"]




    4) Replace <xxxx> with your token. Easiest way is to get it from our Apiary console.

    5) Open as JSON. From here on is just regular Power Query.

    Not pretty but I hope that helps.

  3. Steven Buehler says:

    Could really use some examples in VISUAL BASIC and VBA. Not everyone codes in C#!

  4. Steven Buehler says:

    How would I be able to access this information, say, using an oData data connection in Excel?

  5. Omar Venado says:


    Thanks for the feedback. The current behavior is case-sensitive for string comparisons. I have updated the post to reflect this.

  6. QueryLover says:

    3.[GET] http://www.onenote.com/…/pages$filter=contains(title, 'Seattle') – Returns the first 20 pages containing "seattle" or "Seattle" in the title. String comparisons are case insensitive

    This seems wrong. I am NOT seeing this call being case-sensitive.

  7. Omar Venado says:

    Hi Troy,

    We plan to add more page properties including the last modified time of the page. Any other properties you would like to see?

  8. Troy says:

    Is there an updatedTime that could be added to the API or does createdTime incorporate creates and updates?

  9. DipakBoyed_msft says:

    @mpiu: Yes, it is possible to get the page's content in html format. Check out the newest Beta feature: blogs.msdn.com/…/new-beta-api-page-recall.aspx

  10. mpiu says:

    Is it possible to get page's content in html format ?

  11. Omar Venado says:

    Hi Cem,

    Yes. Parent navigation properties are coming back soon. We thought it would be a better idea to make them available as part of supporting the $expand verb across the API. Expand will allow apps to optimize their API calling patterns by requesting properties from multiple entity types in a single RT. Stay tuned.

  12. Cem Ezberci says:

    It seems like parentNotebook, parentSection and parentSectionGroup concepts have disappeared. I guess such changes are expected in beta but wanted to make sure if they are gone for good or they will come back at some point. It would be quite useful to know as I am building an SDK and the change breaks my integration tests.

  13. S. Liang says:

    This is awesome!

Comments are closed.

Skip to main content