API Overview

API Overview

The BitMarks API is a RESTful JSON API built on Cloudflare Workers with Hono framework. All endpoints are prefixed with /api/v1/.

Base URLs

Environment	Base URL
Production	https://app.bitmarks.sh/api/v1
Development	http://localhost:8787/api/v1

Content Type

All requests and responses use JSON format:

Content-Type: application/json

Authentication

Most endpoints require authentication via session cookie. See Authentication for details.

Cookie: bitmarks_session=YOUR_SESSION_TOKEN

Endpoint Summary

Health

Method	Endpoint	Description	Auth
GET	/health	API health check	No

Auth

Method	Endpoint	Description	Auth
POST	/auth/login	Initiate OAuth login	No
GET	/auth/callback	OAuth callback handler	No
POST	/auth/logout	End session	No
GET	/auth/session	Get current session	Cookie
POST	/auth/refresh	Refresh access token	Cookie

Bookmarks

Method	Endpoint	Description	Auth
GET	/bookmarks	List all bookmarks	Cookie
POST	/bookmarks	Create bookmark	Cookie
GET	/bookmarks/:id	Get single bookmark	Cookie
PUT	/bookmarks/:id	Update bookmark	Cookie
DELETE	/bookmarks/:id	Delete bookmark	Cookie

Sync

Method	Endpoint	Description	Auth
GET	/sync/status	Get sync status	Cookie
POST	/sync/pull	Pull changes	Cookie
POST	/sync/push	Push changes	Cookie
POST	/sync/import	Bulk import	Cookie
GET	/sync/realtime	WebSocket upgrade	Cookie

Exports

Method	Endpoint	Description	Auth
GET	/exports	List exports	Cookie
POST	/exports	Create export	Cookie
GET	/exports/:id	Download export	Cookie
DELETE	/exports/:id	Delete export	Cookie

Request Format

Headers

Header	Required	Description
Content-Type	Yes (POST/PUT)	Must be application/json
Cookie	Yes (authenticated)	Session cookie
X-Device-ID	No	Device identifier for sync

Request Body

POST and PUT requests accept JSON body:

{
  "encrypted_data": "base64-encoded-encrypted-json",
  "data_hash": "sha256-hash-of-plaintext"
}

Response Format

Success Response

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

Error Response

{
  "error": "Human-readable error message"
}

In development mode, errors may include additional details:

{
  "error": "Something went wrong",
  "stack": "Error: Something went wrong\n    at ..."
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
302	Redirect (OAuth callback)
400	Bad Request - Invalid input
401	Unauthorized - Authentication required
404	Not Found
426	Upgrade Required - WebSocket expected
500	Internal Server Error
501	Not Implemented

Pagination

List endpoints support pagination:

{
  "data": [...],
  "meta": {
    "total": 1000,
    "page": 1,
    "limit": 100
  }
}

Query parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 100, max: 1000)

Rate Limiting

Caution

Rate limits are applied per-user based on the authenticated session.

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

When rate limited, you’ll receive a 429 Too Many Requests response.

CORS

The API supports CORS for browser-based clients:

• Allowed Origins: Configured per environment
• Allowed Methods: GET, POST, PUT, DELETE, OPTIONS
• Allowed Headers: Content-Type, Authorization, X-Device-ID
• Credentials: Allowed (for cookies)

Encryption

Note

All bookmark data is encrypted client-side before transmission. See Encryption Guide for implementation details.

The API expects and returns encrypted data envelopes:

interface EncryptedData {
  encrypted_data: string;  // Base64-encoded ciphertext
  data_hash: string;       // SHA-256 of plaintext (for integrity)
}

OpenAPI Specification

The full OpenAPI 3.1 specification is available at:

/openapi.yaml

You can use this with tools like Swagger UI, Postman, or code generators.