first push
This commit is contained in:
@@ -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]]
|
||||
Reference in New Issue
Block a user