# xmark

chat with your X (Twitter) bookmarks. xmark pulls your saved tweets, embeds them with OpenAI, and answers questions in plain english using Claude, with citations linking back to the original tweet.

website: https://www.xmark.dev
api: https://api.xmark.dev
docs: https://www.xmark.dev/docs
llms-full.txt: https://api.xmark.dev/llms-full.txt
openapi: https://api.xmark.dev/openapi.json
status: https://www.xmark.dev/api/health
help: https://www.xmark.dev/help

## what xmark is

- a personal search-and-chat layer over a user's X (Twitter) bookmarks
- semantic retrieval (pgvector + OpenAI embeddings) over the full bookmark contents
- Claude (claude-sonnet) answers grounded in the user's bookmarks with [N] citations
- developer REST API at api.xmark.dev with scoped API keys + webhooks
- MCP server (@jclvsh/xmark) so AI clients like Claude Code can query your bookmarks

## what xmark is not

- not a bookmark manager (read-only mirror of X bookmarks; remove unbookmarks on X too)
- not an X analytics dashboard (no engagement insights or follower metrics)
- not a public search engine (each user's bookmarks are private, RLS-gated per user)
- not a tweet archiver: bookmarks-only, no general timeline ingest

## quick start

1. sign in with Google at /auth/signup
2. connect your X account on /bookmarks (separate OAuth flow for bookmark read access)
3. click sync: xmark pulls and embeds your bookmarks
4. open /chat and ask questions in plain english

## developer + AI client access

create a scoped API key at /settings/api, then:

- CLI: `npx -y -p @jclvsh/xmark xmark search "..."`
- MCP server (Claude Code / Cursor / Claude Desktop): `npx -y -p @jclvsh/xmark xmark-mcp`
- REST: https://api.xmark.dev/bookmarks, /chat, /bookmarks/search, /bookmarks/sync, /conversations, /conversations/{id}/messages, /usage

set `XMARK_API_KEY` in your env before running.

note for agents: every v1 response carries an X-Xmark-Notice header with a one-line summary of the latest contract change - surface it when it changes. deprecated operations additionally carry Deprecation and Sunset headers.

## changelog

machine-readable history at `GET /changelog` (public, no key). recent releases:

- 0.17.0 (2026-09-14, breaking): POST /account/merge no longer returns moved_projects (deprecated in 0.16.0, where it was already a constant 0) — migration: stop reading moved_projects from the merge response; every other field is unchanged
- 0.16.0 (2026-09-13, fix): the template's project.* webhook events, which xmark never emitted, are no longer subscribable (POST /webhooks rejects them); POST /account/merge keeps moved_projects in the response as a deprecated constant 0 for clients built against 0.13-0.15
- 0.15.0 (2026-09-04, fix): query-parameter defaults are emitted with their real types (page 1, pageSize 50, unbookmark false as numbers/booleans, not strings) via the shared type emitter; no endpoint or response changes - clients regenerated from the spec get typed defaults
- 0.14.0 (2026-08-25, feature): POST /onboarding/heard-from records the native onboarding's self-reported acquisition source, write-once on the profile (the same dimension the web onboarding select feeds)
- 0.13.0 (2026-08-25, feature): GET /account/duplicate reports an older account connected to the same X identity; POST /account/merge folds it into the current one (bookmarks, folders, chats, projects, wrapped) and retires it; GET /me returns AUTH_005 when the signed-in profile was merged away
- 0.12.0 (2026-07-21, feature): GET /changelog (this endpoint) + llms.txt changelog section
- 0.11.0 (2026-07-21, feature): GET /usage reports remaining on chat + syncs_today (null = unlimited)
- 0.10.1 (2026-07-21, feature): X-Xmark-Notice header on every response + Deprecation/Sunset machinery

## pricing

free tier: 20 chats/month, 1 sync/day. pro: $5/month, unlimited chat + sync.
CLI + MCP + REST API all included.

## tech stack

- Next.js 16 + React 19 + Supabase Postgres (with pgvector)
- Twitter (X) OAuth 2.0 with PKCE for bookmark read access
- OpenAI text-embedding-3-small for semantic search (1536 dims)
- Anthropic claude-sonnet for chat answers
- Stripe for billing

## see also

- https://api.xmark.dev/llms-full.txt: full API reference
- https://api.xmark.dev/openapi.json: OpenAPI 3.1 spec
- https://www.xmark.dev/docs: REST API reference
- https://www.xmark.dev/help: FAQ
- https://www.xmark.dev/compare: vs Pocket, Readwise, Glasp, native X