Obsidian URI

aliases:
  - Using Obsidian URI
  - Advanced topics/Using obsidian URI
  - Concepts/Obsidian URI
  - Extending Obsidian/Obsidian URI
permalink: uri

Obsidian URI is a custom URI protocol supported by Obsidian that lets you trigger various actions, such as opening a note or creating a note. Obsidian URI enables automation and cross-app workflows.

URI format

Obsidian URIs use the following format:

obsidian://action?param1=value&param2=value

The action parameter is the action that you would like to perform. Available actions include:

• open to open a note.
• new to create or add to an existing note.
• daily to create or open your daily note.
• unique to create a new unique note.
• search to open a search.
• choose-vault to open the vault manager.

Encoding

Ensure that your values are properly URI encoded. For example, forward slash characters / must be encoded as %2F and space characters must be encoded as %20.

This is especially important because an improperly encoded "reserved" character may break the interpretation of the URI. See here for details.

Open note

The open action opens an Obsidian vault, or opens a file within that vault.

Examples

• obsidian://open?vault=my%20vault

This opens the vault my vault. If the vault is already open, focus on the window.

• obsidian://open?vault=ef6ca3e3b524d22f

This opens the vault identified by the ID ef6ca3e3b524d22f.

• obsidian://open?vault=my%20vault&file=my%20note

This opens the note my note.md in the vault my vault, assuming the file exists.

• obsidian://open?path=%2Fhome%2Fuser%2Fmy%20vault%2Fpath%2Fto%2Fmy%20note

This will look for any vault that contains the path /home/user/my vault/path/to/my note. Then, the rest of the path is passed to the file parameter. For example, if a vault exists at /home/user/my vault, then this would be equivalent to file parameter set to path/to/my note.

Open a heading or block

With proper URI encoding, you can navigate to a heading or block within a note. Note%23Heading would navigate to the heading called "Heading", whereas Note%23%5EBlock would navigate to the block called "Block".

Parameters

• vault can be either the vault name or the vault ID.

• file can be either a file name, or a path from the vault root to the specified file. If the file extension is md, the extension can be omitted.

• path an absolute file system path to a file.

• Using this parameter will override both vault and file.

  • This will cause the app to search for the most specific vault which contains the specified file path.
  • Then the rest of the path replaces the file parameter.

• prepend will add to the top of the file and attempt to merge properties.

• append will add to the end of the file and also attempt to merge properties.

• paneType(optional) determines where the note will be opened in the UI.

• if not present, the last active tab is replaced.

  • paneType=tab open in a new tab.
  • paneType=split open in a new tab group.
  • paneType=window open in a pop-out window (Desktop only).

Create note

The new action, creates a new note in the vault, optionally with some content.

Examples

• obsidian://new?vault=my%20vault&name=my%20note

This opens the vault my vault, and creates a new note called my note.

• obsidian://new?vault=my%20vault&file=path%2Fto%2Fmy%20note

This opens the vault my vault, and creates a new note at path/to/my note.

Parameters

• vault can be either the vault name, or the vault ID. Same as action open.
• name the file name to be created. If this is specified, the file location will be chosen based on your "Default location for new notes" preferences.
• file a vault absolute path, including the name. Will override name if specified.
• path a globally absolute path. Works similar to the path option in the open action, which will override both vault and file.
• paneType (optional) determines where the note will be opened in the UI. Same as action open.
• content (optional) the contents of the note.
• clipboard (optional) use of the contents of the clipboard instead of specifying content.
• silent (optional) include this parameter if you don't want to open the new note.
• append (optional) include this parameter to append to an existing file if one exists.
• overwrite (optional) overwrite an existing file if one exists, but only if append isn't set.
• x-success (optional) see Use x-callback-url parameters.

Create or open daily note

The daily action creates or opens your daily note. The Daily notes plugin must be enabled.

Examples

• obsidian://daily?vault=my%20vault

This opens the vault my vault, and creates or opens the daily note.

Parameters

The daily action accepts the same parameters as the new action.

Unique Note

The unique action creates a new unique note in the vault. The Unique note creator plugin must be enabled.

Examples

• obsidian://unique?vault=my%20vault

This opens the vault my vault, and creates a new unique note.

• obsidian://unique?vault=my%20vault&content=Hello%20World

This opens the vault my vault, and creates a new unique note with the content Hello World.

Parameters

• vault can be either the vault name, or the vault ID. Same as action open.
• paneType (optional) determines where the note will be opened in the UI. Same as action open.
• content (optional) the contents of the note.
• clipboard (optional) use of the contents of the clipboard instead of specifying content.
• x-success (optional) see Use x-callback-url parameters.

Open search

The search action opens Search in the specified vault, and optionally perform a search term.

Examples

• obsidian://search?vault=my%20vault

This opens the vault my vault, and opens Search.

• obsidian://search?vault=my%20vault&query=Obsidian

This opens the vault my vault, opens Search, and performs a search for Obsidian.

Parameters

• vault can be either the vault name, or the vault ID. Same as action open.
• query (optional) The search term to perform.

Open Vault Manager

The choose-vault action opens the vault manager.

Examples

• obsidian://choose-vault

Integrate with Hook

This Obsidian URI action is to be used with Hook.

Example

obsidian://hook-get-address

Parameters

• vault (optional) can be either the vault name, or the vault ID. If not provided, the current or last focused vault will be used.
• x-success (optional) see Use x-callback-url parameters.
• x-error (optional) see Use x-callback-url parameters.

If x-success is defined, this API will use it as the x-callback-url. Otherwise, it will copy a Markdown link of the current focused note to the clipboard, as an obsidian://open URL.

Use x-callback-url parameters

Some endpoints will accept the x-callback-url parameters x-success and x-error. When it's provided, Obsidian will provide the following to the x-success callback:

• name the name of the file, without the file extension.
• url the obsidian:// URI for this file.
• file (desktop only) the file:// URL for this file.

For example, if Obsidian receives

obsidian://.....x-success=myapp://x-callback-url, the response would be myapp://x-callback-url?name=...&url=obsidian%3A%2F%2Fopen...&file=file%3A%2F%2F...

Shorthand formats

In addition to the formats above, there are two more "shorthand" formats available to open vaults and files:

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

Troubleshooting

Register Obsidian URI

On Windows and macOS, running the app once should be sufficient to register the Obsidian URI protocol on your computer.

On Linux, it is a much more involved process:

1. Ensure you create a obsidian.desktop file. See here for details.
2. Ensure that your desktop file specifies the Exec field as Exec=executable %u. The %u is used to pass the obsidian:// URIs to the app.
3. If you're using the AppImage installer, you may have to unpack it using Obsidian-x.y.z.AppImage --appimage-extract. Then make sure the Exec directive points to the unpacked executable.