Introduction

Introduction to BitMarks API

BitMarks is a bookmark synchronization service that prioritizes security and privacy. Unlike traditional bookmark sync services, BitMarks implements true end-to-end encryption, meaning your bookmark data is encrypted on your device before it ever leaves, and only you hold the keys to decrypt it.

Core Principles

Zero-Knowledge Architecture

The server stores only encrypted blobs. It cannot read your bookmark titles, URLs, or any metadata.

Client-Side Encryption

All encryption and decryption happens in the browser or extension. Keys never leave your device.

Conflict Resolution

Automatic conflict resolution with Last-Write-Wins strategy ensures your data stays consistent across devices.

Edge-First

Built on Cloudflare Workers for low-latency responses worldwide with Durable Objects for real-time sync.

Architecture Overview

┌─────────────────┐     ┌──────────────────────────────────────┐
│  Browser        │     │  Cloudflare Edge                     │
│  Extension      │────▶│  ┌─────────────┐  ┌──────────────┐  │
│                 │     │  │   Workers   │  │    D1        │  │
│  - Encrypt      │◀────│  │   (Hono)    │──│  (SQLite)    │  │
│  - Decrypt      │     │  └─────────────┘  └──────────────┘  │
│  - Key Mgmt     │     │         │                            │
└─────────────────┘     │  ┌──────▼──────┐  ┌──────────────┐  │
                        │  │   Durable   │  │     R2       │  │
┌─────────────────┐     │  │   Objects   │  │  (Exports)   │  │
│  Web App        │────▶│  │  (Realtime) │  └──────────────┘  │
└─────────────────┘     │  └─────────────┘                    │
                        └──────────────────────────────────────┘

What You Can Do

Bookmark Management

Create encrypted bookmarks with full metadata
Update existing bookmarks while preserving encryption
Delete bookmarks (soft delete with recovery option)
List and search through your bookmark collection

Synchronization

Push local changes to the cloud
Pull changes from other devices
Real-time sync via WebSocket for instant updates
Bulk import from browser exports (Chrome, Firefox)

Data Export

Export your entire collection as encrypted backup
Download exports for offline storage
Manage export lifecycle

Encryption Details

The encryption envelope includes:

Nonce: 24-byte random value (unique per encryption)
Ciphertext: Encrypted bookmark JSON
Auth Tag: 16-byte authentication tag for integrity

API Response Format

All API responses follow a consistent JSON format:

Success Response

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 50
  }
}

Error Response

{
  "error": "Human-readable error message",
  "details": "Additional context (development only)"
}

Rate Limits

Endpoint Type	Limit
Authentication	10 requests/minute
Read Operations	100 requests/minute
Write Operations	30 requests/minute
Bulk Import	5 requests/minute

Next Steps

Quick Start

Get up and running in 5 minutes.

Quick Start Guide →

Authentication

Learn how to authenticate your requests.

Authentication →