Obsidian URI reference

The official Obsidian help page on the Obsidian URI documents 7 actions. This page gives each action with its parameters, the encoding rules, the x-callback-url values, the two shorthand formats and the troubleshooting notes.

What the Obsidian URI does

The Obsidian URI is a custom protocol that other apps and scripts use to trigger actions in Obsidian, such as opening a note or creating one. That makes it useful for automation that spans more than one app.

The format is obsidian://action?param1=value&param2=value, where action is the action to perform.

Every value has to be percent-encoded, so / turns into %2F and a space turns into %20. If a reserved character is left unencoded or is encoded the wrong way, the URI may not be read the way you meant.

Open examples

Example URIWhat it does
obsidian://open?vault=my%20vaultOpens the vault my vault, or brings its window to the front if it is open.
obsidian://open?vault=ef6ca3e3b524d22fOpens the vault whose ID is ef6ca3e3b524d22f.
obsidian://open?vault=my%20vault&file=my%20noteOpens my note.md in my vault if that file exists.
obsidian://open?path=%2Fhome%2Fuser%2Fmy%20vault%2Fpath%2Fto%2Fmy%20noteFinds the vault whose folder holds this path and opens the remaining part of the path as file.
obsidian://open?vault=my%20vault&file=Note%23HeadingOpens Note at its heading called Heading. The # is sent as %23.
obsidian://open?vault=my%20vault&file=Note%23%5EBlockOpens Note at its block called Block. The #^ is sent as %23%5E.

Create examples

Example URIWhat it does
obsidian://new?vault=my%20vault&name=my%20noteCreates a note named my note in my vault.
obsidian://new?vault=my%20vault&file=path%2Fto%2Fmy%20noteCreates a note at path/to/my note in my vault.
obsidian://new?vault=my%20vault&file=my%20note&append=true&heading=Tasks&content=Buy%20milkAppends Buy milk at the bottom of the Tasks section of my note.
obsidian://daily?vault=my%20vaultOpens the daily note of my vault, and creates it first if needed.
obsidian://daily?vault=my%20vault&append=true&heading=Log&content=Called%20SamAppends Called Sam at the bottom of the Log section of the daily note.
obsidian://unique?vault=my%20vault&content=Meeting%20notesAdds a unique note whose text is Meeting notes.
obsidian://search?vault=my%20vault&query=ObsidianOpens Search and runs a search for Obsidian.
obsidian://choose-vaultOpens the vault manager.
obsidian://hook-get-addressWith no x-success given, puts a Markdown link to the note in focus on the clipboard.

Actions and parameters

Every action and its parameters follow. The action and parameter names are copied exactly; the descriptions restate the help page in plain words.

Open a note (open)

Opens a vault, or a single file inside a vault. If that vault is open already, Obsidian brings its window to the front.

ParameterDescription
vaultThe name of the vault, or its ID. The ID is a random code of 16 characters that Obsidian gives each vault folder on your computer. To get it, open the vault switcher, open the context menu of the vault and pick Copy vault ID.
fileThe name of the file, or its path starting at the vault root. You can leave out an md extension.
pathThe full path of the file on disk. When it is set, it takes the place of both vault and file. Obsidian picks the most specific vault whose folder holds that path and uses the remaining part of the path as file.
paneTypeOptional. Without it, the last active tab is replaced. paneType=tab opens a new tab, paneType=split a new tab group, paneType=window a pop-out window (desktop only).

Create a note (new)

Makes a note in the vault, with or without text in it. With append or prepend it can also add to a note that already exists.

ParameterDescription
vaultThe name of the vault, or its ID. Same as the open action.
nameThe name of the new file. Obsidian puts it in the folder set by the Default location for new notes preference.
fileThe path of the note from the vault root, file name included. It wins over name if both are set.
pathA full path on disk. It behaves like path in the open action and takes the place of vault and file.
paneTypeOptional. Same as the open action.
contentOptional. The text of the note.
clipboardOptional. Takes the text from the clipboard in place of content.
silentOptional. Add it to create the note without opening it.
appendOptional. If the file already exists, adds the content at its end and merges any properties.
prependOptional. If the file already exists, adds the content at its start and merges any properties.
headingOptional. Needs append or prepend. The content then goes into the section under this heading rather than into the file as a whole.
spacingOptional. Needs append or prepend. Sets what separates the new content from the text already there. spacing=auto, the default, puts a blank line between the two, spacing=newline begins the content on the next line, and spacing=inline joins it with no line break.
overwriteOptional. Replaces the file if it already exists. This works only when neither append nor prepend is set.
x-successOptional. See the x-callback-url section below.

Create or open the daily note (daily)

Opens the daily note, and makes it first if it is missing. The Daily notes core plugin must be enabled. It accepts the same parameters as the new action.

Create a unique note (unique)

Adds a new unique note to the vault. The Unique note creator core plugin must be enabled.

ParameterDescription
vaultThe name of the vault, or its ID. Same as the open action.
paneTypeOptional. Same as the open action.
contentOptional. The text of the note.
clipboardOptional. Takes the text from the clipboard in place of content.
x-successOptional. See the x-callback-url section below.

Open a search (search)

Opens Search in the given vault and can run a search straight away.

ParameterDescription
vaultThe name of the vault, or its ID. Same as the open action.
queryOptional. The text to search for.

Open the vault manager (choose-vault)

Opens the vault manager.

Hook integration (hook-get-address)

Made for the Hook app. If an x-success callback is given, Obsidian calls it. If not, it puts a Markdown link to the note in focus on the clipboard, and that link is an obsidian://open URL.

ParameterDescription
vaultOptional. The name of the vault, or its ID. Without it, the current or last focused vault is used.
x-successOptional. The x-callback-url to call. See the section below.
x-errorOptional. The x-callback-url to call on error.

Encoding of the values

/ must be encoded as %2F.

A space must be encoded as %20.

# must be encoded as %23 and ^ as %5E when you open a heading or a block.

CharacterEncoded
(space)%20
/%2F
#%23
^%5E
&%26
?%3F
=%3D
%%25
+%2B

x-callback-url parameters

The new, daily, unique and hook-get-address actions accept the x-callback-url parameter x-success. hook-get-address also accepts x-error. When x-success is set, Obsidian passes these values to that callback.

ValueMeaning
nameThe file name with no extension.
urlThe obsidian:// URI of the file.
fileDesktop only. The file:// URL of the file.

For example, when Obsidian receives a URI with x-success=myapp://x-callback-url, the response is myapp://x-callback-url?name=...&url=obsidian%3A%2F%2Fopen...&file=file%3A%2F%2F....

Shorthand formats

ShorthandEquivalent
obsidian://vault/my vault/my noteIt is equivalent to obsidian://open?vault=my%20vault&file=my%20note.
obsidian:///absolute/path/to/my noteIt is equivalent to obsidian://open?path=%2Fabsolute%2Fpath%2Fto%2Fmy%20note.

Register the Obsidian URI for troubleshooting

On Windows and macOS, starting Obsidian one time should be enough to register the Obsidian URI protocol.

On Linux the setup is done by hand and takes more work.

Create an obsidian.desktop file, as the GNOME maintainer guidelines describe.

In that file, set the Exec field to Exec=executable %u. The %u is what hands each obsidian:// URI to the app.

If you installed from the AppImage, you may need to extract it first with Obsidian-x.y.z.AppImage --appimage-extract and then point Exec at the extracted executable.

NoteMods plugins are free to install. One payment of $15 turns on Pro in 129 of them.