How does bookmark syncing work?

One-click sync from the dashboard pulls all new bookmarks since your last sync using the X Bookmarks API v2 with incremental fetching via high-water mark. Only new bookmarks are fetched on each sync — no duplicates, no redundant API calls.

What digest email frequencies are available?

Daily digests (every day at 9 AM UTC) or weekly digests (every Monday at 9 AM UTC). You can also trigger an on-demand send from the dashboard at any time.

How do I use the developer API?

Generate an API token in your settings page (tokens start with bm_). Then call GET https://bookmarks.md/api/v1/bookmarks with an Authorization: Bearer bm_YOUR_TOKEN header. Optional query params: q (search), author (filter by username), cursor (pagination), limit (1–100).

Can AI agents access my bookmarks?

Yes. bookmarks.md includes a SKILL.md file at https://bookmarks.md/.well-known/skills/default/skill.md that AI agents (Claude, ChatGPT, etc.) can consume to discover the API. Generate an API token in your settings, share it with the agent, and it can call GET /api/v1/bookmarks using Bearer token auth.

How many API tokens can I create?

You can generate up to 5 API tokens from your settings page. Tokens are revocable, display their last-used time, and can be named for easy identification.

Is bookmarks.md free to use?

Yes, bookmarks.md is free for personal use. API usage is subject to a rate limit of 100 requests per minute per user.

Documentation — bookmarks.md

Features

What bookmarks.md does

Bookmark Syncing

Automatically fetch and store your X bookmarks in a structured database.

One-click sync from the dashboard — pull all new bookmarks since your last sync
Incremental fetching via high-water mark (never re-reads old bookmarks)
Stores full tweet text, author info, profile images, and direct URLs
Supports the full X Bookmarks API v2 with token auto-refresh

Email Digests

Receive your bookmarks as a beautifully formatted email — daily or weekly.

Choose between daily (every day at 9 AM UTC) or weekly (every Monday at 9 AM UTC)
Each email includes author avatars, full tweet text, and direct links to the original posts
On-demand sending — don't want to wait? Hit the button in your dashboard
Powered by React Email + Resend for reliable, gorgeous delivery

Bookmark Library

Browse, search, and filter through all your synced bookmarks.

Full-text search across tweet content, author names, and usernames
Filter by specific author to see all bookmarks from one person
Cursor-based pagination for smooth, efficient browsing
Direct links back to the original post on X

Developer API

Access your bookmarks programmatically with API tokens.

Generate up to 5 API tokens from the settings page
RESTful JSON API with search, filtering, and pagination
Perfect for AI agents, CLI tools, custom integrations, and automations
Tokens are revocable and track last-used time

AI Agent Integration

Built to be AI-friendly from day one.

Includes a SKILL.md file that AI agents (Claude, Codex, etc.) can use to understand the API
Simple Bearer token auth — easy for any agent to call
Structured JSON responses — no HTML scraping needed
Designed for common agent workflows: fetch all, search, filter by author

Smart Tracking

Efficient syncing that respects your API quotas and avoids duplicates.

High-water mark system tracks the last synced bookmark ID
Only fetches new bookmarks on each sync — no redundant API calls
Deduplication via INSERT OR IGNORE — bookmarks are never stored twice
OAuth tokens refresh automatically before expiry

Developer API

API Reference

Access your bookmarks from any tool, script, or AI agent. Generate a token in your settings and use it as a Bearer token.

GET/api/v1/bookmarksAPI Token

Fetch your bookmarks with optional search, author filtering, and pagination.

param	type	description
q	string	Search text, author name, or username
author	string	Filter by exact X username
cursor	string	Pagination cursor from previous response
limit	1–100	Results per page (default 50)

Example request

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

Example response

{
  "bookmarks": [
    {
      "tweetId": "1893847562001",
      "text": "TypeScript 5.7 just dropped...",
      "tweetUrl": "https://x.com/typescript/status/1893847562001",
      "authorName": "TypeScript",
      "authorUsername": "typescript",
      "createdAt": "2025-02-01T10:00:00.000Z",
      "savedAt": "2025-02-01T14:30:00.000Z"
    }
  ],
  "nextCursor": null,
  "total": 1
}

Digest Emails

Delivery options

Daily Digest

Runs every day at 9:00 AM UTC. Syncs your latest bookmarks and sends them immediately. Ideal if you bookmark frequently and want a daily reading list.

Weekly Digest

Runs every Monday at 9:00 AM UTC. Collects an entire week's worth of bookmarks into one email. Great for a weekly catch-up without inbox noise.

On-demand sending

Don't want to wait? Click “Send Digest Now” from your dashboard to instantly sync your latest bookmarks and send them to your email. This works regardless of your frequency setting.

AI Agents

Agent-friendly by design

bookmarks.md includes a skill.md file that AI agents can consume to understand how to interact with the API. Following the open standard, it's served at the canonical well-known URL for automatic agent discovery.

Setup for agents

1Generate an API token at /dashboard/settings
2Share the token with your agent (they start with bm_)
3The agent calls GET /api/v1/bookmarks with the token as a Bearer header

Fetching the skill file

AI agents can fetch the skill definition from the well-known URL, or install it using the skills CLI:

Well-known URL

https://bookmarks.md/.well-known/skills/default/skill.md

Install via skills CLI

npx skills add https://bookmarks.md

The file returns raw markdown that agents can parse to learn the API endpoints, authentication method, and common workflows. A short redirect is also available at /docs/skill.

Common agent workflows

Fetch all bookmarks: Paginate through all results using the nextCursor field until it returns null.

Semantic search: Use the q parameter to find bookmarks matching a topic, then reason over the results.

Author analysis: Filter by author to see all bookmarks from a specific person.

Everything about
bookmarks.md

What bookmarks.md does

Bookmark Syncing

Email Digests

Bookmark Library

Developer API

AI Agent Integration

Smart Tracking

API Reference

Delivery options

Daily Digest

Weekly Digest

On-demand sending

Agent-friendly by design

Setup for agents

Fetching the skill file

Common agent workflows

Ready to get started?