webobsidian

WebObsidian Agent skill

Operate a WebObsidian vault over its Agent REST API at /api/v1. Everything is a plain HTTP call authenticated with an API key.

Credentials (read these first, every session)

Credentials live in ~/.webobsidian/credentials.json:

{ "baseUrl": "https://your-webobsidian.example.com", "apiKey": "wok_xxxxxxxx" }

Before the first request in a session, load them into shell variables:

BASE=$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.webobsidian/credentials.json")))["baseUrl"].rstrip("/"))')
KEY=$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.webobsidian/credentials.json")))["apiKey"])')

If ~/.webobsidian/credentials.json does not exist or a call returns 401:

1. Ask the user for their WebObsidian base URL (e.g. https://notes.example.com or http://host:8787) and their API key. They create the key in the app at Settings → API Keys (choose scopes read / write / search). Keys look like wok_….
2. Save it (never echo the key back):

   mkdir -p ~/.webobsidian && chmod 700 ~/.webobsidian
   cat > ~/.webobsidian/credentials.json <<JSON
   { "baseUrl": "<BASE_URL>", "apiKey": "<API_KEY>" }
   JSON
   chmod 600 ~/.webobsidian/credentials.json
   

3. Verify with the health + an authenticated call, then proceed.

Security rules: never print, log, or commit the API key. Never write it into vault notes. If a command would expose it, redact it.

Sanity check

curl -s "$BASE/api/v1/health"                          # liveness, no auth
curl -s -H "X-API-Key: $KEY" "$BASE/api/v1/tags" | head # confirms the key works

Authentication

Send the key as a header on every /api/v1 request (either form works):

X-API-Key: wok_xxx
Authorization: Bearer wok_xxx

Scopes per key: read, write, search. A call outside the key's scope returns 403. Rate-limited (default 120 req/min/key) → 429 when exceeded; back off and retry.