Copy notebooks, sections, and pages

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.

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

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.

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"
}

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

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.

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

See also

• Get OneNote content and structure
• Create OneNote pages
• OneNote development
• OneNote Dev Center
• OneNote Developer Blog
• OneNote development questions on Stack Overflow
• OneNote GitHub repos