Copy notebooks, sections, and pages

  • Article

Applies to: Enterprise notebooks on Office 365 only

To copy a OneNote notebook, section, or page, you send a POST request to the respective copy action endpoint. For example:

POST ../notes/sections/{id}/copyToNotebook

Send a JSON copy object in the message body. If the request is successful, the OneNote API returns a 202 HTTP status code and an Operation-Location header. Then, you can poll the operation endpoint for the result.

Note

Copy functionality is currently supported for Office 365 personal, site, and unified group notebooks, but not for consumer notebooks on OneDrive.

Construct the request URI

  1. To construct the request URI, start with the service root URL for your platform:

    Notebooks on OneDrive for Business

    https://www.onenote.com/api/v1.0/me/notes/

    https://www.onenote.com/api/v1.0/users/{id}/notes/

    SharePoint site notebooks

    https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

    Unified group notebooks

    https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/

  2. Append the respective copy action endpoint:

    Copy a page to a section

    ../pages/{id}/copyToSection

    Copy a section to a notebook

    ../sections/{id}/copyToNotebook

    Copy a section to a section group

    ../sections/{id}/copyToSectionGroup

    Copy a notebook

    ../notebooks/{id}/copyNotebook

The notebook is copied to the Notebooks folder in the destination Documents library. The Notebooks folder is created if it doesn't exist.

Your full request URI will look like one of these examples:

https://www.onenote.com/api/v1.0/me/notes/sections/{id}/copyToNotebook

https://www.onenote.com/api/v1.0/users/{id}/notes/sections/{id}/copytosectiongroup

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/pages/{id}/copyToSection

https://www.onenote.com/api/v1.0/groups/{id}/notes/notebooks/{id}/copyNotebook

Note

Learn more about the service root URL.

Construct the message body

In the message body, send a JSON object that contains the parameters that your operation needs. It's okay to send an empty body if no parameters are needed.

Parameter Description
id The ID of the destination notebook or section group (for sections); or the ID of the destination section (for pages).

Used with copyToNotebook, copyToSectionGroup, and copyToSection only.
siteCollectionId The ID of the SharePoint site collection that contains the site to copy the item to.

Used with siteId, and used only when copying to a SharePoint site.
siteId The ID of the SharePoint site to copy the item to.

Used with siteCollectionId, and used only when copying to a SharePoint site.
groupId The ID of the group to copy the item to.

Used only when copying to a unified group.
renameAs The name of the copy.

Used with copyNotebook, copyToNotebook, and copyToSectionGroup only. Defaults to the name of the existing item.

Learn how to get notebook, section group, and section IDs and get site collection and site IDs. For information about getting group IDs, see the Azure AD Graph API documentation.

Example flow for a copy operation

First you send a POST request to the copy action on the item you want to copy. You can copy from notebooks that the user has access to (owned or shared) as long as the source and destination are in the same tenant.

The following example copies a personal notebook to a SharePoint team site. The request doesn't include the renameAs parameter, so the new notebook uses the existing name.

POST https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923/copyNotebook
Authorization: Bearer {token}
Content-Type: application/json 

{
  "siteCollectionId":"0f6dbd5d-d179-49c6-aabd-15830ea90ca8",
  "siteId":"3ba679cf-4470-466e-bc20-053bdfec75bf"
}

Note

Copy operations honor the source notebook's permissions, so the authenticated user must be able to access the source notebook in order to copy it. However, copies don't retain the permissions of the source. The copy has permissions as though the user just created it.

If the call is successful, the OneNote API returns a 202 status code and an Operation-Location header. Here's an excerpt of the response:

HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923
X-CorrelationId: 8a211d7c-220b-413d-8022-9a946499fcfb
Operation-Location: https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
...

Then you poll the Operation-Location endpoint to get the status of the copy operation:

GET https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
Authorization: Bearer {token}
Accept: application/json

The OneNote API returns an OperationModel object that shows the current status. The following example response is returned when the status is completed.

{
  "@odata.context":"https://www.onenote.com/api/beta/$metadata#myOrganization/siteCollections('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/sites('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/notes/operations/$entity",
  "id":"copy-1c5be75c-e7db-4219-8145-a2d6c3f171a33ec9f3da-2b24-4fb1-a776-fe8c8cd1410f",
  "status":"completed",
  "createdDateTime":"2015-09-16T17:32:07.048Z",
  "lastActionDateTime":"2015-09-16T17:32:17.7777639Z",
  "resourceLocation":"https://www.onenote.com/api/v1.0/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/3ba679cf-4470-466e-bc20-053bdfec75bf/notes/notebooks/1-bde29eeb-66e2-4fed-8d48-51cd1bf32511",
  "resourceId":null,"
  "error":null
}

The status can be completed, running, or failed.

  • If completed, the resourceLocation property contains the resource endpoint for the new copy.
  • If running, the percentComplete property shows the approximate percentage completed.
  • If failed, the error and @api.diagnostics properties provide error information.

You can poll the operation endpoint until the operation has completed or failed.

Request and response information

Request data Description
Protocol All requests use the SSL/TLS HTTPS protocol.
Authorization header Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

If missing or invalid, the request fails with a 401 status code. See Authentication and permissions.
Content-Type header application/json
Accept header application/json


Response data Description
Success code A 202 status HTTP status code.
Operation-Location header The URL to poll for the status of the operation.

Polling the operation endpoint returns an OperationModel object that contains the status of the operation and other information.
X-CorrelationId header A GUID that uniquely identifies the request. You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

Construct the OneNote service root URL

The OneNote service root URL uses the following format for all calls to the OneNote API.

https://www.onenote.com/api/{version}/{location}/notes/

The version segment in the URL represents the version of the OneNote API that you want to use.

  • Use v1.0 for stable production code.

  • Use beta to try out a feature that's in development. Features and functionality in beta may change, so you shouldn't use it in your production code.

The location segment in the URL represents the location of the notebooks that you want to access:

  • Notebooks on OneDrive for Business

    • Use me for OneNote content that’s owned by the current user.

    • Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. Use the Azure AD Graph API to get user IDs.

  • SharePoint site notebooks

    • Team sites and other SharePoint sites can contain OneNote notebooks in their document libraries.

    • Use myOrganization/siteCollections/{id}/sites/{id} for OneNote content in a site in the tenant that the current user is logged into. Only the current tenant is supported, accessed using the myOrganization keyword. Learn how to get site IDs.

  • Unified group notebooks

    • Unified groups (also called Office 365 groups) are part of the Office 365 connected experience. Group members can share notebooks, files, and email.

    • Use myOrganization/groups/{id} for OneNote content in the specified group that the current user is a member of. Unified groups are the only supported group type. Use the Azure AD Graph API to get group IDs.

Use the FromUrl method to get the site collection and site IDs

You can use the FromUrl method to get the site collection and site IDs for a specified absolute site URL. You should make this call only when needed, and then store the values for future use.

The format of the site URL depends on your configuration, for example https://domain.sharepoint.com/site-a or https://domain.com/sites/site-a.

Example request

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')

Authorization: Bearer {token}

Accept: application/json

Example response

{"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.SiteMetadata", "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5", "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"}

Requirements for using FromUrl and working with SharePoint site notebooks:

  • You can only create OneNote notebooks, section groups, sections, and pages on sites that have a default document library. (Some site templates don't create a default document library.) However, GET requests return OneNote content from all document libraries on the site.

  • The OneNote service root URL is immutable, meaning you can't use a SharePoint REST API site path and then tack the notes endpoint onto it.

  • The user on whose behalf you're calling must be a member of the site.

  • FromUrl works only with sites that have been indexed. It may take several hours to index a new site.

Permissions

To copy OneNote notebooks, sections, and pages, you'll need to request appropriate permissions. Choose the lowest level of permissions that your app needs to do its work.

Platform Permission scope
Consumer office.onenote_create, office.onenote_update_by_app, office.onenote_update
Enterprise Notes.Create, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, Notes.ReadWrite.All

For more information about permission scopes and how they work, see OneNote permission scopes.

See also