Update page content with the OneNote API
You can add and replace HTML elements on a OneNote page by using the OneNote API.
Last modified: January 22, 2016
Applies to: OneNote service
In this article
Attributes for JSON objects
Supported elements and actions
JSON object and PATCH request examples
Permission scopes
Request and response information
Note
|
|---|
|
See this topic on our new documentation site for consumer and enterprise OneNote APIs. |
The HTML of a OneNote page contains text, images, and other content organized into structures such as div, img, and ol elements. To update page HTML, you send a PATCH request to the page's content endpoint:
PATCH ../api/v1.0/me/notes/pages/{page-id}/content
Your changes are sent in the request body as an array of JSON objects. Each object specifies the target element, new HTML content, and what to do with the content.
The following array defines two changes. The first inserts an image above a paragraph as a sibling, and the second appends an item to a list as a last child.
[
{
'target':'#para-id',
'action':'insert',
'position':'before',
'content':'<img src="image-url-or-part-name" alt="Image above the target paragraph" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the end of the list</li>'
}
]
The array is sent in the request body (see examples). If the request is successful, the OneNote API returns a 204 HTTP status code.
Use the following attributes to define JSON change objects for PATCH requests.
|
Attribute |
Description |
|---|---|
|
target |
The element to update. The value must be one of the following identifiers:
To get the IDs on a page, send a GET request to the page's content endpoint: |
|
action |
The action to perform on the target element. See supported actions for elements.
|
|
position |
The location to add the supplied content, relative to the target element. Defaults to after if omitted.
|
|
content |
A string of well-formed HTML to add to the page and any image or file binary data. If the content contains binary data, the request must be sent using the multipart/form-data content type with a "Commands" part (see an example). |
Generated IDs
The OneNote API generates id values for page elements that can be updated. To get generated IDs, use the includeIDs=true query string expression in your GET request:
GET ../api/v1.0/me/notes/pages/{page-id}/content?includeIDs=true
Note
|
|---|
|
The API discards all id values that are defined in the input HTML of create and update-page requests. |
The following example shows generated IDs for a paragraph and an image in the output HTML of a page.
<p id="p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}">Some text on the page</p>
<img id="img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}" ... />
Note |
|---|
Generated id values might change after a page update, so you should get the current values before building a PATCH request that uses them. |
You can specify target elements by using the data-id or id value, as follows:
For append and insert actions, you can use either ID as the target value.
For replace actions, you must use the generated ID for all elements except for the page title and images and objects that are within a div. To replace a title, use the title keyword. To replace images and objects that are within a div, use either data-id or id.
The following example uses the id value for the target . Don't use the # prefix with a generated ID.
[
{
'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
'action':'insert',
'position':'before',
'content':'<p>This paragraph goes above the target paragraph.</p>'
}
]
Many elements on the page can be updated, but each element type supports specific actions. The following table shows supported target elements and the update actions that they support.
|
Element |
Replace |
Append child |
Insert sibling |
|---|---|---|---|
|
body |
no |
yes |
no |
|
no |
yes |
no |
|
|
div |
yes
|
yes |
yes |
|
img, object |
yes |
no |
yes |
|
ol, ul |
yes
|
yes |
yes |
|
table |
yes
|
no |
yes |
|
p, li, h1-h6 |
yes
|
no |
yes |
|
title |
yes |
no |
no |
The following elements do not support any update actions.
|
img (absolutely positioned) object (absolutely positioned) style tags |
tr meta head |
td span a |
An update request contains one or more changes represented as JSON objects. These objects can define different targets on the page and different actions and content for the targets.
The following examples include JSON objects used in PATCH requests and complete PATCH requests:
Append child elements | Insert sibling elements | Replace elements | Complete PATCH requests
Note
|
|---|
|
To update page content, your app first needs to authenticate the user and request appropriate permissions. |
Append child elements
The append action adds a child to a body, div (within a div), ol, or ul element. The position attribute determines whether to append the child before or after the target. The default position is after.
You can use the prepend action as a shortcut for append + before.
Append to a div
The following example adds two child nodes to the div1 element. It adds an image as the first child and a paragraph as the last child.
[
{
'target':'#div1',
'action':'append',
'position':'before',
'content':'<img data-id="first-child" src="image-url-or-part-name" />'
},
{
'target':'#div1',
'action':'append',
'content':'<p data-id="last-child">New paragraph appended to the div</p>'
}
]
Append to the body element
You can use the body target as a shortcut to append a child element inside the first div on any page.
The following example adds two paragraphs as the first child and the last child to the first div on the page. Don't use a # with the body target. This example uses the prepend shortcut for append + before.
[
{
'target':'body',
'action':'prepend',
'content':'<p data-id="first-child">New paragraph as first child in the first div</p>'
},
{
'target':'body',
'action':'append',
'content':'<p data-id="last-child">New paragraph as last child in the first div</p>'
}
]
Append to a list
The following example adds a list item as a last child to the target list. The list-style-type property is defined because the item uses a non-default list style.
[
{
'target':'#circle-ul',
'action':'append',
'content':'<li style="list-style-type:circle">Item at the end of the list</li>'
}
]
Insert sibling elements
The insert action adds a sibling to the target element. The position attribute determines whether to insert the sibling before or after the target. The default position is after. See elements that support insert.
Insert siblings
The following example adds two sibling nodes to the page. It adds an image above the para1 element and a paragraph below the para2 element.
[
{
'target':'#para1',
'action':'insert',
'position':'before',
'content':'<img src="image-url-or-part-name" alt="Image inserted above the target" />'
},
{
'target':'#para2',
'action':'insert',
'content':'<p data-id="next-sibling">Paragraph inserted below the target</p>'
}
]
Replace elements
You can use either the data-id or generated id as the target value to replace img and object elements that are within a div. To replace the page title, use the title keyword. For all other elements that support replace, you must use the generated ID.
Replace an image
The following example replaces an image with a div by using the image's data-id as the target.
[
{
'target':'#img1',
'action':'replace',
'content':'<div data-id="new-div"><p>This div replaces the image</p></div>'
}
]
Update a table
This example shows how to update a table by using its generated ID. Replacing tr and td elements is not supported, but you can replace the entire table.
[
{
'target':'table:{de3e0977-94e4-4bb0-8fee-0379eaf47486}{11}',
'action':'replace',
'content':'<table data-id="football">
<tr><td><p><b>Brazil</b></p></td><td><p>Germany</p></td></tr>
<tr><td><p>France</p></td><td><p><b>Italy</b></p></td></tr>
<tr><td><p>Netherlands</p></td><td><p><b>Spain</b></p></td></tr>
<tr><td><p>Argentina</p></td><td><p><b>Germany</b></p></td></tr></table>'
}
]
Change the title
This example shows how to change the title of a page. To change the title, use the title keyword as the target value. Don't use a # with the title target.
[
{
'target':'title',
'action':'replace',
'content':'New title'
}
]
Update a to-do item
The following example uses the replace action to change a to-do check box item to a completed state.
[
{
'target':'#task1',
'action':'replace',
'content':'<p data-tag="to-do:completed" data-id="task1">First task</p>'
}
]
See Use note tags for more about using the data-tag attribute.
Complete PATCH requests
The following examples show complete PATCH requests.
Request with text content only
The following example shows a PATCH request that uses the application/json content type. You can use this format when your content doesn't contain binary data.
PATCH https://www.onenote.com/api/v1.0/me/notes/pages/{page-id}/content
Content-Type: application/json
Authorization: Bearer {token}
[
{
'target':'#para-id',
'action':'insert',
'position':'before',
'content':'<img src="image-url" alt="New image from a URL" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the bottom of the list</li>'
}
]
Request with binary content
The following example shows a PATCH request that includes binary data. This multi-part request format requires a "Commands" part that uses the application/json content type. Typically, part names are strings appended with the current time in milliseconds or a random GUID.
PATCH https://www.onenote.com/api/v1.0/me/notes/pages/{page-id}/content
Content-Type: multipart/form-data; boundary=PartBoundary123
Authorization: Bearer {token}
--PartBoundary123
Content-Disposition: form-data; name="Commands"
Content-Type: application/json
[
{
'target':'img:{2998967e-69b3-413f-a221-c1a3b5cbe0fc}{42}',
'action':'replace',
'content':'<img src="name:image-part-name" alt="New binary image" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the bottom of the list</li>'
}
]
--PartBoundary123
Content-Disposition: form-data; name="image-part-name"
Content-Type: image/png
... binary image data ...
--PartBoundary123--
To update page content, you’ll need to pass one of the following permission levels when you authenticate the user:
-
office.onenote_update to update any page in the user’s OneNote notebooks.
-
office.onenote_update_by_app to update only pages created by the app.
For more information about how permission scopes work, see OneNote permission scopes.
The following information applies to PATCH requests and responses.
|
Request data |
Description |
|---|---|
|
SSL/TLS HTTPS protocol |
All requests use the SSL/TLS HTTPS protocol. |
|
Authorization header |
All requests require an Authorization header with the value Bearer token, where token is a valid OAuth token provided to the app based on the user's credentials and access rights. For more information, see Authenticate the user for the OneNote API. |
|
Content type |
The application/json content type, or a multipart/form-data request with a "Commands" part that uses the application/json content type (see examples). If the content contains binary data, send a multi-part request. |
|
Response data |
Description |
|---|---|
|
Success code |
A 204 HTTP status code. No JSON data is returned for a PATCH request. |
|
Errors |
If the update request fails, the API returns errors in the api.diagnostics object in the response body. The request will fail if:
|
|
X-CorrelationId |
An X-header with a GUID that uniquely identifies the request. You can use this value along with the value of the Date header to troubleshoot problems with Microsoft support. |
Note