bonik21/joplin-terminal-api repository overview

[ English ] | 한국어⁠

⁠Joplin Terminal REST API

A lightweight Docker image providing an externally accessible Joplin REST API (Web Clipper API) and HTTP Gateway powered by the official Joplin Terminal App on Linux.

⁠Features

• HTTP Gateway on port 41185
• Bearer token authentication
• Joplin Data API access (/notes, /folders, /tags, etc.)
• On-demand synchronization via POST /sync
• Shared sync lock to prevent concurrent synchronization
• Configurable background synchronization
• Automatic configuration from .env
• Lightweight Alpine-based Docker image

⁠Docker Images

Pre-built images are automatically published to Docker Hub:

bonik21/joplin-terminal-api

The image tag determines the Joplin Terminal App version.

For example:

bonik21/joplin-terminal-api:latest
bonik21/joplin-terminal-api:3.7.1
bonik21/joplin-terminal-api:dev
bonik21/joplin-terminal-api:3.7.1-dev

⁠Quick Start

Create a directory and a docker-compose.yml:

services:
  joplin-terminal-api:
    image: bonik21/joplin-terminal-api:latest
    container_name: joplin-terminal-api
    restart: unless-stopped
    ports:
      - "41185:41185"
    env_file:
      - .env
    volumes:
      - ./joplin-data:/root/.config/joplin

If you use OneDrive as the Joplin sync target, also expose port 9967 for the OAuth redirect:

ports:
  - "41185:41185"
  - "9967:9967"

Create a .env file:

JOPLIN_locale=en_GB
JOPLIN_dateFormat=DD/MM/YYYY
JOPLIN_timeFormat=HH:mm

JOPLIN_sync_target=9
JOPLIN_sync_9_path=https://your-joplin-server.com
JOPLIN_sync_9_username=your_username
JOPLIN_sync_9_password=your_password

JOPLIN_sync_interval=300

For an example of .env with more items, please refer to the following file: https://github.com/bonik21/joplin-terminal-api/blob/main/.env-example⁠

JOPLIN_VERSION is not required in .env. The Joplin version is determined by the Docker image tag.

Start the container:

docker compose up -d

View logs:

docker compose logs -f

⁠Initial Synchronization

On the first run, automatic synchronization is paused when the local database is empty.

Verify the configuration:

docker compose exec joplin-terminal-api joplin config

Check the status:

docker compose exec joplin-terminal-api joplin status

Then perform the initial synchronization:

docker compose exec joplin-terminal-api joplin sync

After the initial synchronization, the background sync daemon will automatically synchronize at the configured interval.

⁠API Authentication

Once the container is started, retrieve your token using:

cat joplin-data/settings.json

Or extract it with jq:

jq -r '."api.token"' ./joplin-data/settings.json

Use the token as a Bearer token:

Authorization: Bearer <YOUR_API_TOKEN>

⁠API Examples

⁠Health Check

No authentication required:

curl http://127.0.0.1:41185/ping

⁠Trigger Synchronization

curl -X POST http://127.0.0.1:41185/sync \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Possible responses include:

• 200 OK — Synchronization completed
• 401 Unauthorized — Invalid or missing token
• 409 Conflict — Another synchronization is already running
• 500 Internal Server Error — Synchronization failed

⁠List Notes

curl "http://127.0.0.1:41185/notes?fields=id,title,body,updated_time&limit=10" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

For the complete Joplin Data API specification, see the official Joplin documentation:

https://joplinapp.org/help/api/references/rest_api⁠

⁠Ports

Port 41184 is internal to the container and should not be exposed externally.

⁠Upgrading

To update the image:

docker compose pull
docker compose up -d

For a fixed Joplin version, specify the desired version as the image tag:

image: bonik21/joplin-terminal-api:3.7.1

The container also checks for newer Joplin releases at startup and reports an available update in the container logs.

⁠Data Persistence

Mounting ./joplin-data preserves the Joplin data across container recreation and upgrades.

The directory contains:

• SQLite database
• Joplin settings
• Resource attachments

volumes:
  - ./joplin-data:/root/.config/joplin

⁠Links

• GitHub: https://github.com/bonik21/joplin-terminal-api⁠
• Joplin Terminal Documentation: https://joplinapp.org/help/apps/terminal/⁠
• Joplin Data API: https://joplinapp.org/help/api/references/rest_api⁠

⁠License

This project is licensed under the MIT License.

For Joplin's own license, visit the official Joplin repository⁠.

Author: BoniK ([email protected]⁠ / https://bonik.me⁠)

Support: Buy me a coffee⁠