> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Obsidian Integration for AI Agents & Workflows

> Read, create, update, search, and delete notes in your Obsidian vault. Manage periodic notes, execute commands, and patch content at specific locations. Requires the Obsidian Local REST API plugin.

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/df8MOr-hXotYLTh5/logos/placeholder.svg?fit=max&auto=format&n=df8MOr-hXotYLTh5&q=85&s=a4046f9cd6d738c81259050e9833913c" alt="Obsidian logo" width="72" height="72" data-path="logos/placeholder.svg" />

## Overview

Add **Obsidian** to any ModuleX agent or workflow. Read, create, update, search, and delete notes in your Obsidian vault via the [Obsidian Local REST API](https://obsidian.md) plugin. Manage periodic notes, list and execute commands, work with the active file, and patch content at specific headings, block references, or frontmatter fields. The plugin runs locally inside your Obsidian app and is reachable at a `base_url` you pass on every call (default `https://127.0.0.1:27124`). Because the plugin serves a self-signed TLS certificate, the HTTP client does not verify the certificate chain.

<Info>
  **Categories**: Productivity & Collaboration · Note Taking · Knowledge Base · **Auth**: API Key · **Actions**: 15
</Info>

## Authentication

### API Key Authentication

Authenticate using the API key from the Obsidian Local REST API plugin

<Steps>
  <Step title="Step 1">
    Install the 'Local REST API' community plugin in Obsidian
  </Step>

  <Step title="Step 2">
    Open the plugin settings and enable it
  </Step>

  <Step title="Step 3">
    Copy the API key shown in the plugin settings
  </Step>

  <Step title="Step 4">
    Note the server URL (default [https://127.0.0.1:27124](https://127.0.0.1:27124)) for the base\_url parameter
  </Step>

  <Step title="Step 5">
    Paste the API key below
  </Step>
</Steps>

#### Required Credentials

| Field                       | Description                                              | Required | Format |
| --------------------------- | -------------------------------------------------------- | -------- | ------ |
| Obsidian Local REST API Key | API key from the Obsidian Local REST API plugin settings | Yes      | `-`    |

## Available Actions

<AccordionGroup>
  <Accordion title="list_files — List files and directories in your Obsidian vault.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="path" type="string">
      Directory path relative to vault root. Leave empty to list the root.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "FileEntry": {
          "additionalProperties": false,
          "description": "A single file or directory entry in ``list_files``.",
          "properties": {
            "path": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Path"
            },
            "type": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Type"
            }
          },
          "title": "FileEntry",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "files": {
          "items": {
            "$ref": "#/$defs/FileEntry"
          },
          "title": "Files",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListFilesOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_note — Retrieve the content of a note from your Obsidian vault.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="filename" type="string" required>
      Path to the note relative to vault root (e.g. "folder/note.md")
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Content"
        },
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Filename"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetNoteOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_note — Create or replace a note in your Obsidian vault.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="filename" type="string" required>
      Path for the note relative to vault root (e.g. "folder/note.md")
    </ResponseField>

    <ResponseField name="content" type="string" required>
      Markdown content for the note
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Filename"
        },
        "created": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Created"
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateNoteOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="append_note — Append content to an existing note in your Obsidian vault.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="filename" type="string" required>
      Path to the note relative to vault root (e.g. "folder/note.md")
    </ResponseField>

    <ResponseField name="content" type="string" required>
      Markdown content to append to the note
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Filename"
        },
        "appended": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Appended"
        }
      },
      "required": [
        "success"
      ],
      "title": "AppendNoteOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="patch_note — Insert or replace content at a specific heading, block reference, or frontmatter field in a note.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="filename" type="string" required>
      Path to the note relative to vault root (e.g. "folder/note.md")
    </ResponseField>

    <ResponseField name="content" type="string" required>
      Content to insert at the target location
    </ResponseField>

    <ResponseField name="operation" type="string" required>
      How to insert content: append, prepend, or replace
    </ResponseField>

    <ResponseField name="target_type" type="string" required>
      Type of target: heading, block, or frontmatter
    </ResponseField>

    <ResponseField name="target" type="string" required>
      Target identifier (heading text, block reference ID, or frontmatter field name)
    </ResponseField>

    <ResponseField name="target_delimiter" type="string">
      Delimiter for nested headings (default: "::")
    </ResponseField>

    <ResponseField name="trim_target_whitespace" type="boolean">
      Whether to trim whitespace from target before matching
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Filename"
        },
        "patched": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Patched"
        }
      },
      "required": [
        "success"
      ],
      "title": "PatchNoteOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="delete_note — Delete a note from your Obsidian vault.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="filename" type="string" required>
      Path to the note to delete relative to vault root
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Filename"
        },
        "deleted": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Deleted"
        }
      },
      "required": [
        "success"
      ],
      "title": "DeleteNoteOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="search — Search for text across notes in your Obsidian vault.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="query" type="string" required>
      Text to search for across vault notes
    </ResponseField>

    <ResponseField name="context_length" type="integer">
      Number of characters of context around each match (default: 100)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "SearchMatch": {
          "additionalProperties": false,
          "description": "A single matching context snippet within a search result.",
          "properties": {
            "context": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Context"
            }
          },
          "title": "SearchMatch",
          "type": "object"
        },
        "SearchResultItem": {
          "additionalProperties": false,
          "description": "A single result row in ``search``.",
          "properties": {
            "filename": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Filename"
            },
            "score": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Score"
            },
            "matches": {
              "items": {
                "$ref": "#/$defs/SearchMatch"
              },
              "title": "Matches",
              "type": "array"
            }
          },
          "title": "SearchResultItem",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "results": {
          "items": {
            "$ref": "#/$defs/SearchResultItem"
          },
          "title": "Results",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "SearchOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_active — Retrieve the content of the currently active file in Obsidian.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Content"
        },
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Filename"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetActiveOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="append_active — Append content to the currently active file in Obsidian.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="content" type="string" required>
      Markdown content to append to the active file
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "appended": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Appended"
        }
      },
      "required": [
        "success"
      ],
      "title": "AppendActiveOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="patch_active — Insert or replace content at a specific heading, block reference, or frontmatter field in the active file.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="content" type="string" required>
      Content to insert at the target location
    </ResponseField>

    <ResponseField name="operation" type="string" required>
      How to insert content: append, prepend, or replace
    </ResponseField>

    <ResponseField name="target_type" type="string" required>
      Type of target: heading, block, or frontmatter
    </ResponseField>

    <ResponseField name="target" type="string" required>
      Target identifier (heading text, block reference ID, or frontmatter field name)
    </ResponseField>

    <ResponseField name="target_delimiter" type="string">
      Delimiter for nested headings (default: "::")
    </ResponseField>

    <ResponseField name="trim_target_whitespace" type="boolean">
      Whether to trim whitespace from target before matching
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "patched": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Patched"
        }
      },
      "required": [
        "success"
      ],
      "title": "PatchActiveOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="open_file — Open a file in the Obsidian UI (creates the file if it does not exist).">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="filename" type="string" required>
      Path to the file relative to vault root
    </ResponseField>

    <ResponseField name="new_leaf" type="boolean">
      Whether to open the file in a new leaf/tab
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Filename"
        },
        "opened": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Opened"
        }
      },
      "required": [
        "success"
      ],
      "title": "OpenFileOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_commands — List all available commands in Obsidian.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "CommandItem": {
          "additionalProperties": false,
          "description": "A single available command in ``list_commands``.",
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Name"
            }
          },
          "title": "CommandItem",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "commands": {
          "items": {
            "$ref": "#/$defs/CommandItem"
          },
          "title": "Commands",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListCommandsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="execute_command — Execute a command in Obsidian (e.g. open daily note, toggle sidebar).">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="command_id" type="string" required>
      ID of the command to execute (use list\_commands to discover available commands)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "command_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Command Id"
        },
        "executed": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Executed"
        }
      },
      "required": [
        "success"
      ],
      "title": "ExecuteCommandOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_periodic_note — Retrieve the current periodic note (daily, weekly, monthly, quarterly, or yearly).">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="period" type="string" required>
      Period type: daily, weekly, monthly, quarterly, or yearly
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Content"
        },
        "period": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Period"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetPeriodicNoteOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="append_periodic_note — Append content to the current periodic note (daily, weekly, monthly, quarterly, or yearly). Creates the note if it does not exist.">
    ### Parameters

    <ResponseField name="base_url" type="string" required>
      Base URL for the Obsidian Local REST API (e.g. [https://127.0.0.1:27124](https://127.0.0.1:27124))
    </ResponseField>

    <ResponseField name="period" type="string" required>
      Period type: daily, weekly, monthly, quarterly, or yearly
    </ResponseField>

    <ResponseField name="content" type="string" required>
      Markdown content to append to the periodic note
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "period": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Period"
        },
        "appended": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Appended"
        }
      },
      "required": [
        "success"
      ],
      "title": "AppendPeriodicNoteOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* The Local REST API runs on the user's own machine, so throughput is
  bound only by the local Obsidian instance; there is no vendor rate
  limit.
* `base_url` must be reachable from where the runtime executes
  (typically the same host). The default `https://127.0.0.1:27124` only
  works for a co-located process.
* **Error model**: non-2xx responses and timeouts are caught and
  returned as `success=False` + `error` rather than raising.

## Related integrations

<CardGroup cols={3}>
  <Card title="Grain" href="/integrations/tools/grain" />

  <Card title="Granola" href="/integrations/tools/granola" />

  <Card title="Reflect" href="/integrations/tools/reflect" />
</CardGroup>

## Links

* [Obsidian](https://obsidian.md)