OneNote POST notebooks/id/sections

  • Article

Creates a new section in the user’s specified notebook in Microsoft OneDrive.

Applies to: OneNote service

In this article
Resource URL
HTTP Request Headers
OAuth scopes
Request properties
Example request
HTTP response headers
Response properties
Example response
Additional resources

The POST verb with the /notebooks/{notebook id}/sections resource path creates sections in the user's specified OneNote notebook in Microsoft OneDrive.

Resource URL

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

Note

You can’t use the HTTPS://www.onenote.com/api/v1.0/sectiongroups/id/sections endpoint to create sections.

Resource information

Encoding

UTF-8 (including image and file contents)

Protocol

SSL/TLS HTTPS

Request format

JSON

Response format

JSON

HTTP Request Headers

All requests to the OneNote API must include Content-Type and Authorization headers.

Request Header

Value and Description

Content-Type

application/json

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 noteSecurity 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 the following scope when your product authenticates the user.

Scopes

Scope

Purpose

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 sections.

Request properties

Property

Value and description

name

The name of the section.

  • Some characters are not allowed. If you include ? * \ / : < > | & # " % ~ 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 section name cannot exceed 50 characters.

Example request

Content-Type:application/json 
Authorization:Bearer tokenString

{
   "name":"section name"
}

In the Authorization header, replace tokenString with the actual OAuth token.

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.

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 create new pages in the section. Use the POST verb with this endpoint to create new pages inside 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: 201 OK
{
   "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#sections",
   {
      "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"
}

Additional resources