---
type: reference
status: active
created: 2026-06-01
updated: 2026-06-02
tags: [reference, api, obsidian, rest, plugin]
agent_written: true
source_notes: []
---

# Obsidian Local REST API

## Summary
This is the operational command reference for reaching the **goldbrain** vault over the
[Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api).
It is the contract a CoWork plugin or any REST client follows to read and write memory.
Paths address the vault **at its root** (e.g. `/vault/_agent/...`), matching the layout
defined in STRUCTURE and verified by BOOTSTRAP.

## Connection

| Setting | Value |
|---------|-------|
| Base URL | `https://goldbrainapi.mpm.to` |
| Auth | `Authorization: Bearer <key>` on every request |
| Content type (writes) | `text/markdown` (or `application/json` for frontmatter patches) |

**Never store the key in the vault.** It lives in the local environment / plugin config,
not in any note. The examples below read it from the shell:

```bash
export OBSIDIAN_REST_API_URL="https://goldbrainapi.mpm.to"
export OBSIDIAN_REST_API_KEY="<bearer-token>"
AUTH="Authorization: Bearer ${OBSIDIAN_REST_API_KEY}"
BASE="${OBSIDIAN_REST_API_URL}"
```

> TLS note: `goldbrainapi.mpm.to` presents a valid certificate (reverse proxy →
> `192.168.86.15:27124`), so `-k` is **not** needed. Add `-k` only if the endpoint is ever
> switched to a self-signed certificate.

---

## Reading Files

```bash
curl -s -H "$AUTH" "$BASE/vault/_agent/context/current-context.md"
```

Returns raw file content (`text/markdown`). A `404` means the file does not exist.

```bash
# Read only one heading's content (full heading path, :: delimited)
curl -s -H "$AUTH" \
  "$BASE/vault/_agent/memory/semantic/operator-preferences.md/heading/Operator%20Preferences%3A%3AFact%20%2F%20Pattern"
```

---

## Listing Directories

```bash
curl -s -H "$AUTH" "$BASE/vault/_agent/sessions/"   # trailing slash required
```

Returns JSON: `{ "files": [...], "folders": [...] }`.

---

## Appending Content (POST)

`POST` appends to the **end** of an existing file; it creates the file if absent.

```bash
cat > /tmp/obs_entry.md << 'OBSEOF'
- 2026-06-02: quick note to triage later
OBSEOF

curl -s -X POST -H "$AUTH" -H "Content-Type: text/markdown" \
  --data-binary @/tmp/obs_entry.md \
  "$BASE/vault/inbox/captures/inbox.md"
```

---

## Creating or Overwriting Files (PUT)

`PUT` creates a new file or fully overwrites one. Missing parent directories are created automatically.

```bash
cat > /tmp/obs_file.md << 'OBSEOF'
---
type: session-log
status: complete
created: 2026-06-02
updated: 2026-06-02
tags: []
agent_written: true
source_notes: []
---

# Session: <title>

## Related
- [[projects/active/some-project]]
OBSEOF

curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" \
  --data-binary @/tmp/obs_file.md \
  "$BASE/vault/_agent/sessions/2026-06-02-1430-my-session.md"
```

Include the canonical frontmatter (see STRUCTURE / BOOTSTRAP §4) and set `agent_written: true`
on agent-generated notes. Cross-reference links go in a body `## Related` section, never in frontmatter.

---

## Patching a Specific Section (PATCH)

`PATCH` edits inside a file without rewriting it. Target and operation are set via headers.

### Append under a heading

**Heading targets must be the FULL heading path, `::`-delimited from the top-level heading.**
A bare subheading name returns `400 invalid-target` (errorCode 40080). Verified against
API v4.1.2. Example: `## Fact / Pattern` under `# Operator Preferences` →
`Target: Operator Preferences::Fact / Pattern`. Percent-encode non-ASCII; spaces are fine.

```bash
cat > /tmp/obs_patch.md << 'OBSEOF'
Bryan prefers concise status updates — lead with the decision.
OBSEOF

curl -s -X PATCH -H "$AUTH" \
  -H "Operation: append" \
  -H "Target-Type: heading" \
  -H "Target: Operator Preferences::Fact / Pattern" \
  -H "Content-Type: text/markdown" \
  --data-binary @/tmp/obs_patch.md \
  "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
```

To discover exact heading paths, GET the note with `Accept: application/vnd.olrapi.document-map+json`;
it returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }` — copy the
heading string verbatim into `Target`.

### Replace a heading's content entirely

Same call with `Operation: replace` — e.g. to refresh a project's `Project Name::Current status`.

### Prepend under a heading

Same call with `Operation: prepend`.

### Patch a frontmatter field

```bash
curl -s -X PATCH -H "$AUTH" \
  -H "Operation: replace" \
  -H "Target-Type: frontmatter" \
  -H "Target: updated" \
  -H "Content-Type: application/json" \
  --data '"2026-06-02"' \
  "$BASE/vault/projects/active/vault-foundation.md"
```

Use this to keep `updated:` and `status:` current after a write.

---

## Searching

```bash
curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=weekly+review"
```

Returns an array of `{ filename, score, matches: [{ context, match }] }`.

---

## Deleting Files

```bash
curl -s -X DELETE -H "$AUTH" "$BASE/vault/archive/notes/old-note.md"
```

Only on an explicit request. Deletion is destructive; memory is append-friendly.

---

## URL-Encoding Notes

- Path separators (`/`) in the vault path are **literal** — do not encode them.
- Spaces in filenames or heading targets in a URL: use `%20`.
- Nested heading levels in a URL path: use `%3A%3A` for `::`.
- Heading text in the `Target:` header: the **full heading path** joined by `::` (e.g. `Operator Preferences::Fact / Pattern`), no `#`; spaces fine; percent-encode non-ASCII.

---

## Memory Routing Map

Where each kind of write lands in goldbrain (mirrors BOOTSTRAP §3 and the taxonomy in STRUCTURE).

| Situation | Vault path | Method |
|-----------|-----------|--------|
| Unsorted / quick capture | `inbox/captures/inbox.md` (date-prefixed line) | POST |
| Raw imported material | `inbox/imports/` | PUT |
| Operator preference / durable fact | `_agent/memory/semantic/operator-preferences.md` | PATCH |
| Other durable facts, patterns | `_agent/memory/semantic/<slug>.md` | PUT |
| Event record (what happened) | `_agent/memory/episodic/<slug>.md` | PUT |
| Short-lived, time-boxed state | `_agent/memory/working/<slug>.md` | PUT |
| Task-scoped context / focus | `_agent/context/current-context.md` | PATCH / PUT |
| Working-session log | `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md` | PUT |
| Long-running project state | `projects/active/<slug>.md` | PUT + PATCH |
| Non-obvious decision (ADR) | `decisions/by-date/YYYY-MM-DD-<slug>.md` (mirror `by-project/`) | PUT |
| Person context | `resources/people/<name>.md` | PUT / PATCH |
| Concept / reference note | `resources/concepts/` or `resources/references/` | PUT |
| Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH |
| Periodic review | `reviews/{weekly,monthly,quarterly,annual}/` | PUT |

**Slug rules:** kebab-case, ASCII, ~40 chars max. Every file carries canonical frontmatter (no `[[wikilinks]]` in it).

---

## Plugin Readiness Checklist

- [ ] Base URL reachable; returns `401` without the key, content with it.
- [ ] `GET /vault/BOOTSTRAP.md` succeeds (vault bootstrapped — else run BOOTSTRAP).
- [ ] A test `PUT` into `_agent/sessions/` creates the file and parent dirs.
- [ ] A `PATCH` `Target-Type: heading` append with a full `::` path lands under the right heading.
- [ ] `POST /search/simple/?query=...` returns scored matches.
- [ ] Key supplied via env / plugin config only — never written into a note.

## Sources / Notes
Adapted from the working `obsidian-memory` plugin reference, retargeted to goldbrain's
vault-root layout and the `goldbrainapi.mpm.to` host. Record host-binding or plugin-specific
conventions here as they emerge.

## Related
- [[_agent/context/current-context]]
- [[projects/active/vault-foundation]]