Section-level GET using existing document map infrastructure

[grimlor]

The REST API already supports targeted writes via PATCH v3 — you can append/prepend/replace content at a specific heading, block reference, or frontmatter field using the Target-Type and Target headers. And you can discover those targets by requesting the document map via Accept: application/vnd.olrapi.document-map+json on GET.

What's missing is the read side: there's no way to GET just the content of a specific section. If you want to read what's under ## Design Notes, you have to fetch the entire document and parse it yourself — even though the server already has the getDocumentMap infrastructure to locate that content.

Proposal: Allow the existing GET endpoints (/vault/*, /active/, /periodic/...) to accept the same Target-Type, Target, and Target-Delimiter headers that PATCH v3 already uses. When present, the response body would contain only the targeted section's content instead of the whole file. No new endpoints or content types needed.

Quick example:

GET /vault/project/notes.md
Target-Type: heading
Target: Design Notes
Authorization: Bearer ...

→ Returns only the text under the ## Design Notes heading.

This would reuse the getDocumentMap from markdown-patch that's already imported for PATCH v3, so the implementation surface is small. It would also be consistent with the existing header-based targeting pattern — same headers, same semantics, just on GET instead of PATCH.

Use case: AI agents and tools that work with large documents benefit from reading specific sections without transferring and re-parsing the full file. The document map GET already lets you discover what sections exist; this would let you read what's in a specific one.

Happy to submit a PR with tests if this sounds like a good direction.

[coddingtonbear]

I've been thinking about this, too, actually; so I'm thrilled that you're also interested in that kind of capability and bet we can together come up with a great way of making that possible!

There are always trade-offs, and I know the solution I've been thinking about has them just like everything else; so don't read this as me saying I am committed to a particular path already, but I'd like to talk over my approach, too, just so we have as many options on the table as possible.

My very early thoughts around this were that maybe we could give URL routes to document sub-parts. In the example you gave above, that might be:

GET /vault/project/notes.md/heading/Design%20Notes

where heading above is the Target-Type and Design%20Notes is the (URL-encoded) equivalent of the PATCH Target¹.

This has some pros:

1. It makes your document fully "addressable" via a URL, which feels kind of nice.
2. It might allow easier integration with other tools. Say you wanted to embed some part of your note content in some other document -- surely you can ask that tool to issue a GET request to a particular URL.
3. We could (eventually) also add support for other HTTP methods eventually (e.g. PUT for replacing the content of that section, just like you can do via PATCH in the existing route, POST for appending to it, PATCH for patching just that sub-part of the document).

& some cons:

1. It's a totally new API that doesn't follow the same patterns we already use for PATCH; your suggested solution, though, is just a simple addition of a few headers to GET that we already use in PATCH, so the learning curve is minimal.
2. It's going to be difficult to convince our documentation tooling into documenting this in a sensible way, but your suggested implementation will not be any more of a problem than we already have for our vault file endpoint.
3. It's probably a bit more complex to sort out than just adding support for those headers.

as I'm talking this through, it also seems like these two approaches for GET-ing sub-parts of a document are probably not mutually exclusive, and I could probably be convinced into supporting both options.

Footnotes

1. URL-encoded because of the space (& any other non-URL-safe symbols), but I imagine we'd let you target subheadings by placing a slash between each layer (e.g. /vault/project/notes.md/heading/Main/Subhead/). ↩

[grimlor]

I love that idea! I already did the simple, backwards-compatible work in a fork+branch, but your URL-based solution would enable so many more capabilities — especially the ones I've been thinking about with regards to token use when an AI needs to read and rewrite entire documents.

The "fully addressable document" framing is compelling, and the eventual support for PUT/POST/PATCH on sub-parts could make this a genuinely powerful interface for AI agents.

One thing worth flagging on the URL path approach: / is valid in Obsidian heading names (e.g. ## Notes/Config), so using it as the nesting delimiter could create ambiguity. Would heading name segments need to be URL-encoded to handle that case, or is there a different delimiter in mind for nesting levels?

Since we agree the two approaches aren't mutually exclusive, would it make sense to ship the header-based GET as a low-risk stepping stone in the near term? My fork already has it with tests, and it gets the immediate AI agent use case covered while the URL routing design gets worked out properly.

[coddingtonbear]

Definitely post a PR adding the support you've added there! I did briefly take a look at your fork, and (at just a brief glance) it looks reasonable to me and I don't imagine it'll encounter much friction from me. I think we'll definitely need to update the docs to document this, though.

About the literal / possibly being present in a URL: yeah! We'll definitely need to URL-encode any URL-unsafe characters, including that.

[grimlor]

Sorry for the delay. I updated the docs and created a PR.
#226

[coddingtonbear]

For those following along, the features @grimlor & I were discussing here were released as part of 3.6.0 !