Obsidian vs Voiden: When to Use Both

If you're a developer with an Obsidian vault, there's probably an APIs folder in it somewhere. Curl commands. Auth quirks. A note called payments-endpoint-gotchas. It works, mostly. Until the API changes and the vault doesn't.

Quick definitions, in case one of the two is new to you.

Obsidian is a note-taking app built on plain Markdown files stored locally in a folder it calls a vault. Its core strength is connected thinking: links between notes, backlinks, a graph view, and a large community plugin ecosystem that extends it in almost any direction. Free for personal use, and your notes stay yours, as files on your disk.

Voiden is an open-source, offline-first API workspace. API requests, tests, and docs live together in .void files, which are plain Markdown with executable request blocks, stored in the same Git repo as your code. It supports REST, GraphQL, gRPC, and WebSockets through plugins, requires no account, and is licensed under Apache 2.0.

Here's the short version of how they relate: Obsidian is a notes workspace, a place to think. Voiden is an API workspace, a place where API requests, tests, and docs live in the repo as executable files. They overlap on the surface: both Markdown, both local-first, both work offline, both extensible through plugins. That overlap is exactly why people confuse the jobs.

This isn't a takedown. Obsidian is one of the tools we genuinely admire. Its community-driven plugin ecosystem directly shaped how we approached Voiden's own plugin model, and one of our early posts was literally titled something like "we threw curl and Obsidian in a blender." The point of this post is narrower: where one tool's job ends and the other's begins.

Same format, different jobs

The confusion is understandable. Both tools bet on plain Markdown files on your disk, no cloud gatekeeping, no proprietary database. If you believe in that bet, and we do, it's natural to try to make one tool do everything.

But the jobs are structurally different, and it shows in three places.

Personal knowledge vs. team contract. Obsidian: your vault is yours. Associative, half-finished, organized however your brain works. Voiden: .void files live in the repo, next to the code, reviewed in pull requests like everything else. Result: a vault answers to you. A repo answers to the team.

Notes about requests vs. files that are requests. Obsidian: a curl command in a note is text. To use it, you copy it somewhere else and hope it's still current. Voiden: a request block in a .void file executes. Hit Cmd/Ctrl+Enter and it runs, with the auth block, params, and assertions it was written with. Result: the documentation and the working request are the same file. There is no second place to forget to update.

Sync vs. version control. Obsidian: sync keeps your devices consistent. Voiden: Git keeps your team consistent. A change to an endpoint shows up as a diff a reviewer can read: added an OAuth block, updated the base URL, fixed the login endpoint. Result: API changes get reviewed the way code changes do, instead of drifting silently in someone's personal notes.

There's a short video showing what that Git-native workflow actually looks like in practice, if you'd rather watch than read: https://youtu.be/fekca2eWLDY

The wrinkle: Voiden takes notes too

Worth being honest about, because it complicates the neat split above. A .void file is Markdown. You can write prose in it. The endpoint gotcha, the warning about rate limits, the reason the auth flow is weird: all of that can sit in the same file as the request it describes. And because the file lives in Git, those notes get versioned, diffed, and reviewed the way code is.

So in a real sense, Voiden is Obsidian for API work. The note about the endpoint and the endpoint itself stop being two artifacts. When the request changes, the explanation sitting two lines above it changes in the same commit.

Which sharpens the actual dividing line. It was never really prose versus executable. It's personal versus shared. Thinking that only needs to serve you, half-formed, cross-project, three ideas deep in a linked graph, belongs in your vault. Anything about an API that a teammate would benefit from reading, prose included, belongs in the repo, inside the .void file, next to the thing it explains.

What Obsidian does that Voiden shouldn't try to do

Discovery. Research. Linking half-formed ideas until they turn into formed ones. Meeting notes that mention an API three weeks before anyone writes a request against it. The graph view finding a connection between two projects you'd forgotten were related.

That's real work, and it's work Voiden has no business doing. Voiden is deliberately narrow: it handles the part of the API lifecycle that needs to be executable, testable, and reviewable. Everything upstream of that, the reading, the comparing, the "wait, didn't we evaluate this vendor last year?", belongs in a thinking tool. Obsidian is a very good one.

The handoff

So the practical rule is simple. Explore in Obsidian. Commit in Voiden.

While you're evaluating an API, reading docs, pasting response samples, arguing with yourself in a note, that's vault material. The moment a request becomes real, meaning a teammate might need it, a test should cover it, or a change to it should be reviewed, it belongs in the repo as a .void file.

A note about an API is a memory. A .void file is a contract.

The handoff itself is cheap, because both sides are Markdown. You're not exporting from one proprietary format and importing into another. You're moving a fenced code block out of a note and into a file that runs.

Where the pairing actually shines

A few real workflows where the split earns its keep:

Evaluating a third-party API. The comparison lives in Obsidian: pricing notes, response samples from three vendors, links to their docs, your own verdict. Once you pick one, the winner's auth setup and first requests get built as .void files in the repo. The losers stay in the vault, which is exactly where you'll want them in a year when someone asks "did we ever look at X?"

Debugging an incident. The timeline, the hypotheses, the 2 a.m. suspicions all go in a note. But the request that finally reproduced the bug becomes a .void file with an assertion, committed next to the fix. The note explains what happened. The file makes sure it can't happen again quietly.

Designing a new endpoint. Naming debates, edge cases, half-serious "what if we just..." ideas: vault. The agreed request and response shape: a .void file in the same PR that implements the endpoint, so the reviewer sees the contract and the code together.

Onboarding notes. Your personal "how our stack actually works" vault is great for a new teammate to skim. But instead of pasting curl commands into it, link to the .void files in the repo. The notes explain the system; the contracts stay in one place, current, and runnable.

The pattern is the same each time. The thinking stays personal. The contract goes to the team.

Getting started

If you already keep API notes in Obsidian, try this once:

1. Download Voiden and open your project's repo as a workspace.
2. Pick one request from your vault, a real one your team actually uses, and rebuild it as a .void file.
3. Commit it and open a PR.

If the diff review feels better than the note did, you'll know where the line is for you.

FAQ

Can Obsidian work as an API client? With enough plugins and copy-pasting, sort of. But notes describe requests; they don't run them, version them with the code, or fail in CI when the API changes. Those are different jobs.

Does Voiden replace Obsidian? No. Voiden covers what your team shares about APIs: contracts, tests, docs, and the notes attached to them, all in the repo. Personal thinking, research, and cross-project knowledge still belong in a notes tool.

Can I use both without duplicating work? Yes, that's the whole argument. Keep exploration in your vault, and move a request into a .void file once it's real. Both are plain Markdown, so the handoff is a copy-paste, not a migration.

Is Voiden open source? Yes, fully, under the Apache 2.0 license, and funded by ApyHub's marketplace revenue rather than VC money. The repo is public at github.com/VoidenHQ/voiden.

Download Voiden at https://voiden.md/download, or poke around the repo at https://github.com/VoidenHQ/voiden if you want to see how it works first.