OneNote POST notebooks

  • Article

Creates a new notebook for the user 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 resource path creates notebooks for the user that are stored in Microsoft OneDrive.

Resource URL

HTTPS://www.onenote.com/api/v1.0/notebooks

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

Request properties

Property

Value and description

name

The name of the notebook.

  • 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 notebook name cannot exceed 50 characters.

Example request

Content-Type:application/json 
Authorization:Bearer tokenString

{
   "name":"notebook 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

userRole

One of three values: Owner, Contributor, or Reader. If the value is Owner, the user has owner-level access to the notebook. If the value is Contributor, the user has read/write access to the notebook. If the value is Reader, the user has read-only access to the notebook.

string

isShared

Indicates whether the notebook is shared. If true, the contents of the notebook can be seen by people other than the owner.

Boolean

sectionsUrl

The /sections endpoint where you can get details for all the sections in the notebook.

string

sectionGroupsUrl

The /sectiongroups endpoint where you can get details for all the section groups in the notebook.

string

links

The value of oneNoteClientURL can be used to open the notebook using the OneNote native client app if it's installed. The value of oneNoteWebURL can be used to open the web-browser based OneNote Online client.

links object

self

The endpoint where you can get details about the notebook.

string

id

The unique identifier of the notebook.

string

name

The name of the notebook.

string

createdBy

The user who created the notebook.

string

createdTime

The date and time when the notebook was created.

An ISO 8601 formatted date.

lastModifiedBy

The user who last modified the notebook.

string

lastModifiedTime

The date and time when the notebook 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#notebooks",
      "isDefault":false,
      "userRole":"Contributor",
      "isShared":false,
      "sectionsUrl":"https://www.onenote.com/api/v1.0/notebooks/notebook ID/sections",
      "sectionGroupsUrl":"https://www.onenote.com/api/v1.0/notebooks/notebook ID/sectionGroups",
      "links":{
         "oneNoteClientUrl":{
         "href":"https:{client URL}"
         },
         "oneNoteWebUrl":{
         "href":"https://{web URL}"
         }
      },
      "id":"notebook ID",
      "name":"notebook name",
      "self":"https://www.onenote.com/api/v1.0/notebooks/notebook ID",
      "createdBy":"user name",
      "lastModifiedBy":"user name",
      "createdTime":"2013-10-05T10:57:00.683Z",
      "lastModifiedTime":"2014-01-28T18:49:00.47Z"
}

Additional resources