REST API

A REST API plugin for Obsidian — clean replacement for obsidian-local-rest-api with extended endpoints and secure-by-default design.

Compatible with obsidian-mcp-tools for Claude Code integration.

Features

• Full REST API — CRUD on vault files, active file, periodic notes
• Extended endpoints — tags, tasks, backlinks, links, outline, properties
• Search — simple text, Dataview DQL, JsonLogic, semantic (via Smart Connections)
• Templates — Templater integration
• PATCH engine — content-based heading parsing, block/frontmatter targeting, and search-replace for precise text substitution
• Dual-mode PATCH — JSON body (preferred) or HTTP headers (backward-compatible)
• HTTPS — self-signed certificate with configurable SANs
• Extension API — third-party plugins can register custom routes
• Constant-time auth — timing-safe API key comparison

Installation

Manual

1. Download main.js, manifest.json, and styles.css from the latest release
2. Create folder .obsidian/plugins/obsidian-api/ in your vault
3. Copy the files into that folder
4. Enable the plugin in Obsidian Settings → Community Plugins

Development

git clone https://github.com/vigeron/obsidian-api.git
cd obsidian-api
npm install
npm run dev

Configuration

Open Obsidian Settings → Obsidian API:

API Reference

Authentication

All endpoints (except GET / and GET /obsidian-api.crt) require a Bearer token:

Authorization: Bearer <your-api-key>

Endpoints

PATCH Format

JSON body (preferred):

{
  "operation": "append",
  "targetType": "heading",
  "target": "Section::Subsection",
  "content": "New content\n",
  "targetDelimiter": "::",
  "createTargetIfMissing": true
}

Search-replace (find and replace text):

{
  "operation": "search-replace",
  "target": "- [ ] Task 1",
  "content": "- [x] Task 1"
}

No targetType required — replaces the first occurrence of target with content anywhere in the file.

HTTP headers (backward-compatible):

Operation: append
Target-Type: heading
Target: Section%3A%3ASubsection
Content-Type: text/markdown

Content Negotiation

Use the Accept header to control response format:

Extension API

Third-party plugins can register custom routes:

const api = app.plugins.plugins["obsidian-api"]?.getPublicApi(manifest);
if (api) {
  api.addRoute("/my-endpoint/")
    .get((req, res) => {
      api.sendSuccess(res, { hello: "world" });
    });
}

Network Usage

This plugin starts a local HTTP/HTTPS server on your machine (default: 127.0.0.1). It does not connect to any external services or send data over the internet.

The server listens only on the configured binding host and port, accepting REST API requests from local clients (e.g. MCP tools, scripts, browser extensions). All communication stays on your machine unless you explicitly change the binding host to a non-loopback address.

Optional integrations (Smart Connections, Dataview, Templater) communicate only with locally installed Obsidian plugins — no network requests are made on their behalf.

Security

• API key generated with cryptographic random bytes (SHA-256)
• Constant-time token comparison (prevents timing attacks)
• Self-signed HTTPS certificate (2048-bit RSA, SHA-256)
• Configurable CORS origin
• Error responses never expose internal details (stack traces, file paths)
• Settings UI uses Obsidian Setting API (no innerHTML)

License

MIT

Support

If this plugin is useful to you and you'd like to support further development, you can do so on Ko-fi.