Capture to OneNote from iPhone, iPad, or Mac

Choose the Shortcut you want

These are the four Shortcut designs for the project. The iCloud download URLs have not been supplied yet, but the manual instructions below let you build both Quick Inbox and Append to OneNote now.

Before you install or build a Shortcut

1. Finish Steps 1–4 of setup

   Your database must be connected, Microsoft must be connected, and a default OneNote section must be selected.

2. Create your Shortcut API key in Step 5

   The key begins with ons_ and is displayed only once. Save it in your password manager before leaving the page.

3. Know your deployment address

   This is the public address of your copy of OneNote System, such as https://my-onenote-system.vercel.app. It is not onenotesystem.erinskidds.com unless that is the installation you control.

4. Open Apple's Shortcuts app

   Shortcuts is included on current iPhone, iPad, and Mac systems. Apple's Shortcuts User Guide ↗ explains the editor and running shortcuts.

How to configure a downloaded Shortcut

When the iCloud links are published, opening one will show Apple's preview before anything is added. Review its actions, choose Add Shortcut, then answer its setup questions:

Build the Quick Inbox Shortcut manually

You can use this today while the downloadable iCloud links are being prepared. Apple occasionally changes labels in the Shortcuts editor, but the actions and values remain the same.

1. Create a blank Shortcut

   Open Shortcuts, press +, choose New Shortcut, and name it Quick Inbox to OneNote.

2. Ask for the page title

   Add Ask for Input. Set the prompt to OneNote page title and leave the input type as Text. Rename its result variable to Page Title if you want the later actions to be easier to read.

3. Ask for the note

   Add a second Ask for Input. Set its prompt to What do you want to save?. Its output is the note text.

4. Add your API address

   Add the URL action. Enter your deployment address followed by /api/capture. For example: https://my-queue.vercel.app/api/capture.

5. Send the request

   Add Get Contents of URL. Expand its options and set Method to POST. Under Headers add Authorization with the value Bearer YOUR_API_KEY. Keep the space after Bearer.

6. Add the JSON fields

   Set Request Body to JSON. Add a Text field named title and insert the first Ask for Input variable. Add a Text field named content and insert the second Ask for Input variable. The field names must be lowercase exactly as shown.

7. Show the result and test

   Add Show Result using the result of Get Contents of URL. Run the Shortcut. A successful request returns "ok": true, and the new page should appear in the OneNote section chosen during setup.

Apple also provides an official guide to using web APIs in Shortcuts ↗.

What the Shortcut sends

POST https://YOUR-ONENOTE-SYSTEM-DOMAIN/api/capture
Authorization: Bearer ons_YOUR_PRIVATE_KEY
Content-Type: application/json

{
  "title": "Page title",
  "content": "The text to save",
  "url": "https://optional-source.example"
}

The title field is optional and defaults to “Untitled capture.” The content field accepts plain text. The optional url field must start with http:// or https://.

Build the Append to OneNote Shortcut

This version adds text to a page that already exists in the default section selected during setup.

1. Create a blank Shortcut

   Open Shortcuts, press +, choose New Shortcut, and name it Append to OneNote.

2. Ask which page to update

   Add Ask for Input with the prompt Exact OneNote page title. The title is matched in your default section.

3. Ask what to append

   Add another Ask for Input with the prompt What do you want to add?.

4. Add the append API address

   Add a URL action using your deployment address followed by /api/append.

5. Send the authenticated request

   Add Get Contents of URL, set the method to POST, and add an Authorization header whose value is Bearer YOUR_API_KEY.

6. Add the JSON fields

   Set the request body to JSON. Add pageTitle using the first input and content using the second input. If duplicate titles exist, use the page's Microsoft Graph ID in a pageId field instead.

7. Test the append

   Add Show Result, run the Shortcut, and confirm that it returns "ok": true. The text should appear at the end of the existing page.

What the Append Shortcut sends

POST https://YOUR-ONENOTE-SYSTEM-DOMAIN/api/append
Authorization: Bearer ons_YOUR_PRIVATE_KEY
Content-Type: application/json

{
  "pageTitle": "Quick Inbox",
  "content": "The text to add",
  "url": "https://optional-source.example"
}

content is required and accepts up to 100,000 plain-text characters. Supply either pageTitle or pageId. Title lookup is limited to your selected default section; a page ID can identify a page in any section available to the connected Microsoft account.

Shortcut troubleshooting

For server and Microsoft errors, continue with the full troubleshooting guide →