bookmark-manager

name	bookmark-manager
description	Save and organize URLs with tags, full-text search, and auto-generated screenshots. Use when you need to save a URL for later, organize links into collections, search saved bookmarks, or import browser bookmarks. Triggers include "save this link", "bookmark", "organize URLs", "find that article I saved", or any task involving managing a personal URL library.

bookmark-manager

Self-hosted bookmark manager with tags, screenshots, and full-text search.

When to use

• Saving URLs to read or reference later
• Organizing links into collections by topic
• Searching across all saved bookmarks by content
• Importing browser bookmarks from Chrome/Firefox/Safari
• Sharing a curated collection of links publicly

Prerequisites

1. A running bookmark-manager instance (self-hosted or Docker)
2. Access to the web UI at the configured BASE_URL
3. Password set during first-run setup

Quick Start

# Run with Docker
docker compose up -d
# Open http://localhost:3000
# Set your password on the first-run screen
# Start saving bookmarks

Key Operations

Save a bookmark

POST to the API or use the web UI form:

curl -X POST http://localhost:3000/api/bookmarks \
  -H "Cookie: session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","tags":["dev","reference"]}'

Response: {"id":42,"url":"...","title":"Example","screenshot_status":"pending"}

Search bookmarks

curl "http://localhost:3000/api/search?q=javascript+promises&page=1" \
  -H "Cookie: session=your-session-token"

Returns paginated results with FTS5 <mark> snippets.

Import from browser

curl -X POST http://localhost:3000/api/import \
  -H "Cookie: session=your-session-token" \
  -F "file=@bookmarks.html"

Returns: {"imported":312,"skipped":28,"errors":2}

Export all bookmarks

curl http://localhost:3000/api/export \
  -H "Cookie: session=your-session-token" \
  > my-bookmarks.html

Share a collection

curl -X POST http://localhost:3000/api/collections/3/share \
  -H "Cookie: session=your-session-token"

Returns: {"shareUrl":"https://bookmarks.example.com/s/abc123..."}

API Reference

Method	Endpoint	Description
POST	/api/auth/login	Login with password
POST	/api/auth/logout	End session
GET	/api/bookmarks	List bookmarks (paginated)
POST	/api/bookmarks	Create bookmark
GET	/api/bookmarks/:id	Get single bookmark
PUT	/api/bookmarks/:id	Update bookmark
DELETE	/api/bookmarks/:id	Delete bookmark
POST	/api/bookmarks/bulk	Bulk tag/delete
GET	/api/search	Full-text search
GET	/api/collections	List collections
POST	/api/collections	Create collection
POST	/api/collections/:id/share	Share/unshare collection
GET	/api/tags	List tags with counts
POST	/api/import	Import Netscape HTML
GET	/api/export	Export Netscape HTML
GET	/api/share/:token	Public collection (no auth)
GET	/api/screenshot/queue	Screenshot queue status

Query Parameters

Param	Description
q	Search query (FTS5)
tag	Filter by tag name
collection	Filter by collection ID
pinned=1	Only pinned bookmarks
page	Page number (1-indexed)
per_page	Results per page (default 24, max 100)

Environment Variables

Variable	Default	Description
PORT	3000	HTTP port
DATA_DIR	./data	SQLite DB and screenshots directory
SESSION_SECRET	(required)	Session signing secret
SCREENSHOT_ENABLED	1	Enable Puppeteer screenshots (0/1)
SCREENSHOT_CONCURRENCY	2	Parallel Puppeteer workers
SCREENSHOT_TIMEOUT_MS	15000	Per-page capture timeout
SHARE_ENABLED	1	Allow public share links (0/1)
BASE_URL	http://localhost:3000	Public URL for share links

Troubleshooting

Screenshots not capturing

Check SCREENSHOT_ENABLED=1 and that Chromium is installed. View the queue at /screenshot-queue to see errors.

Import shows 0 imported

The HTML file may not be in Netscape bookmark format. Export from Chrome: Bookmark Manager > three-dot menu > Export bookmarks.

"Unauthorized" on all API calls

Session cookie expired or not sent. POST to /api/auth/login to get a new session cookie.

Search returns no results

FTS5 index may be out of sync. Rebuilding is triggered automatically on startup. Check that the query does not contain unbalanced quotes.