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¶m2=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 URI | What it does |
|---|---|
obsidian://open?vault=my%20vault | Opens the vault my vault, or brings its window to the front if it is open. |
obsidian://open?vault=ef6ca3e3b524d22f | Opens the vault whose ID is ef6ca3e3b524d22f. |
obsidian://open?vault=my%20vault&file=my%20note | Opens my note.md in my vault if that file exists. |
obsidian://open?path=%2Fhome%2Fuser%2Fmy%20vault%2Fpath%2Fto%2Fmy%20note | Finds the vault whose folder holds this path and opens the remaining part of the path as file. |
obsidian://open?vault=my%20vault&file=Note%23Heading | Opens Note at its heading called Heading. The # is sent as %23. |
obsidian://open?vault=my%20vault&file=Note%23%5EBlock | Opens Note at its block called Block. The #^ is sent as %23%5E. |
Create examples
| Example URI | What it does |
|---|---|
obsidian://new?vault=my%20vault&name=my%20note | Creates a note named my note in my vault. |
obsidian://new?vault=my%20vault&file=path%2Fto%2Fmy%20note | Creates a note at path/to/my note in my vault. |
obsidian://new?vault=my%20vault&file=my%20note&append=true&heading=Tasks&content=Buy%20milk | Appends Buy milk at the bottom of the Tasks section of my note. |
obsidian://daily?vault=my%20vault | Opens the daily note of my vault, and creates it first if needed. |
obsidian://daily?vault=my%20vault&append=true&heading=Log&content=Called%20Sam | Appends Called Sam at the bottom of the Log section of the daily note. |
obsidian://unique?vault=my%20vault&content=Meeting%20notes | Adds a unique note whose text is Meeting notes. |
obsidian://search?vault=my%20vault&query=Obsidian | Opens Search and runs a search for Obsidian. |
obsidian://choose-vault | Opens the vault manager. |
obsidian://hook-get-address | With 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.
| Parameter | Description |
|---|---|
vault | The 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. |
file | The name of the file, or its path starting at the vault root. You can leave out an md extension. |
path | The 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. |
paneType | Optional. 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.
| Parameter | Description |
|---|---|
vault | The name of the vault, or its ID. Same as the open action. |
name | The name of the new file. Obsidian puts it in the folder set by the Default location for new notes preference. |
file | The path of the note from the vault root, file name included. It wins over name if both are set. |
path | A full path on disk. It behaves like path in the open action and takes the place of vault and file. |
paneType | Optional. Same as the open action. |
content | Optional. The text of the note. |
clipboard | Optional. Takes the text from the clipboard in place of content. |
silent | Optional. Add it to create the note without opening it. |
append | Optional. If the file already exists, adds the content at its end and merges any properties. |
prepend | Optional. If the file already exists, adds the content at its start and merges any properties. |
heading | Optional. Needs append or prepend. The content then goes into the section under this heading rather than into the file as a whole. |
spacing | Optional. 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. |
overwrite | Optional. Replaces the file if it already exists. This works only when neither append nor prepend is set. |
x-success | Optional. 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.
| Parameter | Description |
|---|---|
vault | The name of the vault, or its ID. Same as the open action. |
paneType | Optional. Same as the open action. |
content | Optional. The text of the note. |
clipboard | Optional. Takes the text from the clipboard in place of content. |
x-success | Optional. See the x-callback-url section below. |
Open a search (search)
Opens Search in the given vault and can run a search straight away.
| Parameter | Description |
|---|---|
vault | The name of the vault, or its ID. Same as the open action. |
query | Optional. 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.
| Parameter | Description |
|---|---|
vault | Optional. The name of the vault, or its ID. Without it, the current or last focused vault is used. |
x-success | Optional. The x-callback-url to call. See the section below. |
x-error | Optional. 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.
| Character | Encoded |
|---|---|
(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.
| Value | Meaning |
|---|---|
name | The file name with no extension. |
url | The obsidian:// URI of the file. |
file | Desktop 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
| Shorthand | Equivalent |
|---|---|
obsidian://vault/my vault/my note | It is equivalent to obsidian://open?vault=my%20vault&file=my%20note. |
obsidian:///absolute/path/to/my note | It 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.
Sources
- “Using Obsidian URI, Obsidian Help”help.obsidian.md
- “Obsidian URI.md, the source file of the help page”raw.githubusercontent.com
- “encodeURIComponent(), MDN Web Docs”developer.mozilla.org
- “RFC 3986, Uniform Resource Identifier syntax”rfc-editor.org