|
|
|
@@ -0,0 +1,245 @@
|
|
|
|
|
---
|
|
|
|
|
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
|
|
|
|
|
- [[spinup]]
|
|
|
|
|
- [[BOOTSTRAP]]
|
|
|
|
|
- [[STRUCTURE]]
|
|
|
|
|
- [[CLAUDE]]
|
|
|
|
|
- [[_agent/context/current-context]]
|
|
|
|
|
- [[projects/active/vault-foundation]]
|
