# Read Apple Notes with a Scoped Mac Helper

Canonical: https://figment.so/blog/apple-notes-export-integration

Apple Notes has no public REST endpoint, no CalDAV feed, and no developer SDK that runs outside the user's device. The documented native path to Notes content on macOS is the **Notes scripting dictionary** — an Apple Events interface the Notes app exposes to authorized processes on the same Mac.

## Why there is no Apple Notes REST API

Apple Calendar and Contacts both use open protocols — CalDAV and CardDAV — that iCloud serves over HTTP. Notes has neither. Apple has not published an HTTP or OAuth endpoint for Notes content, and there is no developer-accessible iCloud Notes web API.

What exists instead is Apple Events: macOS's inter-app messaging protocol. Any process with the right entitlement and a user-granted Automation permission can send an AppleScript command to the Notes app and receive a structured reply. The query runs entirely on-device — no network request leaves the machine when a helper reads Notes this way.

## The Notes scripting dictionary

The Notes scripting dictionary exposes a five-level hierarchy:

**Application → Account → Folder → Note → Attachment**

**Accounts** correspond to storage locations. An iCloud account syncs across a user's Apple devices. An account whose name contains "On My Mac" stores notes locally only. If iCloud Notes is enabled in System Settings, the iCloud account appears alongside any local account. List all accounts before targeting one — the name can vary between machines.

**Folders** have a `name`, `id`, and `container` (parent account or folder) and can contain both notes and nested subfolders.

**Notes** expose these properties:

| Property | Type |
|---|---|
| `name` | text (read-only) |
| `id` | text (read-only) |
| `body` | HTML text (read-write) |
| `creation date` | date (read-only) |
| `modification date` | date (read-only) |
| `container` | account or folder (read-only) |

The `body` property returns the full note content as HTML. Rich formatting — bold text, lists, headings, checklists, inline colors — is encoded in that markup. Parse it as HTML rather than plain text. Write operations against `body` can silently destroy formatting if content is not carefully escaped and round-tripped.

This integration design shows the traversal pattern. In production, list all accounts first rather than hard-coding a name, and recurse into subfolders to reach notes nested below the top level:

```applescript
-- List account names present on this Mac first:
--   get name of every account of application "Notes"
-- Use the returned name. Do not hard-code "iCloud".

tell application "Notes"
  set targetAccount to account "iCloud"  -- substitute actual account name
  repeat with f in (get folders of targetAccount)
    repeat with n in (get notes of f)
      -- name of n       → note title
      -- id of n         → stable identifier
      -- body of n       → full HTML content
      -- creation date of n
      -- modification date of n
    end repeat
    -- Recurse: (get folders of f) to reach nested subfolders
  end repeat
end tell
```

This is a design example. Run it on a Mac where Notes is signed in and your helper process has been granted Automation permission for the Notes app in System Settings → Privacy & Security → Automation.

## Locked notes

Locked notes are the most significant access boundary to understand before you build.

Apple Notes lets users lock individual notes with a custom Notes password, the Mac login password (requires two-factor authentication and iCloud Keychain), or Touch ID on a supported Mac. The lock is per-note, not per-folder or per-account.

When a note is locked, its `body` is not accessible via Apple Events until the user unlocks it on the Mac. The note still appears in the account and folder hierarchy — `name` and `id` are readable — but the body content is withheld. Build your integration to surface that a note is locked rather than silently skipping it or treating it as empty.

One additional boundary: a note locked with the Mac login password cannot be viewed on iCloud.com. A note locked with a custom Notes password can be viewed on iCloud.com after manual password entry. In both cases the note remains in the hierarchy; only the content is withheld.

## Attachments and cloud-only assets

Attachments are elements of the Note object in the scripting dictionary, separate from the HTML body. They are retrieved independently rather than parsed out of the markup.

iCloud may keep attachment binaries in cloud storage rather than on the local Mac — particularly for older notes or large files on a Mac with limited storage. When a binary has not been downloaded locally, trigger iCloud sync before attempting to access it.

An inline image in a note body may appear as a data URI inside the HTML or as a separate attachment object, depending on how the note was created and the macOS version. A robust parser should handle both representations.

## Export: Markdown and PDF on macOS 26

macOS 26 adds Markdown export to the Notes app. To export a single note, open it and choose **File → Export as → Markdown**. PDF export — **File → Export as → PDF** — is also available. Both are user-initiated; there is no programmatic batch-export path in the Notes UI. ([Apple support: Import, export, and print notes on Mac](https://support.apple.com/guide/notes/import-export-and-print-notes-not201900c07/4.13/mac/26))

For programmatic bulk access, the scripting dictionary remains the documented path. The Markdown export is well suited for one-off handoffs to writing tools and other Markdown-aware workflows.

## iCloud sync and local accounts

A Mac helper reads whichever accounts and notes are present on the connected Mac at query time. iCloud Notes sync must be enabled in System Settings under iCloud for iCloud notes to appear. With sync off, only local "On My Mac" notes are visible. iCloud Notes syncs across iPhone, iPad, Mac, and Apple Vision Pro when enabled on each device. ([Apple: Use Notes with iCloud](https://support.apple.com/en-gb/guide/icloud/mm203ae070a2/icloud))

An "On My Mac" account is local to that machine only. Notes in iCloud appear on all signed-in devices when sync is active. Querying a Mac where sync is disabled or temporarily offline returns only locally stored content.

## Get started with Figment Apple Connect

Figment Apple Connect provides a user-approved, scoped connection to Apple data from a hosted Mac. The iMessage REST API is available today, along with a synthetic read-only sandbox for Contacts, Calendar, and Reminders. Notes scripting is a developer-owned integration design; there is no current Figment customer connector endpoint for Notes.

Developers working with a Figment-hosted Mac can apply the design above on the same connected Mac where the iMessage integration runs. For the full grant model — scopes, approvals, and revocation — see [OAuth for iCloud: Connect Apple Data to Your App](/oauth-for-icloud).

**[Connect Apple Account](/apple-connect/developers)** to register your app and explore the available iMessage and sandbox integrations.