Obsidian REST API

Obsidian Local REST API (fallback for missing MCP methods)

Overview

The connected obsidian MCP server exposes only a subset of the Obsidian Local REST API (plugin obsidian-local-rest-api, v4.1.x). This skill provides the full API surface plus an authenticated wrapper, so a missing MCP method is called over HTTP instead of being worked around with hacks (e.g. delete+recreate to rename).

When to use

1. First choice is always the mcp__obsidian__* tools — read, append, patch, delete, simple/complex search, periodic-note read. Do not use this skill for those.
2. Fall back here only when the needed operation has no MCP tool. The REST-only operations are:
   • Move / rename a note (MOVE /vault/{filename}) — preserves history, updates internal links.
   • Overwrite a whole file atomically (PUT /vault/{filename}) — instead of MCP delete+recreate.
   • Active-file operations (/active/ GET/PUT/POST/PATCH/DELETE) — the note open in the UI.
   • Run an Obsidian command (GET /commands/, POST /commands/{id}/).
   • Open/focus a note in the UI (POST /open/{filename}).
   • List all tags with counts (GET /tags/).
   • Date-specific / mutating periodic notes (/periodic/{period}/... PUT/POST/PATCH/DELETE).

How to call

Use the wrapper scripts/olrapi.sh — it resolves host/port/API-key from the obsidian MCP server config (~/.claude.json) or OBSIDIAN_* env vars, and handles the self-signed TLS cert. Never hardcode the key.

S=~/.claude/skills/obsidian-rest-api/scripts/olrapi.sh

# rename/move a note (the most common reason to reach for this skill)
"$S" MOVE "/vault/Path/To/Old Name.md" -H 'Destination: Path/To/New Name.md'

# move into a folder, keeping the filename (trailing slash on Destination)
"$S" MOVE "/vault/Inbox/todo.md" -H 'Destination: Archive/'

# atomically overwrite a whole note
"$S" PUT "/vault/Path/Note.md" -H 'Content-Type: text/markdown' --data-binary @/tmp/new_body.md

# read a note as structured JSON (frontmatter + tags + stat)
"$S" GET "/vault/Path/Note.md" -H 'Accept: application/vnd.olrapi.note+json'

# list all tags, run a command, open a note
"$S" GET /tags/
"$S" GET /commands/
"$S" POST "/commands/editor:toggle-bold/"
"$S" POST "/open/Path/Note.md?newLeaf=true"

The wrapper appends <<HTTP nnn>> after the body so the status code is visible. Success codes: 200/204. Check 409 on MOVE (destination exists — add -H 'Allow-Overwrite: true' to force).

Path & encoding rules

• {filename} is vault-relative (no leading slash on the vault path itself). Spaces are fine in the shell-quoted argument.
• MOVE Destination rejects absolute (/…) paths and anything escaping the vault; percent-encode non-ASCII (r%C3%A9sum%C3%A9.md).
• Targeting a sub-part of a note (heading/block/frontmatter) uses Target-Type + Target headers on GET/PATCH/POST — see the reference.

Full reference

references/api_reference.md — every path, method, header enum (Operation, Target-Type, Target-Scope, period), the MOVE contract, search (JsonLogic/Dataview), and the complete MCP↔REST coverage map. Load it when composing a non-trivial call or when unsure whether an operation exists.

Regenerate against the live instance if the plugin was updated: scripts/olrapi.sh GET /openapi.yaml (and GET / shows the version + any apiExtensions).