# bookmarks.md

> Sync, search, and digest your X (Twitter) bookmarks — with a developer API and AI agent support built in.

bookmarks.md is a web service that automatically syncs your X bookmarks to a searchable database and delivers them as beautifully formatted email digests (daily or weekly). It exposes a REST API for programmatic access, making it easy to integrate with AI agents and developer workflows.

## Product

- **Free to use** for personal X bookmark management
- Sign in with X OAuth to connect your account
- One-click sync pulls all new bookmarks via the X Bookmarks API v2
- Search and browse your full bookmark history in a clean dashboard
- Daily digest: sent every day at 9 AM UTC
- Weekly digest: sent every Monday at 9 AM UTC
- On-demand send: trigger a digest instantly from the dashboard

## For AI Agents

### Skill Discovery

bookmarks.md follows the open [skills standard](https://github.com/cloudflare/skills). Agents can discover and consume the skill definition to learn how to use the API:

- **Skill URL**: https://bookmarks.md/.well-known/skills/default/skill.md
- **Short redirect**: https://bookmarks.md/docs/skill
- **Install via skills CLI**: `npx skills add https://bookmarks.md`

### API Reference

**Base URL**: `https://bookmarks.md/api/v1`

**Authentication**: Bearer token — generate one at https://bookmarks.md/dashboard/settings (tokens start with `bm_`)

**Endpoints**:

#### GET /api/v1/bookmarks

Fetch, search, and filter bookmarks.

Query parameters:
- `q` (string) — Full-text search across tweet content, author name, and username
- `author` (string) — Filter by exact X username (e.g. `author=typescript`)
- `cursor` (string) — Pagination cursor from a previous response's `nextCursor` field
- `limit` (integer, 1–100, default 50) — Number of results per page

Response shape:
```json
{
  "bookmarks": [
    {
      "tweetId": "1893847562001",
      "text": "Tweet content here",
      "tweetUrl": "https://x.com/username/status/1893847562001",
      "authorName": "Display Name",
      "authorUsername": "username",
      "createdAt": "2025-02-01T10:00:00.000Z",
      "savedAt": "2025-02-01T14:30:00.000Z",
      "note": "AI-generated commentary on the tweet (may be null)"
    }
  ],
  "nextCursor": "cursor_string_or_null",
  "total": 42
}
```

**Rate limit**: 100 requests per minute per user

### Common Agent Workflows

1. **Fetch all bookmarks**: Paginate using `nextCursor` until it returns `null`
2. **Semantic search**: Use `?q=topic` to find bookmarks about a subject, then reason over results
3. **Author analysis**: Use `?author=username` to see all bookmarks from a specific person
4. **Recent bookmarks**: Use default parameters — results are sorted newest first

### Example Request

```bash
curl -H "Authorization: Bearer bm_YOUR_TOKEN" \
  "https://bookmarks.md/api/v1/bookmarks?q=typescript&limit=10"
```

## Key Features

- **Bookmark Sync**: Incremental fetching via high-water mark — only new bookmarks on each sync
- **Email Digests**: Daily or weekly, delivered via Resend with author avatars and tweet links
- **Search**: Full-text search across tweet content, authors, and usernames
- **Developer API**: RESTful JSON API with pagination, search, and author filtering
- **AI-Ready**: SKILL.md at the well-known URL for automatic agent discovery
- **Privacy**: Your data is never sold or shared. Delete your account and data at any time.

## Technology

- Framework: Next.js 16 (App Router), React 19
- Language: TypeScript
- Database: Turso (SQLite at the edge via libSQL)
- ORM: Drizzle
- Authentication: X OAuth via Auth.js (NextAuth)
- Email: Resend + React Email
- Hosting: Vercel

## Links

- Homepage: https://bookmarks.md
- Documentation: https://bookmarks.md/docs
- API skill file: https://bookmarks.md/.well-known/skills/default/skill.md
- GitHub / issue tracker: https://github.com/jaipandya/bookmarks-md/issues
- Built by: @jaipandya on X (https://x.com/jaipandya)

## Terms

- Free for personal use
- API rate limit: 100 requests/minute per user
- No data selling or third-party sharing
- Users can delete their data at any time from the dashboard

---

Last updated: 2026-02-20