Quick Start

Quick Start Guide

This guide will help you make your first API calls to BitMarks in just a few minutes.

Prerequisites

• A BitMarks account (sign up at app.bitmarks.sh)
• Basic familiarity with REST APIs
• A tool for making HTTP requests (curl, Postman, or your favorite HTTP client)

1. Check API Health

   First, verify the API is operational:

   curl

   curl https://app.bitmarks.sh/api/v1/health

   JavaScript

   const response = await fetch('https://app.bitmarks.sh/api/v1/health');
   const data = await response.json();
   console.log(data);

   Expected Response:

   {
     "name": "@bitmarks.sh/api",
     "version": "2.0.0-alpha",
     "environment": "production",
     "status": "healthy",
     "timestamp": "2025-01-15T12:00:00.000Z"
   }

2. Authenticate

   BitMarks uses OAuth 2.0 via WorkOS AuthKit. To authenticate:

   curl

   # Initiate login flow
   curl -X POST https://app.bitmarks.sh/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"returnTo": "/"}'

   JavaScript

   const response = await fetch('https://app.bitmarks.sh/api/v1/auth/login', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ returnTo: '/' })
   });
   const { authorizationUrl } = await response.json();
   
   // Redirect user to authorizationUrl
   window.location.href = authorizationUrl;

   Response:

   {
     "authorizationUrl": "https://authkit.workos.com/..."
   }

   Redirect the user to the authorizationUrl. After authentication, they’ll be redirected back with a session cookie set.

3. Verify Session

   After the OAuth callback, verify your session:

   curl

   curl https://app.bitmarks.sh/api/v1/auth/session \
     -b "bitmarks_session=YOUR_SESSION_COOKIE"

   JavaScript

   const response = await fetch('https://app.bitmarks.sh/api/v1/auth/session', {
     credentials: 'include' // Include cookies
   });
   const session = await response.json();
   console.log(session);

   Response:

   {
     "authenticated": true,
     "user": {
       "user_id": "user_01ABC123",
       "email": "you@example.com",
       "name": "Your Name",
       "email_verified": true
     }
   }

4. Check Sync Status

   See your current sync status:

   curl

   curl https://app.bitmarks.sh/api/v1/sync/status \
     -b "bitmarks_session=YOUR_SESSION_COOKIE"

   JavaScript

   const response = await fetch('https://app.bitmarks.sh/api/v1/sync/status', {
     credentials: 'include'
   });
   const status = await response.json();
   console.log(status);

   Response:

   {
     "user_id": "user_01ABC123",
     "last_sync": 1735430400000,
     "pending_changes": 0,
     "conflict_count": 0,
     "total_bookmarks": 150
   }

5. Pull Changes

   Fetch all bookmarks (or changes since a timestamp):

   curl

   curl -X POST https://app.bitmarks.sh/api/v1/sync/pull \
     -H "Content-Type: application/json" \
     -b "bitmarks_session=YOUR_SESSION_COOKIE" \
     -d '{"since": 0, "limit": 100}'

   JavaScript

   const response = await fetch('https://app.bitmarks.sh/api/v1/sync/pull', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     credentials: 'include',
     body: JSON.stringify({ since: 0, limit: 100 })
   });
   const { changes, has_more } = await response.json();

   Response:

   {
     "changes": [
       {
         "id": "sync_abc123",
         "entity_type": "bookmark",
         "entity_id": "bm_xyz",
         "operation": "create",
         "encrypted_data": "eyJhbGciOi...",
         "data_hash": "a1b2c3d4...",
         "timestamp": 1735430400000
       }
     ],
     "last_sync_timestamp": 1735430400000,
     "has_more": false
   }

Working with Encrypted Data

Caution

The encrypted_data field contains your bookmark data encrypted with your key. You’ll need to decrypt it client-side using the encryption utilities.

Encryption Example

import { encryptObject, decryptObject } from '@bitmarks.sh/core';

// Your encryption key (derived from password)
const key = await deriveKey(password, salt);

// Encrypt a bookmark
const bookmark = {
  id: 'bm_' + crypto.randomUUID(),
  title: 'Example Bookmark',
  url: 'https://example.com',
  source: 'bookmarks',
  dateAdded: new Date().toISOString()
};

const encrypted = await encryptObject(bookmark, key);
// { nonce: '...', ciphertext: '...', tag: '...' }

// Decrypt received data
const decrypted = await decryptObject(encrypted, key);
// { id: 'bm_...', title: 'Example Bookmark', ... }

Next Steps

Now that you’ve made your first API calls:

• Authentication Guide - Deep dive into OAuth flow
• Sync API Reference - Full sync endpoint documentation
• Encryption Guide - Understanding the encryption scheme
• Real-time Sync - WebSocket setup for instant updates

Common Issues

401 Unauthorized

Your session cookie may be expired. Call /auth/refresh to get a new access token, or re-authenticate.

CORS Errors

When calling from a browser, ensure you’re:

1. Using credentials: 'include' in fetch
2. Calling from an allowed origin

Empty Sync Response

If you’re a new user, you won’t have any bookmarks yet. Try importing some first via the browser extension or the import endpoint.