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. 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. Open the OpenNote app
2. Go to Profile → API Tokens
3. Tap Create Token
4. Choose the scopes you need:
   • diaries:write — create and update notes
   • images:write — upload images to notes
5. Set an expiration (default: 90 days, max: 365 days, or never)
6. 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:

text

OPENNOTE_API_TOKEN=milo_pat_v1_your_token_here

Option B — Shell profile (if running locally):

bash

export OPENNOTE_API_TOKEN="milo_pat_v1_your_token_here"

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 OPENNOTE_API_TOKEN
• 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:

json

{
  "fetchedAt": 1741111111111,
  "labels": [
    { "categoryID": 1, "categoryName": "Personal", "categoryColor": 4294198070 },
    { "categoryID": 2, "categoryName": "Work", "categoryColor": 4283215696 }
  ]
}

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

bash

curl -s "https://api.opennote.cc/api/v1/labels" \
  -H "Authorization: Bearer $OPENNOTE_API_TOKEN"

Response:

json

{
  "labels": [
    { "categoryID": 1, "categoryName": "Personal", "categoryColor": 4294198070, "visibility": true, "coverImageName": null, "lastModified": 1741111111111, "fontFamily": null, "backgroundPreset": null }
  ]
}

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#

js

const now = Date.now(); // Unix milliseconds
const fileName = `${now}.json`;

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:

json

{ "insert": "Hello world" }

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

json

{ "insert": "\n" }

Inline styles (on text insert):

• bold (boolean)
• italic (boolean)
• underline (boolean)
• strike (boolean)
• color (hex string like "#2a7fff") — use the palette below for best results
• size (number, typically 2-99; app default is 17)

json

{ "insert": "Important", "attributes": { "bold": true, "color": "#ff0000", "size": 20 } }

Available color palette (36 colors):

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

NameLight-mode hexBlack#000000Charcoal#545454Dark Grey#616161Warm Slate#455a64Crimson#b71c1cDeep Red#c0392bBrick#bf360cDark Amber#a04000Mustard#9a6e00Dark Olive#558b2fForest Green#2e7d32Deep Gold#8b6914Dark Teal#00695cDark Cyan#00838fRoyal Blue#1565c0Blue#007affIndigo#5856d6Deep Purple#6a1b9aMagenta#e91e63Pink#ff2d55Berry#880e4fPlum#6a0572Dark Violet#4a148cBrown#8d6e63Red#ff3b30Dark Rose#ad1457Terracotta#8b3a1fSea Green#007a63Midnight#1a237eDeep Sage#2e5902Ochre#7a5c00Steel Grey#37474fWine#8b0000Mahogany#6d2f1fDeep Sea#005b72Dark Coffee#4e342e

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

• align: "left", "center", "right"
• indent: integer
• list: "ordered", "bullet", "checked", "unchecked"
• code-block: true
• blockquote: true

json

{ "insert": "A bullet point" },
{ "insert": "\n", "attributes": { "list": "bullet" } }

Image embed:

json

{ "insert": { "image": "{\"src\":\"my_photo.jpg\",\"w\":1920,\"h\":1080}" } }

If dimensions are unknown:

json

{ "insert": { "image": "my_photo.jpg" } }

Collage embed (multi-image layout):

json

{
  "insert": {
    "collage": "{\"layout\":\"twoHorizontal\",\"images\":[\"img1.jpg\",\"img2.jpg\"]}"
  }
}

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

Divider embed:

json

{ "insert": { "divider": "split" } }

Example richContent value

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

json

"[{\"insert\":\"My Title\\n\",\"attributes\":{\"bold\":true,\"size\":24}},{\"insert\":\"Today was a great day.\\n\"},{\"insert\":{\"image\":\"photo.jpg\"}},{\"insert\":\"\\n\"}]"

Step 6: Build the content field (plain text)#

content 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)#

stickerData 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:

json

{
  "id": "unique_hex_id",
  "assetPath": "assets/stickers/bunny.svg",
  "dx": 150.0,
  "dy": 200.0,
  "normalizedDx": 0.39,
  "normalizedDy": 0.25,
  "scale": 1.0,
  "rotation": 0.0
}

Field rules:

• id: unique string, format <hex_timestamp>_<6char_hex_random>
• assetPath: must be an exact match from the bundled sticker list below
• dx, dy: pixel offsets from top-left of note canvas (typical canvas ~390px wide)
• normalizedDx, normalizedDy: proportional position (0.0–1.0 for dx; dy can exceed 1.0 for long content)
• scale: 0.3 to 4.0 (1.0 = default 70px base size)
• rotation: radians

Example stickerData field value:

json

"[{\"id\":\"18f0c9d2_a1b2c3\",\"assetPath\":\"assets/stickers/bunny.svg\",\"dx\":150.0,\"dy\":200.0,\"normalizedDx\":0.39,\"normalizedDy\":0.25,\"scale\":1.0,\"rotation\":0.0}]"

Available sticker asset paths

Kawaii:

text

assets/stickers/backpack.svg       assets/stickers/bird.svg
assets/stickers/book.svg           assets/stickers/bunny.svg
assets/stickers/burger.svg         assets/stickers/cake_slice.svg
assets/stickers/cat.svg            assets/stickers/cheese.svg
assets/stickers/chicken.svg        assets/stickers/clapboard.svg
assets/stickers/crown.svg          assets/stickers/flower_2.svg
assets/stickers/frog.svg           assets/stickers/garland.svg
assets/stickers/gramophone.svg     assets/stickers/hat.svg
assets/stickers/heart_2.svg        assets/stickers/kiwi.svg
assets/stickers/kitten.svg         assets/stickers/little_girl.svg
assets/stickers/little_girl_2.svg  assets/stickers/meals.svg
assets/stickers/muffin.svg         assets/stickers/piggy_bank.svg
assets/stickers/pizza.svg          assets/stickers/plant.svg
assets/stickers/pop_corn.svg       assets/stickers/rabbit.svg
assets/stickers/rabbit_2.svg       assets/stickers/saturn.svg
assets/stickers/shooting_star.svg  assets/stickers/skirt.svg
assets/stickers/soda_can.svg       assets/stickers/strawberry.svg
assets/stickers/symbol.svg         assets/stickers/tea_pot.svg
assets/stickers/ufo.svg            assets/stickers/wallet.svg
assets/stickers/watermelon.svg     assets/stickers/watermelon_2.svg

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 hippie_020-dj.svg

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 k791_020-book.svg

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 k155_020-rainbow.svg

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

Step 8: Upload images (if any)#

If the note includes images, upload each one first:

bash

curl -s -X POST "https://api.opennote.cc/api/v1/images" \
  -H "Authorization: Bearer $OPENNOTE_API_TOKEN" \
  -F "image=@/path/to/photo.jpg"

Response:

json

{ "imageName": "photo.jpg", "sizeInMB": 0.42 }

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#

bash

curl -s -X POST "https://api.opennote.cc/api/v1/diaries" \
  -H "Authorization: Bearer $OPENNOTE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "<timestamp>.json",
    "time": <timestamp>,
    "content": "<plain text summary>",
    "richContent": "<JSON string of Quill Delta ops>",
    "stickerData": "<JSON string of sticker array or null>",
    "diaryCoverImageName": null,
    "category": <categoryID>,
    "title": "<optional title>",
    "imageList": [],
    "isDeleted": false,
    "lastModified": <timestamp>,
    "hideTitle": false
  }'

If the API returns 409 ALREADY_EXISTS, retry with PUT:

bash

curl -s -X PUT "https://api.opennote.cc/api/v1/diaries/<fileName>" \
  -H "Authorization: Bearer $OPENNOTE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "...", "richContent": "...", "lastModified": <now> }'

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:

json

{
  "fileName": "1741111111111.json",
  "action": "created",
  "timestamp": 1741111111111,
  "title": "Morning Walk",
  "contentPreview": "Woke up early and went for a walk in the park...",
  "categoryID": 2,
  "categoryName": "Personal",
  "hasStickers": true,
  "hasImages": false,
  "imageList": []
}

Rules for the history:

• action: either "created" or "updated"
• contentPreview: first 150 characters of the plain text content
• categoryName: look up from cached labels, or "No Label" if category is 0
• hasStickers: true if stickerData was non-null
• hasImages: 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#

bash

curl -s "https://api.opennote.cc/api/v1/diaries?category=CATEGORY_ID&search=KEYWORD&limit=50&offset=0" \
  -H "Authorization: Bearer $OPENNOTE_API_TOKEN"

Query parameters (all optional):

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

Response:

json

{
  "diaries": [ { "fileName": "...", "time": ..., "content": "...", "richContent": "...", ... } ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Get a single note#

bash

curl -s "https://api.opennote.cc/api/v1/diaries/FILENAME.json" \
  -H "Authorization: Bearer $OPENNOTE_API_TOKEN"

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)
• contentPreview (keyword search)
• categoryName (label name)
• timestamp (date range)
• fileName (exact match)

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

Validation Rules#

Before sending, validate:

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. content must be plain text (for preview/search), not JSON.
4. imageList must contain filename-only entries and include all image filenames from richContent embeds.
5. Use Unix milliseconds for time and lastModified.
6. stickerData 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.