Actions URI

Actions URI is an Obsidian plugin that extends the built-in Obsidian URIs by adding additional x-callback-url endpoints. It provides super-charged capabilities for interacting with Obsidian via external workflows, such as:

• Managing daily notes
• Working with specific notes
• Retrieving search results

For a full list of available routes and features, refer to the official documentation.

Actions URI is a plugin that extends Obsidian's native obsidian:// URI protocol by adding new x-callback-url endpoints. It allows external applications to interact with an Obsidian instance via GET requests to obsidian://actions-uri/* URLs.

Key features include:

• Enhanced Interactivity: Provides more robust ways for external sources to trigger actions within Obsidian.
• Callback Support: All new routes support x-success and x-error parameters, enabling the plugin to communicate the result of an action back to the original sender (e.g., a web browser or automation app).

The /vault routes allow you to interact with an Obsidian vault via URI. All these routes use the base prefix obsidian://actions-uri/vault.

Requirements:

• For /vault/open and /vault/close, the vault must be recognized by Obsidian and the Actions URI plugin must be active within that vault.
• /vault/close is Desktop only.

As of version v1.9.0, the vault parameter has been removed to maintain compatibility with Obsidian 1.13 (which no longer passes vault in obsidian:// URIs).

• The vault parameter is no longer required.
• If you continue to supply the vault parameter in your URIs, it will be silently ignored.

When developing external applications that communicate with Obsidian via Actions URI, you can enable debug-mode in your incoming request.

When debug-mode is enabled, the x-success callback will include additional input- prefixed parameters that mirror the original request's parameters (e.g., input-action, input-file, input-silent). This allows you to verify exactly what was sent to Actions URI during the callback lifecycle.

// Example of a success callback with debug-mode enabled
my-app://success
  ?request-id=123456789
  &result-body=%0AActions+URI+is+ready+for+action%21
  &result-content=---%0Atags%3A+test%0A---%0A%0AActions+URI+is+ready+for+action%21
  &result-filepath=My+super+note.md
  &result-front-matter=tags%3A+test%0A
  &input-action=actions-uri%2Fnote%2Fget
  &input-file=My+super+note.md
  &input-silent=false

An Actions URI follows a structure similar to standard Obsidian URIs, but uses a specific host to route requests to the Actions URI plugin.

URL Components

1. Host: The host must be actions-uri. This tells Obsidian to hand the request to the Actions URI plugin.
2. Path (Route): The path specifies the specific action to perform (e.g., /daily-note/get-current).
3. Search Parameters: Data and configuration are passed via standard URL search parameters (e.g., ?parameter=value).

Important Requirement: URL Encoding

All parameter data must be properly percent-encoded. The plugin does not attempt to correct malformed or unencoded input.

// Example of an Actions URI structure:
obsidian://actions-uri/daily-note/get-current?parameter=value

If you want to test pre-release or beta versions of Actions URI, use the BRAT plugin:

1. Install the BRAT plugin from the Obsidian community plugin browser.
2. Open Settings → Community Plugins → Obsidian42 - BRAT.
3. Click Add Beta plugin.
4. Enter the repository address: czottmann/obsidian-actions-uri.
5. Enable Actions URI under Settings → Community plugins.

The root route obsidian://actions-uri is a minimal endpoint that performs no complex actions other than displaying a 'hello' Notice toast within Obsidian. It is useful for testing connectivity or verifying that the Actions URI plugin is active and responding to URI calls.

Parameters

This route only supports the base parameters defined in the Parameters required in/ accepted by all calls documentation.

Return values

When successful, the following parameter is included in the callbacks used for retrieving data back from the Actions URI:

To contribute to or develop the Actions URI plugin locally, follow these steps:

1. Clone the repository.
2. Install dependencies using pnpm install or npm install.
3. Start the development server with pnpm dev or npm run dev to compile the code and enable file watching.

To install the stable version of Actions URI, follow these steps within Obsidian:

1. Open Obsidian and navigate to Settings → Community plugins.
2. Click Browse and search for "Actions URI".
3. Click Install.
4. Once installed, click Enable to activate the plugin.