Write Note via OpenNote Public API

Write a note to OpenNote using the public API at https://api.opennote.cc/api/v1.

Getting Started

What you need

1. 1. An OpenNote account — download the app from the App Store
2. A Pro subscription — API access is a Pro feature
3. A Personal Access Token (PAT) — generated from the app

Generating an API token

1. 1. Open the OpenNote app
2. Go to Profile → API Tokens
3. Tap Create Token
4. Choose the scopes you need:

1. 5. Set an expiration (default: 90 days, max: 365 days, or never)
2. Copy the token immediately — it starts with milo_pat_v1_ and is only shown once

Setting up the environment variable

Set OPENNOTE_API_TOKEN in your OpenClaw environment:

Option A — OpenClaw config (recommended):

In your OpenClaw settings, add the environment variable:
CODEBLOCK0

Option B — Shell profile (if running locally):
CODEBLOCK1

Add this to your ~/.zshrc or ~/.bashrc to persist it across sessions.

Security:

• - Never commit your token to version control
• The token grants write access to your notes — treat it like a password
• If compromised, revoke it immediately from Profile → API Tokens in the app

Token lifecycle

• - Tokens expire based on the duration you set (default 90 days)
• You can have up to 5 active tokens per account
• Revoke unused tokens from the app at any time
• When a token expires or is revoked, generate a new one and update INLINECODE7
• If you get a 401 INVALID_API_TOKEN error, your token has expired or been revoked

Prerequisites

The token is read from the OPENNOTE_API_TOKEN environment variable. It must have the diaries:write scope. If images will be uploaded, images:write is also required.

Local Cache Files

This skill maintains two local files in the working directory under .opennote/:

• - Labels cache: .opennote/opennote-labels-cache.json — cached user labels
• Note history: .opennote/opennote-history.json — log of all notes written/edited via this skill

Always read these files at the start of every invocation. If they are missing, treat them as empty. If the user asks about previously written notes, consult the history file.

Instructions

Step 1: Load labels (fetch or use cache)

Read .opennote/opennote-labels-cache.json. If it exists and was fetched less than 24 hours ago, use the cached labels.

Expected cache format:
CODEBLOCK2

If the cache is missing, empty, or stale (older than 24 hours), fetch labels from the API:

CODEBLOCK3

Response:
CODEBLOCK4

After fetching, write the result to .opennote/opennote-labels-cache.json with the current timestamp as fetchedAt.

Step 2: Choose a label/category

• - If the user specified a label by name or ID, use that categoryID.
• If the user did NOT specify a label, pick a random label from the cached label list.
• If no labels are cached at all, use category: 0 (no label).

When picking a random label, tell the user which label was selected.

Step 3: Gather note content from the user

Ask the user what they want to write about. Collect:

• - The note text content (required)
• Optional: a title
• Optional: whether they want stickers added
• Optional: whether they want images (user must provide image files)

Step 4: Generate timestamps and fileName

CODEBLOCK5

Step 5: Build the richContent (Quill Delta JSON string)

Build a Quill Delta array of ops, then JSON.stringify() it into the richContent field.

Supported Quill Delta operations

Plain text:
CODEBLOCK6

Newline (required - every Delta must end with at least one):
CODEBLOCK7

Inline styles (on text insert):

• - bold (boolean)
• INLINECODE23 (boolean)
• INLINECODE24 (boolean)
• INLINECODE25 (boolean)
• INLINECODE26 (hex string like "#2a7fff") — use the palette below for best results
• INLINECODE28 (number, typically 2-99; app default is 17)

CODEBLOCK8

Available color palette (36 colors):

Always store the light-mode hex — the app remaps it automatically when rendering in dark mode.

Block/line styles (attached to the newline op after the line):

• - align: "left", "center", INLINECODE68
• INLINECODE69: integer
• INLINECODE70: "ordered", "bullet", "checked", INLINECODE74
• INLINECODE75: INLINECODE76
• INLINECODE77: INLINECODE78

CODEBLOCK9

Image embed:
CODEBLOCK10

If dimensions are unknown:
CODEBLOCK11

Collage embed (multi-image layout):
CODEBLOCK12

Available collage layouts: twoHorizontal (2), bigLeft2Right (3), bigRight2Left (3), threeRow (3), bigLeft2RectRight (3), bigTop2Bottom (3), bigLeftTopRect2Bottom (4), grid2x2 (4)

Divider embed:
CODEBLOCK13

Example richContent value

The API field richContent must be a JSON string (not an object):

CODEBLOCK14

Step 6: Build the content field (plain text)

INLINECODE88 is a plain-text summary used for home screen preview and search. Strip all formatting — just include the text. Do NOT put JSON or markdown here.

Step 7: Build stickerData (optional)

INLINECODE89 is a JSON string (not an object) containing an array of sticker overlay objects. Stickers float on top of the note page and are NOT part of richContent.

Each sticker object:
CODEBLOCK15

Field rules:

• - id: unique string, format INLINECODE92
• INLINECODE93: must be an exact match from the bundled sticker list below
• INLINECODE94, dy: pixel offsets from top-left of note canvas (typical canvas ~390px wide)
• INLINECODE96, normalizedDy: proportional position (0.0–1.0 for dx; dy can exceed 1.0 for long content)
• INLINECODE98: 0.3 to 4.0 (1.0 = default 70px base size)
• INLINECODE99: radians

Example stickerData field value:
CODEBLOCK16

Available sticker asset paths

Kawaii:
CODEBLOCK17

Animals: assets/stickers/animals/001-crocodile.svg through 040-hippopotamus.svg (040 total)

Nature: assets/stickers/nature/001-sunflower.svg through 024-tree.svg (024 total)

Characters: assets/stickers/characters/girl_001-girl.svg through girl_020-girl.svg, hippie_001-hippie.svg through INLINECODE108

Food: assets/stickers/food/misc_001-meat.svg through misc_020-dolphin.svg, k760_001-cat.svg through k760_020-ice_cream.svg, k791_001-cat.svg through INLINECODE114

Cute Life: assets/stickers/cute_life/k678_001-badge.svg through k678_020-vinyl_record.svg, k612_001-teddy_bear.svg through k612_020-yogurt.svg, k155_001-egg_and_bacon.svg through INLINECODE120

Everyday: assets/stickers/everyday/k448_001-cake.svg through k448_020-violin.svg, k450_001-backpack.svg through INLINECODE124

Step 8: Upload images (if any)

If the note includes images, upload each one first:

CODEBLOCK18

Response:
CODEBLOCK19

Use the returned imageName in imageList, richContent image embeds, and optionally diaryCoverImageName.

Image constraints:

• - Supported types: jpg, jpeg, png, gif, webp, heic, heif
• Max size: 15 MB per image
• User storage quota applies

Step 9: Assemble and send the API request

CODEBLOCK20

If the API returns 409 ALREADY_EXISTS, retry with PUT:

CODEBLOCK21

Step 10: Record to note history

After a successful create or update, append an entry to .opennote/opennote-history.json.

Read the existing file first (or start with an empty array [] if it doesn't exist), then append and write back.

Each history entry format:
CODEBLOCK22

Rules for the history:

• - action: either "created" or INLINECODE134
• INLINECODE135: first 150 characters of the plain text INLINECODE136
• INLINECODE137: look up from cached labels, or "No Label" if category is 0
• INLINECODE139: true if stickerData was non-null
• INLINECODE140: true if imageList is non-empty
• For updates, add a new entry with action: "updated" (do not overwrite previous entries)

Step 11: Confirm to the user

Tell the user:

• - The note was created/updated successfully
• The fileName
• Which label was used (and whether it was randomly selected)
• A brief summary of the content

Reading Notes from the API

When the user asks to read, search, or use an existing note as a template, use the read endpoints (requires diaries:read scope on the token).

Note: The diaries:read scope may not yet be available when creating tokens from the app. If you get a 403 INSUFFICIENT_SCOPE error on read endpoints, the token doesn't have this scope. Writing notes and fetching labels will still work.

List notes

CODEBLOCK23

Query parameters (all optional):

• - category — filter by categoryID (integer)
• INLINECODE146 — search in content and title (partial match)
• INLINECODE147 — results per page, 1–200, default 50
• INLINECODE148 — pagination offset, default 0

Response:
CODEBLOCK24

Get a single note

CODEBLOCK25

Looking Up Previous Notes

When the user asks about notes they've previously written (e.g., "what did I write last time?", "find my note about X"), read .opennote/opennote-history.json. You can match by:

• - title (partial match)
• INLINECODE151 (keyword search)
• INLINECODE152 (label name)
• INLINECODE153 (date range)
• INLINECODE154 (exact match)

Report matching entries with their title, content preview, date, and label.

Validation Rules

Before sending, validate:

1. 1. richContent must be either JSON null or a JSON string that parses into an array where every element has an insert key.
2. Never put plain text, markdown, "NULL", "null", or empty string "" into richContent.
3. INLINECODE162 must be plain text (for preview/search), not JSON.
4. INLINECODE163 must contain filename-only entries and include all image filenames from richContent embeds.
5. Use Unix milliseconds for time and lastModified.
6. INLINECODE167 must be either omitted, null, or a JSON string parsing to an array of valid sticker objects.
7. Each sticker must use an exact assetPath from the bundled sticker list above.
8. Sticker scale should be between 0.3 and 4.0.