OneNote connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your OneNote credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

   Dashboard setup steps

   Register your Scalekit environment with the Microsoft OneNote connector so Scalekit handles the authentication flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:

   1. Create the OneNote connection in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Search for OneNote and click Create.

        

      • In the Configure OneNote Connection dialog, copy the Redirect URI. You will need this when registering your app in Azure.

        

   2. Register an application in Azure

      • Sign into portal.azure.com and go to Microsoft Entra ID → App registrations.

        

      • Click New registration. Enter a name for your app (for example, “Scalekit_Agent_Actions”).

      • Under Supported account types, select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts.

      • Under Redirect URI, select Web and paste the redirect URI you copied from the Scalekit dashboard. Click Register.

        

   3. Get your client credentials

      • From the app’s Overview page, copy the Application (client) ID.

        

      • Go to Certificates & secrets in the left sidebar, then click + New client secret.

        

      • Enter a description, set an expiry period, and click Add. Copy the secret Value immediately — it is only shown once.

        

   4. Add credentials in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections and open the OneNote connection you created.

      • Enter your credentials:

        • Client ID — the Application (client) ID from the Azure app overview
        • Client Secret — the secret value from Certificates & secrets
        • Scopes — select the permissions your app needs (for example, Notes.ReadWrite, User.Read, email, openid, profile, offline_access). See Microsoft Graph permissions reference for the full list.

      • Click Save.

4. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'onenote'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize OneNote:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'onenote_list_notebooks',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "onenote"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize OneNote:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="onenote_list_notebooks",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Update page content — Apply a single patchContentCommand to an existing OneNote page’s content, per the Graph OneNote page-update semantics (a JSON array containing one command object with target/action/position/content)
• Search pages — Search all of the signed-in user’s OneNote pages (across every notebook and section) for pages whose title contains the given text
• List sections, section groups, pages — List the OneNote sections (onenoteSection objects) inside a specific notebook
• Get page content — Retrieve the full HTML content of a OneNote page by page ID
• Delete page — Permanently delete a OneNote page by page ID
• Create section group, section, page — Create a new section group directly inside the specified notebook

Common workflows

Proxy API call

Node.js

const result = await actions.request({
  connectionName: 'onenote',
  identifier: 'user_123',
  path: '/v1.0/me/onenote/notebooks',
  method: 'GET',
});
console.log(result);

Python

result = actions.request(
    connection_name='onenote',
    identifier='user_123',
    path="/v1.0/me/onenote/notebooks",
    method="GET"
)
print(result)

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

onenote_copy_page#Copy an existing OneNote page into a different section (including a section in a different notebook). This is an asynchronous Graph operation: a successful call returns 202 Accepted immediately with an Operation-Location header rather than the copied page itself; the copy completes shortly afterward in the background. Requires Notes.Create or Notes.ReadWrite scope.3 params▾

Copy an existing OneNote page into a different section (including a section in a different notebook). This is an asynchronous Graph operation: a successful call returns 202 Accepted immediately with an Operation-Location header rather than the copied page itself; the copy completes shortly afterward in the background. Requires Notes.Create or Notes.ReadWrite scope.

NameTypeRequiredDescription

page_idstringrequiredThe unique ID of the OneNote page to copy. Obtain page IDs from onenote_list_pages, onenote_search_pages, or onenote_create_page.

target_section_idstringrequiredThe unique ID of the destination section to copy the page into. Obtain section IDs from onenote_list_sections or onenote_create_section.

group_idstringoptionalThe ID of the Microsoft 365 group that owns the destination section, if the destination section belongs to a group notebook rather than the signed-in user's own notebooks.

onenote_create_notebook#Create a new OneNote notebook for the signed-in user. Notebook names must be unique within the user's OneNote, cannot exceed 128 characters, and cannot contain the characters ?*/:<>|'". Returns the new notebook object including its id and sectionsUrl. Requires Notes.Create or Notes.ReadWrite scope.1 param▾

Create a new OneNote notebook for the signed-in user. Notebook names must be unique within the user's OneNote, cannot exceed 128 characters, and cannot contain the characters ?*/:<>|'". Returns the new notebook object including its id and sectionsUrl. Requires Notes.Create or Notes.ReadWrite scope.

NameTypeRequiredDescription

display_namestringrequiredThe display name for the new notebook. Must be unique among the user's notebooks, 128 characters or fewer, and cannot contain the characters ?*/:<>|'".

onenote_create_page#Create a new OneNote page in the specified section by posting well-formed HTML directly as the request body. Content-Type is text/html (application/xhtml+xml is also accepted by the Graph API) — the body must be valid XHTML-compliant markup (properly closed/nested tags), not JSON. Use a <title> element inside <head> to set the page title, and a <meta name="created" content="..."/> tag to set the creation date. This tool only supports plain HTML (including remote image URLs); pages that embed binary image/file data require a multipart/form-data request, which is not supported by this tool. Requires Notes.Create or Notes.ReadWrite scope.2 params▾

Create a new OneNote page in the specified section by posting well-formed HTML directly as the request body. Content-Type is text/html (application/xhtml+xml is also accepted by the Graph API) — the body must be valid XHTML-compliant markup (properly closed/nested tags), not JSON. Use a <title> element inside <head> to set the page title, and a <meta name="created" content="..."/> tag to set the creation date. This tool only supports plain HTML (including remote image URLs); pages that embed binary image/file data require a multipart/form-data request, which is not supported by this tool. Requires Notes.Create or Notes.ReadWrite scope.

NameTypeRequiredDescription

html_contentstringrequiredWell-formed XHTML-compliant HTML for the new page, including the <html>, <head>, and <body> elements. Example: "<!DOCTYPE html><html><head><title>Meeting Notes</title></head><body><p>Agenda items...</p></body></html>". Remote image URLs are allowed in <img src="https://...">; embedded binary data is not supported by this tool.

section_idstringrequiredThe unique ID of the section in which to create the new page. Obtain section IDs from onenote_list_sections or onenote_create_section.

onenote_create_section#Create a new OneNote section inside the specified notebook. Section names must be unique within the same hierarchy level, cannot exceed 50 characters, and cannot contain the characters ?*/:<>|'%~. Returns the new onenoteSection object including its id and pagesUrl. Requires Notes.Create or Notes.ReadWrite scope.2 params▾

Create a new OneNote section inside the specified notebook. Section names must be unique within the same hierarchy level, cannot exceed 50 characters, and cannot contain the characters ?*/:<>|'%~. Returns the new onenoteSection object including its id and pagesUrl. Requires Notes.Create or Notes.ReadWrite scope.

NameTypeRequiredDescription

display_namestringrequiredThe display name for the new section. Must be unique among the notebook's other sections, 50 characters or fewer, and cannot contain the characters ?*/:<>|'%~.

notebook_idstringrequiredThe unique ID of the notebook in which to create the new section. Obtain notebook IDs from onenote_list_notebooks or onenote_create_notebook.

onenote_create_section_group#Create a new section group directly inside the specified notebook. A section group is a folder-like container that can hold its own sections and nested section groups — useful for organizing many sections under one notebook. Section group names must be unique within the same hierarchy level, cannot exceed 50 characters, and cannot contain the characters ?*/:<>|'%~. Returns the new sectionGroup object including its id, sectionsUrl, and sectionGroupsUrl. Requires Notes.Create or Notes.ReadWrite scope.2 params▾

Create a new section group directly inside the specified notebook. A section group is a folder-like container that can hold its own sections and nested section groups — useful for organizing many sections under one notebook. Section group names must be unique within the same hierarchy level, cannot exceed 50 characters, and cannot contain the characters ?*/:<>|'%~. Returns the new sectionGroup object including its id, sectionsUrl, and sectionGroupsUrl. Requires Notes.Create or Notes.ReadWrite scope.

NameTypeRequiredDescription

display_namestringrequiredThe display name for the new section group. Must be unique among the notebook's other section groups, 50 characters or fewer, and cannot contain the characters ?*/:<>|'%~.

notebook_idstringrequiredThe unique ID of the notebook in which to create the new section group. Obtain notebook IDs from onenote_list_notebooks or onenote_create_notebook.

onenote_delete_page#Permanently delete a OneNote page by page ID. This action cannot be undone through the API. On success, returns 204 No Content. Requires Notes.ReadWrite scope.1 param▾

Permanently delete a OneNote page by page ID. This action cannot be undone through the API. On success, returns 204 No Content. Requires Notes.ReadWrite scope.

NameTypeRequiredDescription

page_idstringrequiredThe unique ID of the OneNote page to delete. Obtain page IDs from onenote_list_pages, onenote_search_pages, or onenote_create_page.

onenote_get_page_content#Retrieve the full HTML content of a OneNote page by page ID. Returns raw HTML (Content-Type: text/html), not JSON — the response body is the page's markup, including any embedded images as data URIs or object references. Set include_ids to true to have the server annotate elements with data-id attributes, which are required as the "target" of a subsequent onenote_update_page_content call. Requires Notes.Read, Notes.Create, or Notes.ReadWrite scope.2 params▾

Retrieve the full HTML content of a OneNote page by page ID. Returns raw HTML (Content-Type: text/html), not JSON — the response body is the page's markup, including any embedded images as data URIs or object references. Set include_ids to true to have the server annotate elements with data-id attributes, which are required as the "target" of a subsequent onenote_update_page_content call. Requires Notes.Read, Notes.Create, or Notes.ReadWrite scope.

NameTypeRequiredDescription

page_idstringrequiredThe unique ID of the OneNote page whose content to retrieve. Obtain page IDs from onenote_list_pages, onenote_search_pages, or onenote_create_page.

include_idsbooleanoptionalWhen true, the returned HTML includes data-id attributes on elements so they can be targeted by a later onenote_update_page_content call. Default: false.

onenote_list_notebooks#List all OneNote notebooks owned by or shared with the signed-in user. Returns each notebook's id, displayName, createdDateTime, lastModifiedDateTime, userRole, isShared, sectionsUrl, sectionGroupsUrl, and links (oneNoteWebUrl/oneNoteClientUrl). Default sort order is displayName ascending. Requires Notes.Create, Notes.Read, or Notes.ReadWrite scope.3 params▾

List all OneNote notebooks owned by or shared with the signed-in user. Returns each notebook's id, displayName, createdDateTime, lastModifiedDateTime, userRole, isShared, sectionsUrl, sectionGroupsUrl, and links (oneNoteWebUrl/oneNoteClientUrl). Default sort order is displayName ascending. Requires Notes.Create, Notes.Read, or Notes.ReadWrite scope.

NameTypeRequiredDescription

orderbystringoptionalValue for the OData $orderby query parameter — the property to sort results by. Example: "displayName desc". The default sort order is "displayName asc".

selectstringoptionalValue for the OData $select query parameter — a comma-separated list of notebook properties to return. Example: "id,displayName,lastModifiedDateTime" reduces response payload.

topintegeroptionalValue for the OData $top query parameter — the maximum number of notebooks to return per page. Accepts values 1–999.

onenote_list_pages#List the OneNote pages inside a specific section. Returns each page's id, title, createdByAppId, contentUrl, links, and lastModifiedDateTime. By default returns the top 20 pages ordered by lastModifiedDateTime descending; the maximum for top is 100. Use onenote_get_page_content to fetch a page's HTML body. Requires Notes.Read, Notes.Create, or Notes.ReadWrite scope.5 params▾

List the OneNote pages inside a specific section. Returns each page's id, title, createdByAppId, contentUrl, links, and lastModifiedDateTime. By default returns the top 20 pages ordered by lastModifiedDateTime descending; the maximum for top is 100. Use onenote_get_page_content to fetch a page's HTML body. Requires Notes.Read, Notes.Create, or Notes.ReadWrite scope.

NameTypeRequiredDescription

section_idstringrequiredThe unique ID of the section whose pages to list. Obtain section IDs from onenote_list_sections or onenote_create_section.

filterstringoptionalValue for the OData $filter query parameter — an expression to narrow results. Example: "contains(tolower(title),'standup')".

orderbystringoptionalValue for the OData $orderby query parameter — the property to sort results by. Example: "title asc". The default sort order is "lastModifiedDateTime desc".

selectstringoptionalValue for the OData $select query parameter — a comma-separated list of page properties to return. Example: "id,title,lastModifiedDateTime" reduces response payload.

topintegeroptionalValue for the OData $top query parameter — the maximum number of pages to return per page of results (default: 20). The server-enforced maximum is 100.

onenote_list_section_groups#List the OneNote section groups (sectionGroup objects) inside a specific notebook. A section group is a folder-like container that can hold its own sections and nested section groups. Returns each section group's id, displayName, sectionsUrl, sectionGroupsUrl, createdDateTime, and lastModifiedDateTime. The default sort order is displayName asc. Requires Notes.Create, Notes.Read, or Notes.ReadWrite scope.5 params▾

List the OneNote section groups (sectionGroup objects) inside a specific notebook. A section group is a folder-like container that can hold its own sections and nested section groups. Returns each section group's id, displayName, sectionsUrl, sectionGroupsUrl, createdDateTime, and lastModifiedDateTime. The default sort order is displayName asc. Requires Notes.Create, Notes.Read, or Notes.ReadWrite scope.

NameTypeRequiredDescription

notebook_idstringrequiredThe unique ID of the notebook whose section groups to list. Obtain notebook IDs from onenote_list_notebooks or onenote_create_notebook.

filterstringoptionalValue for the OData $filter query parameter — an expression to narrow results. Example: "displayName eq 'Archived'".

orderbystringoptionalValue for the OData $orderby query parameter — the property to sort results by. Example: "lastModifiedDateTime desc". The default sort order is "displayName asc".

selectstringoptionalValue for the OData $select query parameter — a comma-separated list of section group properties to return. Example: "id,displayName,sectionsUrl" reduces response payload.

topintegeroptionalValue for the OData $top query parameter — the maximum number of section groups to return per page. Accepts values 1–999.

onenote_list_sections#List the OneNote sections (onenoteSection objects) inside a specific notebook. Returns each section's id, displayName, isDefault, pagesUrl, createdDateTime, and lastModifiedDateTime. The default response expands parentNotebook. Requires Notes.Create, Notes.Read, or Notes.ReadWrite scope.5 params▾

List the OneNote sections (onenoteSection objects) inside a specific notebook. Returns each section's id, displayName, isDefault, pagesUrl, createdDateTime, and lastModifiedDateTime. The default response expands parentNotebook. Requires Notes.Create, Notes.Read, or Notes.ReadWrite scope.

NameTypeRequiredDescription

notebook_idstringrequiredThe unique ID of the notebook whose sections to list. Obtain notebook IDs from onenote_list_notebooks or onenote_create_notebook.

filterstringoptionalValue for the OData $filter query parameter — an expression to narrow results. Example: "displayName eq 'Meeting Notes'".

orderbystringoptionalValue for the OData $orderby query parameter — the property to sort results by. Example: "displayName asc" or "lastModifiedDateTime desc". The default sort order is "displayName asc".

selectstringoptionalValue for the OData $select query parameter — a comma-separated list of section properties to return. Example: "id,displayName,pagesUrl" reduces response payload.

topintegeroptionalValue for the OData $top query parameter — the maximum number of sections to return per page. Accepts values 1–999.

onenote_search_pages#Search all of the signed-in user's OneNote pages (across every notebook and section) for pages whose title contains the given text. Implemented as an OData $filter using contains(tolower(title),'...'), so matching is case-insensitive as long as the query is passed in lowercase. To list pages within one specific section instead, use onenote_list_pages. Requires Notes.Read, Notes.Create, or Notes.ReadWrite scope.3 params▾

Search all of the signed-in user's OneNote pages (across every notebook and section) for pages whose title contains the given text. Implemented as an OData $filter using contains(tolower(title),'...'), so matching is case-insensitive as long as the query is passed in lowercase. To list pages within one specific section instead, use onenote_list_pages. Requires Notes.Read, Notes.Create, or Notes.ReadWrite scope.

NameTypeRequiredDescription

querystringrequiredText to search for in page titles. Pass lowercase for reliable matching, since the filter compares against a lowercased title (e.g. "standup" matches "Weekly Standup Notes").

selectstringoptionalValue for the OData $select query parameter — a comma-separated list of page properties to return. Example: "id,title,parentSection" reduces response payload.

topintegeroptionalValue for the OData $top query parameter — the maximum number of matching pages to return. The server-enforced maximum is 100.

onenote_update_page_content#Apply a single patchContentCommand to an existing OneNote page's content, per the Graph OneNote page-update semantics (a JSON array containing one command object with target/action/position/content). target must be the #<data-id> or generated <id> of an element from a onenote_get_page_content call made with include_ids=true, or the literal keyword "body" or "title". action is one of replace, append, delete, insert, or prepend. content must be well-formed HTML and is required for every action except delete. Binary image/file data in content is not supported by this tool (it would require a multipart/form-data request). On success, returns 204 No Content. Requires Notes.ReadWrite scope.5 params▾

Apply a single patchContentCommand to an existing OneNote page's content, per the Graph OneNote page-update semantics (a JSON array containing one command object with target/action/position/content). target must be the #<data-id> or generated <id> of an element from a onenote_get_page_content call made with include_ids=true, or the literal keyword "body" or "title". action is one of replace, append, delete, insert, or prepend. content must be well-formed HTML and is required for every action except delete. Binary image/file data in content is not supported by this tool (it would require a multipart/form-data request). On success, returns 204 No Content. Requires Notes.ReadWrite scope.

NameTypeRequiredDescription

actionstringrequiredThe action to perform on the target element.

page_idstringrequiredThe unique ID of the OneNote page to update. Obtain page IDs from onenote_list_pages, onenote_search_pages, or onenote_create_page.

targetstringrequiredThe element to update: the #<data-id> or generated <id> of an element (from a onenote_get_page_content call with include_ids=true), or the literal keyword "body" or "title".

contentstringoptionalA string of well-formed HTML to add to the page. Required for the replace, append, insert, and prepend actions; ignored for delete.

positionstringoptionalThe location to add the supplied content, relative to the target element. Possible values: after (default) or before.