URI Scheme

Octarine supports deep links via the octarine:// URL scheme (or octarine-staging:// for staging builds). These allow external tools like Raycast, Alfred, Shortcuts, and AI assistants (Claude, ChatGPT) to interact with your notes.

URL Format

octarine://<action>?param1=value1&param2=value2

Or with explicit action parameter:

octarine://host?action=<action>&param1=value1

x-callback-url Support

Octarine supports the x-callback-url specification, allowing external apps to receive results from Octarine actions.

Callback Parameters

Parameter	Description
`x-success`	URL to open on successful completion
`x-error`	URL to open if an error occurs
`x-cancel`	URL to open if the operation is cancelled
`x-source`	Name of the calling app (optional, for display)

Success Callback Data

On success, Octarine appends result data to the x-success URL:

Action	Data Appended
`open`	`path`, `workspace`
`create`	`path`, `workspace`, `action` (created/appended/replaced)
`daily`	`path`, `date` or `week`, `workspace`, `action`
`search`	`query`, `workspace`

Error Callback Data

On error, Octarine appends to the x-error URL:

errorCode - Machine-readable error code
errorMessage - Human-readable error description

Error Codes

Code	Description
`workspace_not_found`	Specified workspace doesn't exist
`file_not_found`	File path doesn't exist
`missing_parameter`	Required parameter not provided
`invalid_date`	Could not parse date/week format
`save_failed`	Failed to save file
`unknown_action`	Unrecognized action

Example with Callbacks

Apple Shortcuts - Run another shortcut on success:

octarine://create?path=inbox/note&content=Hello&x-success=shortcuts://run-shortcut?name=NoteCreated

# On success, runs the "NoteCreated" shortcut with parameters:
shortcuts://run-shortcut?name=NoteCreated&path=inbox/note.md&workspace=Personal&action=created

Apple Shortcuts - Open a URL on success:

octarine://daily?date=today&content=Task%20complete&x-success=https://example.com/webhook?status=done

# On success, opens in browser:
https://example.com/webhook?status=done&path=Daily/2026-01-06.md&action=appended

Generic webhook on error:

octarine://create?path=important/note&content=Data&x-error=https://example.com/alert?type=octarine-error

# On error, calls:
https://example.com/alert?type=octarine-error&errorCode=save_failed&errorMessage=Error%20saving%20file

Common Parameters

These parameters are available across most actions:

Parameter	Type	Description
`workspace`	string	Workspace name to target. If omitted, uses current workspace.
`compressedContent`	string	LZ-String base64 compressed content (for large payloads)

Actions

`open` - Open an existing note

Opens a specific note file in a new tab.

Parameters:

Parameter	Required	Type	Description
`path`	Yes	string	Path to the note (relative to workspace root)
`workspace`	No	string	Target workspace name

Examples:

# Open a note in current workspace
octarine://open?path=notes/meeting.md

# Open a note in a specific workspace
octarine://open?path=Projects/roadmap.md&workspace=Work

# Path without .md extension (auto-added)
octarine://open?path=inbox/quick-note

Behavior:

Navigates to the workspace notes view
Opens the file in a new tab
If file doesn't exist, tab will show empty/error state

`search` - Execute a search query

Opens the search drawer with a pre-filled query.

Parameters:

Parameter	Required	Type	Description
`query`	Yes	string	Search query text
`workspace`	No	string	Target workspace name

Examples:

# Search in current workspace
octarine://search?query=project%20alpha

# Search with special characters (URL encoded)
octarine://search?query=%23todo%20urgent

# Search in specific workspace
octarine://search?query=meeting%20notes&workspace=Work

Behavior:

Opens the sidebar
Opens the search drawer
Pre-fills the search query
Search is case-insensitive by default

`daily` - Open a daily or weekly note

Opens the daily or weekly note for a specific date. Supports natural language dates and ISO week format. Can optionally add content to the note.

Parameters:

Parameter	Required	Type	Default	Description
`date`	Yes	string	-	Date (YYYY-MM-DD), week (YYYY-Www), or natural language
`content`	No	string	-	Content to add to the note
`fresh`	No	`true`	`false`	`false`
`position`	No	`top`	`bottom`	`bottom`
`separator`	No	string	`\n\n`	Separator between existing and new content
`openAfter`	No	`true`	`false`	`true`
`workspace`	No	string	current	Target workspace name

Supported Date Formats:

ISO date: 2024-01-15, 2024-12-25
ISO week: 2024-W03, 2026-W1
Natural language dates: today, yesterday, tomorrow
Relative dates: 2 days ago, next monday, last friday
Partial dates: jan 15, december 25, nov 3
Natural language weeks: this week, last week, next week
Relative weeks: 2 weeks ago, in 2 weeks

Examples:

# Today's daily note (just open)
octarine://daily?date=today

# Yesterday's note
octarine://daily?date=yesterday

# Specific date
octarine://daily?date=2024-01-15

# Natural language
octarine://daily?date=last%20friday
octarine://daily?date=2%20days%20ago

# Weekly notes (ISO week format)
octarine://daily?date=2024-W03
octarine://daily?date=2026-W1

# Natural language weeks
octarine://daily?date=this%20week
octarine://daily?date=last%20week
octarine://daily?date=2%20weeks%20ago

# Add content to today's note (appends if exists, creates if not)
octarine://daily?date=today&content=Remember%20to%20call%20Mom

# Add content to top of daily note
octarine://daily?date=today&content=%23%23%20Morning%20Entry&position=top

# Replace daily note content entirely
octarine://daily?date=today&content=Fresh%20start&fresh=true

# Add to weekly note without opening
octarine://daily?date=this%20week&content=Weekly%20goal&openAfter=false

Behavior:

For dates: Opens/creates Daily/YYYY-MM-DD.md
For weeks: Opens/creates Daily/Weekly/YYYY-WNN.md
If content provided: auto-appends to existing file or creates new file
If fresh=true: replaces existing content instead of appending
When position=top, preserves frontmatter at the top and inserts after it

`create` - Create or update a note

Creates a new note or updates an existing one. By default, appends content to existing files (upsert behavior).

Parameters:

Parameter	Required	Type	Default	Description
`path`	Yes	string	-	Path for the note (relative to workspace)
`content`	No	string	""	Content for the note
`contentReference`	No	string	-	URL or file path to fetch content from
`compressedContent`	No	string	-	LZ-String base64 compressed content
`fresh`	No	`true`	`false`	`false`
`position`	No	`top`	`bottom`	`bottom`
`separator`	No	string	`\n\n`	Separator between existing and new content
`openAfter`	No	`true`	`false`	`true`
`workspace`	No	string	current	Target workspace name

Examples:

# Create empty note (or open if exists)
octarine://create?path=inbox/new-idea

# Create with content (appends if file exists)
octarine://create?path=inbox/task&content=%23%20New%20Task%0A%0A-%20%5B%20%5D%20Item%201

# Create from URL content
octarine://create?path=imports/article&contentReference=https://example.com/doc.md

# Add to top of note
octarine://create?path=inbox/updates&content=%23%23%20Update&position=top

# Add content without opening
octarine://create?path=inbox/quick&content=Note&openAfter=false

# Replace file content entirely
octarine://create?path=inbox/draft&content=Starting%20over&fresh=true

# Create in specific workspace
octarine://create?path=Projects/feature&content=Feature%20spec&workspace=Work

Behavior:

Auto-adds .md extension if not present
Upsert by default: Creates file if doesn't exist, appends if it does
With fresh=true: Replaces existing content entirely
When position=top, preserves frontmatter at the top and inserts after it
Shows toast notification with result ("Created", "Appended to", or "Replaced")

Use Case - AI Update List:

# Claude adding an update (auto-appends to existing)
octarine://create?path=inbox/claude-updates&content=%23%23%20Jan%203%2C%202026%0A%0A-%20Completed%20feature%20X&position=top

Use Case - Daily Standup Template:

# Replace with fresh template each day
octarine://create?path=work/standup&content=%23%20Standup%0A%0A%23%23%20Yesterday%0A%0A%23%23%20Today%0A%0A%23%23%20Blockers&fresh=true

URL Encoding

Special characters must be URL-encoded:

Character	Encoded
Space	`%20`
Newline	`%0A`
`#`	`%23`
`/`	`%2F`
`?`	`%3F`
`&`	`%26`
`=`	`%3D`

Example with markdown content:

# Original content:
## Heading

- Item 1
- Item 2

# URL encoded:
octarine://create?path=test&content=%23%23%20Heading%0A%0A-%20Item%201%0A-%20Item%202

Large Content: LZ-String Compression

For large content that might exceed URL length limits, use LZ-String base64 compression:

import LZString from "lz-string";

const content = "# Very long document...";
const compressed = LZString.compressToBase64(content);
const url = `octarine://create?path=doc&compressedContent=${encodeURIComponent(
  compressed
)}`;

Integration Examples

Shell Script - Daily Log

#!/bin/bash
# Append timestamped entry to daily log

TIMESTAMP=$(date "+%H:%M")
ENTRY="- [$TIMESTAMP] $1"
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$ENTRY'))")

open "octarine://daily?date=today&content=$ENCODED&openAfter=false"

Shell Script - Quick Capture

#!/bin/bash
# Add quick note to inbox

NOTE_CONTENT="$1"
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$NOTE_CONTENT'))")
open "octarine://create?path=inbox/quick-capture&content=$ENCODED&openAfter=false"

Browser Bookmarklet

// Save page info as a note (add as bookmark URL)
javascript: (function () {
  const title = document.title.replace(/[^a-zA-Z0-9 ]/g, "");
  const content = `# ${document.title}\n\nURL: ${
    window.location.href
  }\n\nSaved: ${new Date().toISOString()}`;
  window.location.href = `octarine://create?path=web-clips/${encodeURIComponent(
    title
  )}&content=${encodeURIComponent(content)}`;
})();

Browser Bookmarklet - Save Selection

javascript: (function () {
  const sel = window.getSelection().toString();
  if (!sel) {
    alert("Select some text first");
    return;
  }
  const content = `# Clip from ${document.title}\n\nSource: ${window.location.href}\n\n> ${sel}`;
  window.location.href = `octarine://create?path=inbox/web-clip&content=${encodeURIComponent(
    content
  )}`;
})();

Claude/AI Assistant

To save this information to your notes, use:
octarine://create?path=inbox/ai-research&content=%23%23%20Research%20Summary%0A%0A...&position=top

AppleScript - Capture from Any App

-- Save clipboard to daily note
set clipContent to the clipboard as text
set encodedContent to do shell script "python3 -c \"import urllib.parse; print(urllib.parse.quote('" & clipContent & "'))\""
open location "octarine://daily?date=today&content=" & encodedContent & "&openAfter=false"

PopClip Extension (macOS)

# Config.yaml for PopClip extension
name: Save to Octarine
icon: square and pencil
url: octarine://create?path=inbox/popclip&content=***

Error Handling

All actions show toast notifications for:

Success: Green toast with action confirmation ("Created", "Appended to", "Replaced")
Error: Red toast with error message

Common errors:

"Workspace not found" - Invalid workspace name
"File not found" - Path doesn't exist (for open action)
"Could not parse date" - Invalid date format (for daily action)
"Missing X parameter" - Required parameter not provided
"Error saving file" - File system error during save
"Invalid deep link URL format" - Malformed URL

Platform Notes

Platform	URL Scheme Registration
macOS	Automatic via Info.plist
Windows	Runtime registration on app start
Linux	Runtime registration on app start

The deep link handler has a 1-second debounce to prevent duplicate executions when the same URL is triggered multiple times rapidly.

Copying Octarine URLs

You can copy the Octarine URL for any note using:

Command Bar (Cmd+K): Search for "Copy Octarine URL"
Note Menu: Click the settings icon in the note breadcrumb -> "Copy Octarine URL"

The copied URL format:

octarine://open?path=notes%2Fmeeting.md&workspace=My%20Workspace

Best Practices

URL Stability

Use relative paths: Octarine URLs use paths relative to the workspace root, so they survive workspace folder moves
Include workspace name: For multi-workspace setups, always include the workspace parameter
Use URL encoding: Always encode special characters, especially spaces, newlines, and #

Performance

Use openAfter=false for background operations when you don't need to see the result
Batch operations: For multiple entries, consider building content in your script and doing one create
Use fresh=true sparingly - only when you intentionally want to replace content

Content Behavior

Default is upsert: create and daily actions auto-append to existing files
Use fresh=true to replace content entirely (e.g., regenerating a template)
Use position=top for reverse-chronological logs (newest first)
Use position=bottom (default) for chronological logs

Error Handling

All deep link actions show toast notifications for success/failure
Use x-error callback to handle errors programmatically
Use x-success callback to chain actions or confirm completion
Invalid workspaces or paths result in error toasts

Security

Deep links can only access workspaces configured in Octarine
No access to arbitrary filesystem paths outside workspaces
Content is never executed, only inserted as text