OneNote POST pages

Creates a new page in the user’s default notebook.

Last modified: July 24, 2014

Applies to: OneNote service

In this article
Resource URL
HTTP Request Headers
Extended description
Example request (non-multi-part)
Example request (multi-part)
Example "Presentation" part (required in multi-part requests)
Example "Presentation" part with an HTML data part
Example "Presentation" part with image and file binary data parts
HTTP response headers
Response properties
Example response
Additional resources

The pages resource path represents pages in the user's OneNote notebooks that are stored in Microsoft OneDrive. For platform-specific code examples that show how to use the API, see the How to (OneNote API) topics.

HTTPS://www.onenote.com/api/v1.0/pages
HTTPS://www.onenote.com/api/v1.0/sections/{section ID}/pages
NoteNote

HTTPS://www.onenote.com/api/v1.0/pages is the default notebook location. POST to the /pages endpoint for a specific section when you want to create a page in a location other than the default.

Resource information

Encoding

UTF-8 (including image and file contents)

Protocol

SSL/TLS HTTPS

Size limits

70 MB per POST
25 MB per part in a multi-part message
30 data parts of image and file data, including the "Presentation" part. Image and file data parts provided in the request can be referenced multiple times.

Response format

JSON

Parameters

sectionName

The named section where the page will be stored. If the section doesn’t exist (or was renamed), the API will create the section.

  • This parameter applies only to the default location endpoint: HTTPS://www.onenote.com/api/v1.0/pages. It’s not applicable when you’re using the /pages endpoint for a specific section.

  • Only top-level sections can be created or referenced, and only in the default OneNote notebook. Sections inside OneNote section groups cannot be created, or referenced, even if they already exist.

  • Section names are case-insensitive for matching, but the case is preserved when they are created. So "My New Section" will be displayed like that, but "my new section" would also match on subsequent posts.

  • 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 new section name must be URL-encoded. For example, spaces must be encoded as %20.

  • Users might rename sections, in which case the API will create a new section with the sectionName you supply.

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

Request Header

Value and Description

Content-Type

Text/html
for non-multi-part POST messages, or

multipart/form-data; boundary=yourAppMultiPartBoundaryString for multi-part messages. The boundary string is used to signal the start and end of each MIME part.

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

If you don’t specify a section (with the sectionName parameter), the Microsoft OneNote API creates pages inside the "Quick Notes" section of the user's default notebook. This is typically named using their first name, for example John Doe's might be "John's Notebook", or "My Notebook", or even "Personal".

If there is no default notebook, or if the notebook doesn't have a Quick Notes section, the OneNote API creates them. After the notebook and section are available, the new page will be created.

The POST can either contain HTML placed directly in the request body, or it can use a multi-part message format. The multi-part format supports a single "Presentation" part containing HTML that defines the page layout, and other data parts to be used in the page. Those data parts can contain image binary data, file binary data, or HTML that will be rendered as an image and placed on the OneNote page.

See OneNote API HTML tag support for the set of HTML tags that you can include in your HTTP request body or in the "Presentation" MIME part.

Request the office.onenote_create scope when you authenticate in order to give your product the ability to create pages.


Content-Type:text/html 
Authorization:Bearer tokenString

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the captured OneNote page</title>
    <meta name="created" content="2013-06-11T12:45:00.000-8:00"/>
  </head>
  <body>
    <p>This is a simple non-multi-part HTML page.</p>
  </body>
</html>


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

The HTML has to be XML compatible, so be sure to close tags and include quote-marks around attributes.

The <title> and <meta name="created"> tags in the <head> section are used for the title and created date of your new OneNote page.

To include images that are available as a URL in that simple HTML, you can, using the standard <img src="..."/>. Be aware that the image must be available on the Internet to the OneNote API without requiring authentication, so be careful of images located on a company's intranet that cannot be accessed by the API.


Content-Type:multipart/form-data; boundary=MyAppPartBoundary
Authorization:Bearer tokenString

--MyAppPartBoundary
Content-Disposition:form-data; name="Presentation"
Content-type:text/html

... presentation part html data ...

--MyAppPartBoundary
Content-Disposition:form-data; name="imagePart-1"
Content-type:image/jpeg

... image binary data ...

--MyAppPartBoundary
Content-Disposition:form-data; name="htmlToRender-1"
Content-type:text/html

... html data ...

--MyAppPartBoundary
Content-Disposition:form-data; name="EmbeddedFilePartName1"
Content-type:application/vnd.openxmlformats-officedocument.wordprocessingml.document

... binary file data ...

--MyAppPartBoundary--


The request includes the required "Presentation" part, a binary image data part, an HTML part, and a binary file data part.

The HTML in the "Presentation" part specifies the overall page layout that OneNote will create in the user's notebook.

Separate each MIME part with a line starting with two hyphens followed by the boundary string specified in the Content-Type declaration. Leading whitespace is not allowed. The end of the last message part has two more hypens after the boundary string.

Each of the parts in a OneNote API POST must have a Content-Disposition part header that tells the API how to handle the part and its name. The only accepted part-level Content-Disposition is form-data at this time. Each MIME part must also have a Content-Type header indicating the format of the data in that part.

All multi-part requests must have a "Presentation" part, and depending on what you're capturing, might have one or more image or HTML data parts. If your POST request has more than one part, the part order is not important: the Presentation part can be anywhere in the list of parts, but it must be included somewhere.

Many MIME-encoding libraries can construct the above structure for you, so you might already have this capability and not need to code it manually.

Each part name must be unique. The OneNote API will throw an error if your request contains duplicate part names.

TipTip

The examples in this documentation give easily-recognizable string values for the part names and part boundaries. This is not the part-naming typically used in production apps. In most apps, part names include a string followed by some effectively random, unique string, like the current time in milliseconds, or a GUID. For example, "MyAppBoundrary-73720000422322" or "ImageDataBlock-d2d6aaf5-3bde-4ee7-ba18-27727bf3cffe". Remember, however, that "Presentation" is a special part name, and is required in all multi-part POST requests.


Content-Type:multipart/form-data; boundary=MyAppPartBoundary
Authorization:Bearer tokenString

--MyAppPartBoundary
Content-Disposition:form-data; name="Presentation"
Content-type:text/html

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the captured OneNote page</title>
    <meta name="created" content="2013-06-11T12:45:00.000-8:00"/>
  </head>
  <body>
    <p>This is a simple Presentation block.</p>
  </body>
</html>

--MyAppPartBoundary--


The <head> contents in the "Presentation" part supply the title and creation date/time that OneNote uses for the new page.

The HTML in the "Presentation" part should be XHTML-compliant. All tags should be closed, and attribute values should have surrounding double quote-marks ("...").

The DOCTYPE directive is optional, but recommended.


Content-Type:multipart/form-data; boundary=MyAppPartBoundary
Authorization:Bearer tokenString

--MyAppPartBoundary
Content-Disposition:form-data; name="Presentation"
Content-type:text/html

<!DOCTYPE html>
<html>
  <head>
    <title>A simple page with an thumbnail image of some HTML</title>
  </head>
  <body>
    <img data-render-src="name:MyAppEmbeddedHtmlId" width="100"/>
  </body>
</html>

--MyAppPartBoundary
Content-Disposition:form-data; name="MyAppEmbeddedHtmlId"
Content-type:text/html

<!DOCTYPE html>
<html>
  <body>
    <h1>This is just amazing!</h1>
    <p>That's right, an HTML page captured as an image</p>
  </body>
</html>

--MyAppPartBoundary--

Use the data-render-src attribute to render the data as a screen-shot image of the web page in the new page. This attribute can specify either a live internet URL or the name of a MIME part in the POST request. That HTML will be rendered and inserted into the page as an image. This can be especially useful when your app is capturing a page that requires the user be logged in, since the API isn't able to log in on behalf of the user.

You can refer to the same part name in multiple <img> tags.


Content-Type:multipart/form-data; boundary=MyAppPartBoundary
Authorization:Bearer tokenString

--MyAppPartBoundary
Content-Disposition:form-data; name="Presentation"
Content-type:text/html

<!DOCTYPE html>
<html>
  <head>
    <title>A simple page with an embedded image</title>
  </head>
  <body>
    <p>Here is a cool image I found.</p>
    <img src="name:AppPictureBlockName1" alt="a cool image" width="500"/>
    <p>Here is an embedded file.</p>
    <object data-attachment="EmbeddedFileDisplayName.docx" 
      data="name:EmbeddedFileBlocksName1" 
      type="application/vnd.openxmlformats-officedocument.wordprocessingml.document" />
  </body>
</html>

--MyAppPartBoundary
Content-Disposition:form-data; name="AppPictureBlockName1"
Content-type:image/jpeg

... binary image data ...

--MyAppPartBoundary--
Content-Disposition:form-data; name="EmbeddedFileBlockName1"
Content-type:application/vnd.openxmlformats-officedocument.wordprocessingml.document

... binary file data ...

--MyAppPartBoundary--



The example shows a "Presentation" part with an img tag that tells the API to add a 500-pixel wide image, with a binary image data in the MIME part named AppPictureBlockName1, and an embedded file in the MIME part named EmbeddedFileBlockName1. In this example, the file is a Microsoft Word document.

When you want to embed a file, use the <object> tag, as in the example above.

When you embed image data directly in the POST, you add the data as part of an image data MIME part, and refer to the image using the <img data-render-src="name:…"> tag.

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.

Property

Value and Description

links

The value of oneNoteClientURL can be used to open the newly-created page 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. For platform-specific code samples using the links, see Open the OneNote clients with the OneNote API.

Id

The unique identifier of the page.

Title

The title of the page.

CreatedTime

The date and time when the page was created.

CreatedByAppId

The unique identifier of the application that created the page.

ParentNotebook

An object containing values for the id, name , and link properties of the page’s parent notebook. The link value can be used to open the web-browser based OneNote Online client.

ParentSection

An object containing values for the id, name, and link properties of the page’s parent section. The link value can be used to open the web-browser based OneNote Online client.

Content-Type: application/json
X-CorrelationId: <GUID>
Status: 201 OK
{
"@odata.context": "https://www.onenote.com/api/v1.0/$metadata#pages/$entity",
    "createdTime": "2013-05-22T14:24:00Z",
    "links": {
    "oneNoteClientURL" : {"href" : "onenote:https://..."},
    "oneNoteWebURL" : {"href" : "https://..."},
     "id": "page ID",
     "parentSection": {
        "id": "section ID",
        "name": "section name",
        "link": {"href" : "https://..."}
 },
     "parentNotebook": {
        "id": "notebook ID",
        "name": "notebook name",
        "link": {"href" : "https://..."}
},
     "title": "page title",
     "createdByAppId": "appID"
}

The Microsoft OneNote API returns standard HTML error messages as headers in the response. On success, you'll get a 201 Created response, and when something appears wrong with the request, you'll get an error in the 4xx range. Rarely, you might receive a 5xx error if there are problems with the API.

Show: