OneNote GET sections

Article
07/30/2014

Gets details of sections to which a user has access.

Applies to: OneNote service

In this article
Resource URLs
HTTP Request Headers
OAuth scopes
Extended description
Example requests
HTTP response headers
Response properties
Example response
Additional resources

The GET verb with the sections resource path represents all sections to which a user has access in all OneNote notebooks that are stored in Microsoft OneDrive. This includes sections in notebooks that are both owned by and shared with the user. You can also retrieve all sections to which the user has access inside a specific notebook or section group.

Resource URLs

HTTPS://www.onenote.com/api/v1.0/sections
HTTPS://www.onenote.com/api/v1.0/notebooks/{notebook ID}/sections
HTTPS://www.onenote.com/api/v1.0/sectiongroups/{section group ID}/sections

Resource information

Protocol	SSL/TLS HTTPS
Response format	JSON

Parameters

$orderby	One or more comma-delimited expressions with an optional ‘asc’ (the default) or ‘desc’ depending on the order you’d like the values sorted. The value of this operator is the list of section properties to use for sorting the sections returned by the API and the order in which to sort the results. Valid properties are lastModifiedTime, createdTime, and name. These values are case-sensitive. The default value is name asc (ascending by name). The modifiedTime property refers to the date and time when a page in the section was last modified. You can specify a list of properties, such as $orderby=name asc, lastModifiedTime desc (ascending by name and descending by lastModifiedTime). The order in which you list the properties will determine the level at which each sort occurs. If you specify a property more than once, only the first instance of the property will be used.	$orderby=name asc
$filter	A Boolean expression for whether a particular entry should be included in the response.	$filter=contains(name, ‘text’)
$select	Limit the properties on each entry in the response to the ones that are specified by this value.	$select=id,name

HTTP Request Headers

All requests to the OneNote API must include the Authorization header.

Request Header	Value and Description
Authorization	Bearer tokenString A valid OAuth token provided to the app based on the user credentials and the user having authorized access. For more information, see Authenticate the user for the OneNote API.

Security Note
The Microsoft OneNote API requires OAUTH authentication, so user names and passwords passed in clear text, as is done with Basic authentication, are not accepted. To ensure the security of your user's account credentials, be sure your app doesn't attempt to use Basic authentication, or send account credentials, even when it's over HTTPS.

OAuth scopes

Request one of the following scopes when your product authenticates the user, depending on what you want the user to be able to see.

Scopes

Scope	Purpose
office.onenote	Grants read permissions to the user's notebooks and pages. Request this scope if your product needs to query sections in any of the user's notebooks.
office.onenote_update_by_app	Grants create, read, update, and delete permissions to pages created by the product. Request this scope if your product only needs to query sections that the user created through your product.
office.onenote_update	Grants full access to the user's notebooks, sections, and pages. Request this scope if your product needs to query and update sections in any of the user's notebooks.
office.onenote_create	Allows your product to enumerate the notebook hierarchy and create pages in any location. Request this scope if your product needs to create pages in any of the user's notebooks.

Extended description

When you use the GET verb with the /sections endpoint, the OneNote API returns the sections as JSON objects that conform to the OData version 4.0 specification.

The /sections endpoint returns all sections, including ones that are nested inside notebooks and section groups. The sections returned at the /notebooks/{notebook ID}/sections and /sectiongroups/{section group ID}/sections endpoints return only the sections directly underneath the specified notebook or section group. You can get a list of section group IDs by using the sectiongroups resource path.

Example requests

[GET] https://www.onenote.com/api/v1.0/notebooks/{notebook ID}/sections

This returns the sections to which the user has access within a specific notebook. Default ordering is by name asc (case insensitive).

[GET] https://www.onenote.com/api/v1.0/notebooks/{notebook ID}/sectiongroups/{section group ID}/sections

This returns the sections in a specific section group. You can get a list of section group IDs by using the sectiongroups resource path.

[GET] https://www.onenote.com/api/v1.0/notebooks/{notebook ID}/sections?$select=id,name,createdTime&$orderby=createdTime

This returns only the id, title and createdTime properties for the sections in a specific notebook, ordered by createdTime.

HTTP response headers

Response Header	Value and Description
Content-Type	Application/json: charset=utf-8 The API always returns data in JSON format.
X-CorrelationId	<GUID> The correlation ID uniquely identifies the request and can be used when debugging problems.

Content-Type

Application/json: charset=utf-8

The API always returns data in JSON format.

X-CorrelationId

<GUID>

The correlation ID uniquely identifies the request and can be used when debugging problems.

Response properties

Property	Value and description	Value type
isDefault	Indicates whether this is the user’s default section.	Boolean
pagesUrl	The /pages endpoint where you can get details for all the pages in the section.	string
self	The endpoint where you can get details about the section.	string
id	The unique identifier of the section.	string
name	The name of the section.	string
createdBy	The user who created the section.	string
createdTime	The date and time when the section was created.	An ISO 8601 formatted date.
lastModifiedBy	The user who last modified the section.	string
lastModifiedTime	The date and time when the section was last modified.	An ISO 8601 formatted date.

Example response

Content-Type: application/json
X-CorrelationId: <GUID>
Status: 200 OK
{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#sections","value":[
    {
      "isDefault":false,
"pagesUrl":"https://www.onenote.com/api/v1.0/sections/section ID/pages",
"id":"section ID",
"name":"section name",
"self":"https://www.onenote.com/api/v1.0/sections/section ID",
"createdBy":"user name",
"lastModifiedBy":"user name",
"createdTime":"2013-10-05T10:58:19.98Z",
"lastModifiedTime":"2013-10-13T10:42:36.11Z"
    },
{
      "isDefault":false,
"pagesUrl":"https://www.onenote.com/api/v1.0/sections/section ID/pages",
"id":"section ID",
"name":"section name",
"self":"https://www.onenote.com/api/v1.0/sections/section ID",
"createdBy":"user name",
"lastModifiedBy":"user name",
"createdTime":"2013-10-05T16:48:52.233Z",
"lastModifiedTime":"2014-01-28T18:49:00.47Z"
    }
  ]
}