| 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
- A running bookmark-manager instance (self-hosted or Docker)
- Access to the web UI at the configured BASE_URL
- Password set during first-run setup
Quick Start
docker compose up -d
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.
