Conditional writes (ETag / If-Match) so two clients can't silently overwrite each other

[ErikEvenson]

I'd like to float a small feature before writing any code, per CONTRIBUTING.

The problem. A PUT (or PATCH, POST append, DELETE) on a note always succeeds against whatever is there now. If two clients read a note, and both then write their edited copy, the second write silently discards the first. With one person typing in Obsidian that rarely matters. But since the MCP server, a vault often has several automated writers at once: an agent, a script, a second session, the user editing by hand. That's the setup where this bites, and there's no way for a careful client to protect itself today, because it can't ask "write this only if the note is still the version I read".

The proposal: standard HTTP conditional requests, opt-in and backward compatible.

• GET /vault/{path} (and the other single-note reads) returns an ETag for the file's current content, for example a hash of the bytes or of mtime plus size.
• Writes accept If-Match: <etag>. If the note has changed since that version, the server answers 412 Precondition Failed and writes nothing. That's the status the API already uses for PATCH target preconditions.
• PUT accepts If-None-Match: * to mean "create only; fail if the note exists".
• With neither header, behavior is exactly as today, so no existing client changes.
• The MCP write tools could take an optional expected_etag argument that maps to If-Match.

What I'd plan to include, if you're open to it:

• failing tests first, covering a match, a mismatch (412, file untouched), a missing file, and the no-header case unchanged;
• the docs and OpenAPI entries kept in sync, per AGENTS.md;
• the MCP tool descriptions.

Questions for you:

1. Is this something you'd want in core, or would you rather it live in an API extension?
2. Do you have a preference for what the ETag is derived from? A content hash is exact but costs a read; mtime plus size is cheap, but two writes within the same timestamp could collide.
3. Which routes should take it first? I'd suggest the single-note PUT, PATCH, POST and DELETE on /vault/ and the periodic-note equivalents.

Happy to adjust the scope to whatever fits the project best.

A note on how this was put together: I researched and drafted this proposal with Claude, an AI assistant, and any code I contribute would be AI-assisted too. I review everything myself, and I'd follow the workflow in your AGENTS.md: failing test first, small commits that each leave main green.

[coddingtonbear]

We already have If-Match support on the PATCH endpoint, but you're right, that support doesn't exist for anything else and it probably should. Unfortunately, I wasn't able to get this sorted out in time for the most recent release (today: 5.4.0), but I did ask an LLM to work through the first pass version: #383. I imagine this might land in the API during the next version, but that might be a few weeks out depending on what else happens!