Version française ici.

Obsidian Inbox | API

An Obsidian plugin allowing you to receive files in your vault via a REST API, like an inbox.

This GitHub repo contains the source code required to run the backend. The plugin for Obsidian is available here.

Hosting

Install from source

Prerequisites:

• A recent version of Node.js and npm (comes with Node.js)
  • Obsidian Inbox has been tested with Node.js v24
  • You can check the installed version with the command node --version
• Git CLI

Download the code and dependencies:

git clone https://github.com/johan-perso/obsidianinbox-api.git
cd obsidianinbox-api

npm install
# or pnpm install

Configure the API:

mv .env.example .env
nano .env

The API password must be set with the environment variable AUTH_PASSWORD. This will also need to be configured in Obsidian.

Start the API:

npm start

# To start the API in the background, you can use PM2:
# npm install pm2 -g
# pm2 start index.js --name obsidianinbox-api

Installation with Docker

Prerequisites:

• Docker
• Git CLI

Download the source code:

git clone https://github.com/johan-perso/obsidianinbox-api.git
cd obsidianinbox-api

Configure the API:

mv .env.example .env
nano .env

The API password must be set with the environment variable AUTH_PASSWORD. This will also need to be configured in Obsidian.

Start the API:

docker-compose up -d --build
# To view logs: docker-compose logs -f

To avoid losing data, you can mount a volume going from the STORAGE_PATH directory (value from the .env file) to a physical directory on your host machine.

Configure the Obsidian plugin

These instructions can be found in the GitHub repository of the plugin.

Using the API

Add files to the inbox (POST /store)

curl -X POST "http://localhost:3000/store" \
  -H "Authorization: <AUTH_PASSWORD>" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"name":"test.md","content":"blablabla","force":false}]}'

# 'force' allows a file to be overwritten if not yet synchronized in the vault.

Get incoming files (GET /files)

curl -X GET "http://localhost:3000/files" \
	-H "Authorization: <AUTH_PASSWORD>"

Remove files from the inbox (DELETE /delete)

curl -X DELETE "http://localhost:3000/delete" \
  -H "Authorization: <AUTH_PASSWORD>" \
  -H "Content-Type: application/json" \
  -d '{"files":["test.md"]}'

License

MIT © Johan. Support this project if you want to help me 💙